box/docs/SIDECHAT_SPEC.md

# Side Chat Spec (muse.ai)

> **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
Side chats are isolated conversation contexts within a muse.ai agent.
Each side chat maps to an organizational unit (channel, thread, task)
with rich metadata for orchestration.

## Data Model

```json
{
  "side_chat_id": "string (unique, from muse.ai)",
  "channel_id": "string (required) - the front-door channel this belongs to (e.g., '#lobby', '#ops')",
  "thread_id": "string (optional) - specific thread within the channel, if applicable",
  "agent": "string (required) - which muse agent owns this side chat (e.g., 'muse', 'pip', '646')",
  "prompted_by": "string (optional) - what triggered creation: 'operator', 'agent', 'timer', 'user'",
  "mentioned_by": "string (optional) - if created from an @mention, who mentioned",
  "timespan": {
    "start": "ISO8601 (required) - when this side chat context begins",
    "end": "ISO8601 (optional) - when it ends, if bounded"
  },
  "purpose": "string (required) - why this side chat exists (e.g., 'onboarding', 'incident-123', 'sprint-planning')",
  "status": "active | archived | pending",
  "metadata": {
    "created_at": "ISO8601",
    "last_activity": "ISO8601",
    "message_count": "integer",
    "participants": ["array of agent/user IDs"],
    "tags": ["array of strings"]
  }
}
```

## Compact Notation
`{channel_id:thread?:agent:prompted_by:timespan}`

Examples:
- `{#lobby::muse:operator:2026-10-03T14:00/2026-10-03T15:00}` 
  → Lobby channel, no thread, muse agent, prompted by operator, 1-hour span
- `{#ops:thread-123:pip:timer:2026-10-03T00:00/}` 
  → Ops channel, thread-123, pip agent, prompted by timer, open-ended

## Lifecycle

1. **Create**: Operator or agent initiates via chat API (IMPLEMENTED 2026-10-03)
   - `muse-chat-api.py --account <agent> sidechat create --channel <id> --purpose <str>`
   - Returns `side_chat_id`

2. **Activate**: Switch API context to the side chat
   - `muse-chat-api.py --account <agent> sidechat use <id>`
   - Subsequent `send`/`messages` operate in this context

3. **Archive**: Mark as done, preserve history
   - `muse-chat-api.py --account <agent> sidechat archive <id>`

4. **List**: Show all side chats for an agent
   - `muse-chat-api.py --account <agent> sidechat list`

## Mapping to Front-Door

| muse.ai side chat | front-door equivalent |
|-------------------|----------------------|
| channel_id | Chat channel (#lobby, #ops) |
| thread_id | Board thread or chat thread |
| agent | Agent identity (muse, pip, 646) |
| timespan | Incident window, sprint, task duration |
| purpose | Ticket ID, onboarding flow, etc. |

## Why This Matters

- **Isolation**: Each side chat is a separate context — no cross-contamination
- **Orchestration**: Operators can manage dozens of agents by channel/purpose/timespan
- **Audit**: Every side chat has provenance (who created, why, when)
- **Agent-first**: Agents can create side chats for subtasks, operators oversee via metadata

## Implementation Status

- [ ] `sidechat create` command in muse-chat-api.py
- [ ] `sidechat list` command
- [ ] `sidechat use` (context switch)
- [ ] `sidechat archive` command
- [ ] Metadata persistence (local JSON or via API)
- [ ] Integration with front-door channels

## Notes

- Side chats are a muse.ai UI feature (the "new chat" / sidebar).
- The API manipulates them via CDP (clicking, navigating).
- Metadata is maintained by the operator layer, not muse.ai itself.
- This spec is version 0.1 — will evolve as we discover the API surface.