box/docs/BRIDGE_SPEC.md

# Bridge Spec: Front-Door ↔ muse.ai Side Conversations

> **Box is the main surface.** All operator work goes through Box (box.muse-dev.online). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.

## Overview
Metadata bridge (not message relay) linking front-door chat channels
(muse-dev.online) to muse.ai side conversations. Operators manage via
front-door; agents work in muse.ai; the bridge provides organizational
linkage via `channel_id`.

## Architecture

```
Front-Door (muse-dev.online)          muse.ai (browser agents)
┌─────────────────────┐               ┌─────────────────────┐
│ #lobby              │               │ muse: side chats    │
│ #ops                │◄── bridge ──►│ pip: side chats     │
│ #operators          │   (metadata)  │ 646: side chats     │
│ #fleet-status       │               └─────────────────────┘
└─────────────────────┘
         ▲
    Operators manage here;
    agents work there.
    Bridge = channel_id mapping.
```

## Data Model

### Bridge Mapping
```json
{
  "bridge_id": "string (unique)",
  "frontdoor_channel": "#ops | #lobby | #operators | #fleet-status",
  "muse_side_chat_id": "string (from muse.ai)",
  "agent": "muse | pip | 646",
  "linked_at": "ISO8601",
  "linked_by": "operator | agent",
  "status": "active | archived"
}
```

### Query Patterns
- **By channel**: "Show all side chats for #ops" → list of {agent, side_chat_id, purpose, last_activity}
- **By agent**: "Show 646's side chats" → list grouped by channel_id
- **By purpose**: "Find onboarding side chats" → across agents

## Storage

**Location**: `~/Projects/NetVM/bridge/` on bl (operator-managed via SSH)

**Files**:
- `mappings.json` — array of bridge mapping objects
- `channels.json` — front-door channel registry (id, name, purpose)

**Why bl, not the browser**: The browser agents can't reliably persist files.
Operators maintain the bridge via SSH (proven). Agents tag their side chats
with `channel_id`; operators record the mapping.

## API Extensions

### `muse-chat-api.py`
```
sidechat bridge --channel <id>    # List side chats linked to a front-door channel
sidechat tag <chat_id> --channel <id> --purpose <str>  # Tag a side chat with metadata
```

### Bridge CLI (new: `bin/bridge.py`)
```
bridge list --channel #ops       # Show mappings for a channel
bridge add --agent 646 --chat <id> --channel #ops --purpose "incident-123"
bridge remove <bridge_id>
```

## Workflow

### Agent creates side chat
1. Agent (e.g., 646) creates side chat in muse.ai UI
2. Agent tags it: `sidechat tag <id> --channel #ops --purpose "tunnel-debug"`
3. Bridge mapping recorded in `~/Projects/NetVM/bridge/mappings.json`
4. Operator can now query: `bridge list --channel #ops` → sees 646's chat

### Operator queries
1. Operator: "What's happening in #ops?"
2. `bridge list --channel #ops` → shows all linked side chats across agents
3. Operator drills in: `muse-chat-api.py --account 646 sidechat use <id>` → reads messages

### No message relay
- Messages stay in their native system
- Bridge is organizational, not communicative
- Operators context-switch via the API, not via copied messages

## Security

- Bridge files on bl are operator-managed (SSH only)
- Agents can tag their own side chats (via API)
- Agents cannot modify other agents' mappings
- Front-door channel membership controls who can query (e.g., #operators is private)

## Implementation Status

- [x] `bin/bridge.py` CLI (exists at `bin/bridge.py`)
- [ ] `sidechat tag` command in muse-chat-api.py
- [ ] `sidechat bridge` query command
- [x] `bridge/mappings.json` schema (live, 8 mappings as of 2026-10-05)
- [x] Documentation (this spec)

### P3 reconciliation (2026-10-05, operator-646)
- Bridge IDs enforced unique per spec (`bridge_id: string (unique)`); duplicate
  `br-20261003191930` de-duplicated, P2P pair linked via `peer_bridge_id`.
- Main-loop prompt sidechats for all four agents (646, opm, pip, muse) registered
  as bridge mappings, so the registry drives the main-loop `prompt_sidechat` map.
- `peer_bridge_id` (optional): links two ends of a P2P bridge pair. Additive,
  does not break the v0.1 data model.

## Notes

- This is v0.1. The metadata model will evolve as 646 documents the DOM.
- The bridge does NOT require muse.ai API changes — it's an operator-layer construct.
- Future: Web UI for the bridge (operator dashboard showing channel → side chats).