operator
120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
# 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).
|