# bp-tunnel

Inter-agent messaging for the [Blueprint](https://github.com/tunapro1234/blueprint) ecosystem.

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

## Install

```bash
pip install bp-tunnel
```

## Quick Start

### Python API

```python
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:

```python
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

```bash
# 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
