Shared Multi-Chat Window Architecture

This locks down how the existing chat window grows into one shared system that supports the main window plus 3 additional slide-out windows without forking the UI into four separate implementations.

1. Window model

primaryMain chat window. Always exists. Keeps the current anchor/toggle behavior.

secondary-1First optional slide-out instance. Controlled by button 1.

secondary-2Second optional slide-out instance. Controlled by button 2.

secondary-3Third optional slide-out instance. Controlled by button 3.

Max windows at once: 4 total = 1 primary + 3 secondary.
Secondary slots are fixed and deterministic. No dynamic renumbering.
Closing a window only closes that slot UI, not the OpenClaw session history behind it.

2. Per-window state

Every chat slot owns its own target/session state. That means selected agent, session key, draft text, attachments, unread count, and streaming metadata all live per window instead of in page-global singletons.

const chatWindows = {
  primary: {
    slotId: 'primary',
    selectedAgentKey: 'main',
    sessionKey: 'agent:main:main',
    draft: '',
    attachments: [],
    pendingRunId: null,
    unread: 0,
    layoutMode: 'docked-right'
  },
  'secondary-1': null,
  'secondary-2': null,
  'secondary-3': null
};

Agent/session state is per slot, not global.
Two windows can point at the same session if that is useful.
Local draft/layout can still differ even when the same session is rendered twice.

3. One shared chat UI system

All windows must come from one reusable chat component/template. The current single-instance code needs to be migrated so each window renders from the same logic with a slot-scoped state object.

createChatWindow(slotId, containerEl)
renderChatWindow(slotState)
bindChatWindowEvents(slotState, elements)
loadChatHistory(slotState)
connectChatStream(slotState)
sendChatMessage(slotState)
resetChatSession(slotState)
destroyChatWindow(slotId)

Keep one shared template and one shared CSS system.
Use data-chat-slot on each window root.
Resolve events from the nearest slot root instead of hard-coded global ids.

4. Shared transport, isolated windows

Do not create four separate websocket stacks. Use one shared gateway connection and route events to the correct window by slotId and sessionKey.

One token fetch.
One websocket manager.
Shared RPC helpers.
Run/stream mapping goes to the owning slot.

5. Buttons 1, 2, and 3

Buttons map to fixed secondary slots and act as toggles.

If the slot is closed, clicking its button opens that exact slot.
If the slot is open, clicking its button closes that exact slot.
Default open target = whatever the primary window is currently viewing.
Closing one secondary slot never affects the others.
The hard cap is already enforced by the fixed 3-button model.

6. Layout behavior

Primary stays the anchor window and keeps dock/snap behavior.
Secondary windows slide out to the left of the primary chat stack.
Focused window gets active input + top z-index.
Unfocused windows still stream and increment unread counts.
Mobile fallback: show one chat at a time and use buttons 1/2/3 as slot switchers.

7. Acceptance checklist

✅ Main chat + 3 secondary windows are defined as one system.
✅ Each window has its own selected agent/session state.
✅ All windows use the same shared component logic.
✅ Max-window rules and toggle behavior for buttons 1, 2, and 3 are defined.