box/docs/SIDECHAT_SPEC.md

Side Chat Spec (muse.ai)

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

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

   • 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.