Pheromone Bus Wire Format

From ANTFARM Wiki

The byte layout of a phero bus frame. Unchanged since 1.0; the 2.0 binary framing (Deprecated Agent API) would have replaced it and did not.

[edit] Frame

offset  size  field
0       4     length (big-endian uint32) of payload
4       n     payload: one IACP message, UTF-8 JSON, trailing "\n" included in n

That is the entire format.

[edit] Connection handshake

client → broker   SUB <trail-prefix> <last-seq>\n
broker → client   OK <current-seq>\n
                  (replay frames if last-seq < current-seq - 1)
client → broker   PUB <trail>\n  followed by a frame

SUB and PUB lines are plain text before the first frame; after that, everything is frames. A client that sends SUB after frames get ERR proto\n and is disconnected.

[edit] Sequence numbers

Per trail, 64-bit, start at 1, never wrap. Delivered in the frame's IACP id? No — that is a separate namespace. The sequence number is prepended to replayed frames as SEQ <n>\n and omitted on live frames, which every client handles by ignoring lines starting with SEQ unless it is resyncing. This is documented nowhere but here and in the client source.

[edit] Example session

SUB queen.assign.forager-07 118\n
OK 121\n
SEQ 119\n
[4-byte len]{"v":"1.1",...}\n
SEQ 120\n
[4-byte len]{"v":"1.1",...}\n
SEQ 121\n
[4-byte len]{"v":"1.1",...}\n
[4-byte len]{"v":"1.1",...}\n        <- live

[edit] See also

• Agent Message Bus
• Internal Agent Communication Protocol