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

{
  "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

• bin/bridge.py CLI (exists at bin/bridge.py)
• sidechat tag command in muse-chat-api.py
• sidechat bridge query command
• bridge/mappings.json schema (live, 8 mappings as of 2026-10-05)
• 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).