bp-tunnel 0.2.0

Inter-agent messaging for Blueprint ecosystem

bp-tunnel

Inter-agent messaging for the Blueprint ecosystem.

Lightweight tunnel system that lets AI agents (or any process) communicate through named channels with pluggable transport backends.

Install

pip install bp-tunnel

Quick Start

Python API

from bp_tunnel import FileTransport, Tunnel

transport = FileTransport()  # defaults to /tmp/bp-tunnel

# Agent 1: create tunnel and send
transport.create("my-tunnel", "alice")
alice = Tunnel("my-tunnel", "alice", transport)
alice.send("hello everyone")          # broadcast
alice.send("hey bob", to="bob")       # direct message

# Agent 2: join and receive
transport.join("my-tunnel", "bob")
bob = Tunnel("my-tunnel", "bob", transport)
msg = bob.receive()                   # non-blocking
msg = bob.wait_for(from_="alice")     # blocking wait

AI Tool Interface

Stateless dict-based functions for AI agent integration:

from bp_tunnel.tools import create_tunnel, join_tunnel, send_message, wait_for_message

# Agent creates a tunnel
result = create_tunnel("manager")
# {"tunnel_id": "a1b2c3d4", "agent": "manager", "role": "admin"}

# Another agent joins
join_tunnel("a1b2c3d4", "worker")

# Send and receive
send_message("a1b2c3d4", "manager", "build the feature", to="worker")
msg = wait_for_message("a1b2c3d4", "worker", from_agent="manager", timeout=30)
# {"status": "message", "from": "manager", "message": "build the feature", "ts": ...}

CLI

# Create a tunnel
bp-tunnel create --as alice
# prints: a1b2c3d4

# Join from another terminal
bp-tunnel join a1b2c3d4 --as bob

# Send messages
bp-tunnel send a1b2c3d4 "hello" --as alice
bp-tunnel send a1b2c3d4 "hey bob" --as alice --to bob

# Receive
bp-tunnel recv a1b2c3d4 --as bob
bp-tunnel recv a1b2c3d4 --as bob --from alice

# Listen continuously
bp-tunnel listen a1b2c3d4 --as bob

# Admin operations
bp-tunnel promote a1b2c3d4 bob --as alice
bp-tunnel demote a1b2c3d4 bob --as alice

# Info
bp-tunnel info a1b2c3d4
bp-tunnel ls

Features

• Multi-agent tunnels - any number of agents can join a channel
• Broadcast & direct messaging - to=None broadcasts, to="agent" sends direct
• Blocking patterns - wait_for() and send_wait() for turn-based workflows
• Admin system - creator is auto-admin, can promote/demote others
• Pluggable transport - abstract Transport base class, file-based included
• Selective filtering - from_ parameter filters without consuming other messages
• Atomic writes - tempfile + rename for crash safety
• File locking - fcntl locks for concurrent access
• Path traversal protection - strict name validation

Architecture

Python API / AI Tools / CLI
         |
    Tunnel (agent-centric wrapper)
         |
    Transport (abstract interface)
         |
    FileTransport (/tmp/bp-tunnel/)
         |
    Message (YAML format)

File Transport Layout

/tmp/bp-tunnel/
  {tunnel-id}/
    _meta.yaml        # {admins: [...], members: [...]}
    _meta.lock         # fcntl lock file
    {agent-name}/      # mailbox directory
      {timestamp}-{id}.yaml   # message files

License

MIT