Telepathy Bus & MCP Virtual Pager Specification¶
References: docs/architecture.md §2, docs/adr/0004-zero-copy-shm-telepathy-bus.md, docs/adr/0005-v1-1-0-workspace-trust-store-and-daemon.md, docs/security-and-threat-model.md
Target Crates: crates/icx-bus, crates/icx-adapters, crates/icx-cli
1. Purpose¶
When several agents (for example Claude Code and Codex) work in the same project, icx lets one
agent's high-surprise events (a compiler panic, a failing test) reach the others' next prompt.
crates/icx-bus provides the telepathy ring (SeqlockTelemetryBus): a fixed 256-slot ring of
event records with seqlock-validated reads.
icx v1.1.0 contains:
- The telepathy ring (
crates/icx-bus/src/ring.rs), with an in-process backend and a file-backed backend (§2). - A single-tool MCP pager (
icx mcp-serve,crates/icx-adapters/src/mcp.rs) that gives MCP clients dereference, slicing, search, recall, folding and bus access through one tool (§3).
The resident daemon's Unix socket (icx daemon, crates/icx-cli/src/daemon.rs) carries hook
requests only; it is described in docs/architecture.md §3.3. There is no
separate RPC protocol for CAS or graph queries.
1.1 What the bus is not¶
The v1.0.0 documentation described the bus as a lock-free, memory-mapped, zero-copy /dev/shm
segment (audit finding ICX-AUD-046). That does not match the code:
- The file-backed backend is not memory-mapped. It uses positional I/O (
pread/pwritethroughstd::os::unix::fs::FileExt::{read_exact_at, write_all_at}) on an ordinary file.mmapwould requireunsafe, which the workspace forbids. - It is not lock-free for writers. A file-backed writer takes an in-process
Mutexand then an exclusive advisory file lock (File::try_lock, retried up to 5,000 times at 50 µs, about 250 ms, before failing). Readers take no lock. - It is not zero-copy. Every publish and every read copies the slot through a buffer.
- The file is wherever it is configured. The default is
icx-fabric-v1.shminside the workspace directory;ICX_SHM_PATHoverrides it. It is on the/dev/shmtmpfs only ifICX_SHM_PATHpoints there.
2. Telepathy Ring¶
2.1 Backends¶
| Backend | Constructor | Scope | Synchronization |
|---|---|---|---|
BackingStore::InProcess |
SeqlockTelemetryBus::new_in_memory() |
Threads of one process | Atomic seqlock per slot; writers claim a sequence number with fetch_add and a slot with compare-and-swap. No mutex, no syscalls. |
BackingStore::SharedFile |
SeqlockTelemetryBus::open_shared_file(path) |
All processes that open the same file | Writers: in-process Mutex plus exclusive advisory file lock around the whole slot write. Readers: optimistic, lock-free, seqlock version check. |
Agent hooks and the MCP server use the file-backed backend, because each hook invocation is a separate process. The in-process backend is used by the benchmark and by tests.
2.2 Layout¶
The ring has a fixed size of 1,048,640 bytes: a 64-byte header followed by 256 slots of
4,096 bytes. All integers are little-endian.
Offset 0x0000_0000 .. 0x0000_003F (64 B): FabricHeader (magic, version, root seqlock, write_seq, active agent mask, DAG root)
Offset 0x0000_0040 .. 0x0010_003F (1,048,576 B): 256 slots x 4,096 B
pub const ICX_SHM_MAGIC: u64 = 0x4943_585F_4641_4231; // "ICX_FAB1"
pub const ICX_SHM_VERSION: u32 = 1;
pub const ICX_RING_SLOTS: usize = 256;
pub const ICX_AHTL_INLINE_CAP: usize = 3968; // inline AHTL payload bytes per slot
| Header field | Offset | Meaning |
|---|---|---|
magic |
0 | ICX_SHM_MAGIC |
version |
8 | ICX_SHM_VERSION; a mismatch fails with BusError::UnsupportedVersion |
root_seqlock |
12 | Version counter for global_dag_root |
write_seq |
16 | Number of committed events (next sequence number) |
active_agents_mask |
24 | Bit per AgentKind that has published |
global_dag_root |
32 | Latest 256-bit Merkle-DAG root |
Each slot holds: the seqlock word, timestamp_ms, artifact_id, workspace_hash, a packed
metadata word (agent kind, surprise_q8, payload length, packet kind), a 256-bit HDC sketch, a
16-dimensional Q15 fractal coordinate, padding, and up to 3,968 bytes of UTF-8 AHTL payload
(longer payloads are truncated). In-process slots are #[repr(C, align(64))] arrays of
AtomicU64 words.
2.3 Publish and Read Protocol¶
Writer, in-process (try_publish):
fetch_addonwrite_seqclaims sequence numberseq;slot = seq % 256.- The writer moves the slot's seqlock from an even value to
odd = (seq << 1) | 1with compare-and-swap. If the slot already holds a version>= (seq + 1) << 1, a later lap has overwritten it and the call returnsErr(BusError::SlotLapped). If the slot stays odd (held by a stalled writer) past the spin limit, it returnsErr(BusError::SlotContended). - The writer stores the payload with relaxed atomics between
AcqRelfences, then storeseven = (seq + 1) << 1withRelease.
Writer, file-backed (try_publish): under the mutex and file lock, the writer reads
write_seq, writes the odd version, writes the payload, writes the even version, and only then
advances write_seq. Writers are serialized, so the file-backed path does not lap itself.
Reader (poll_since, poll_workspace_since): for each sequence number after the cursor
(at most the last 256), the reader loads the seqlock (Acquire); an odd or zero value is skipped;
it copies the slot, loads the seqlock again, and accepts the record only if both loads match and
the version corresponds to the expected sequence number. poll_workspace_since additionally
filters on workspace_hash.
The file-backed reader relies on pwrite ordering through the page cache, which holds on Linux
but is not guaranteed by POSIX.
Crash behaviour: a writer killed mid-publish leaves its slot odd. Readers skip it; later writers
treat it as contended and drop their event with SlotContended rather than block. The file lock is
an OS advisory lock and is released when the process exits.
2.4 Loss Signalling¶
v1.0.0 returned success when an event was dropped (ICX-AUD-054). v1.1.0 makes loss observable:
| API | Behaviour |
|---|---|
try_publish(..) -> Result<u64, BusError> |
Returns the new sequence number, or SlotLapped / SlotContended / Io when the event was not committed. |
publish(..) -> u64 |
Infallible wrapper; counts every dropped event. |
dropped_publishes() -> u64 |
Number of events this handle failed to publish. |
poll_since_with_loss(since) -> (Vec<TelepathyEvent>, u64) |
Events after since, plus the number of sequence numbers that could not be delivered (overwritten before the reader caught up, or torn and skipped). A non-zero count means the reader must not assume it saw every event. |
Tests: crates/icx-bus/tests/loss_signalling.rs.
2.5 File Open Hardening¶
open_shared_file (ICX-AUD-019):
- opens with
O_NOFOLLOW | O_CLOEXEC, creating the file with mode0600; - refuses (
BusError::InsecurePermissions) a path that is not a regular file, is owned by another uid, or has any group or other permission bits, instead of silently tightening it; - refuses a file whose header has the wrong magic (
InvalidMagic) or version (UnsupportedVersion); a new or zero-magic file is initialized under the file lock.
2.6 Measured Latency¶
Measured on the development machine (Intel i9-10850K, Linux):
| Path | Result | Source |
|---|---|---|
| In-process publish | 58.3 ns per slot over 1,000 publishes | icx benchmark (synthetic, single thread) |
| File-backed publish to visible in a second handle | worst case 38 µs over 200 events | two-handle test modelling two agent processes (ICX-AUD-055) |
These are component measurements, not end-to-end agent latencies. A writer waiting on the file lock can take up to about 250 ms before failing.
3. Single-Tool MCP Pager (icx mcp-serve)¶
icx mcp-serve runs a JSON-RPC 2.0 server over stdio, one JSON message per line. It registers one
tool, icx, whose schema is estimated at under 180 tokens
(McpPagerServer::schema_token_estimate):
{
"name": "icx",
"description": "Infinity-Context MMU syscall: deref #icx:<id>, slice lines, grep cold CAS, associative recall, fold/expand branch, or poll/broadcast /dev/shm bus.",
"inputSchema": {
"type": "object",
"required": ["op"],
"properties": {
"op": {
"type": "string",
"enum": ["deref", "slice", "grep", "recall", "fold", "expand", "xagent", "status"]
},
"id": { "type": "string" },
"q": {
"type": "string",
"description": "Search pattern for grep/recall, 'begin:<label>' or '<summary>' for fold, or message for xagent."
},
"range": { "type": "array", "items": { "type": "integer" } },
"k": { "type": "integer" },
"provenance": { "type": "boolean" }
}
}
}
3.1 Operations¶
deref: full stored text ofid(#icx:<16-hex>or#icx:<12-hex>), framed (§3.3).slice: linesrange[0]..=range[1](1-based, inclusive) ofid, framed.grep: patternqoverid, or over all artifacts in the workspace whenidis omitted.recall: associative recall forq(HDC two-stage index), returning AHTL packets and handles;klimits the result count.fold:q = "begin:<label>"opens a sub-trajectory branch;q = "<summary>"closes the innermost open branch into anL2folded node.expand: expands a folded branch.xagent: publishes a message to, or polls, the telepathy ring for the current workspace.status: DAG, epoch, index and ring status.
The tool description says /dev/shm; the ring is at the configured path (§1.1).
3.2 Protocol Versions (ICX-AUD-008)¶
The server supports two protocol eras:
- Legacy handshake.
initializenegotiates2025-11-25,2025-06-18,2025-03-26or2024-11-05: the server echoes the client's version when it is supported and otherwise answers with2025-11-25. - Stateless (
2026-07-28).server/discoveris supported; each request carries its version in_meta["io.modelcontextprotocol/protocolVersion"]; results carryresultTypeand_meta.serverInfo. An unsupported version returns error-32022.
Constants: LEGACY_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS in
crates/icx-adapters/src/mcp.rs.
3.3 Provenance Framing¶
Dereferenced content is untrusted data. deref output always starts with a provenance header,
followed by the Tier-0-escaped body:
⟪ICX:PROVENANCE│id=<handle>│redacted=<bool>│exactness=post_redaction_cas│trust=untrusted_data⟫
<escaped body>
exactness=post_redaction_cas states that the bytes are exactly what the CAS stored, which is the
tool output after secret redaction. icx deref on the command line uses the same framing by
default; icx deref --raw prints the exact stored bytes.
3.4 Bounds¶
| Bound | Value | Constant |
|---|---|---|
| MCP stdio line length | 4 MiB | MAX_MCP_LINE_BYTES (crates/icx-cli/src/main.rs) |
Open nested fold begin: branches |
64 | MAX_FOLD_DEPTH (crates/icx-adapters/src/mcp.rs) |
| Hook stdin | 64 MiB + 64 KiB envelope | MAX_STDIN_BYTES (crates/icx-cli/src/main.rs) |
Tests: crates/icx-adapters/tests/mcp_bounds.rs; fuzz target fuzz/fuzz_targets/mcp_jsonrpc.rs.