Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs(switchdash): map the sidebar's state model and its broken paths (CHOO-1943)
Louis Amaudruz07328f5567d5
diff --git a/dash/docs/sidebar-state-model.md b/dash/docs/sidebar-state-model.mdnew file mode 100644index 000000000..03a8f8b84--- /dev/null+++ b/dash/docs/sidebar-state-model.md@@ -0,0 +1,204 @@+# Sidebar state model — audit and target design (CHOO-1943)++Status: **design note, pre-implementation.** Part 1 and 2 are the audit of what+exists today. Part 3 is the proposed target. Nothing here is implemented yet.++Scope: the left sidebar, rooms view first, but the plumbing is shared with the+agents view and the servers section so both are covered.++## The thesis++The sidebar does not have a state model. It has five independent caches, filled+by four different mechanisms, refreshed on triggers that do not line up. Every+reported symptom is a place where two of them are read side by side and+disagree.++The fix is not to add refresh calls at the places that currently look wrong.+It is to make each fact have one owner and one read, so that two parts of the+view cannot hold different answers to the same question.++## Part 1 — What the sidebar shows, and where each fact comes from++Five stores back the rooms view. Two of them are both called+`switchRoomsStore`, are unrelated, and are imported into the same file under+different aliases.++| # | Store | Holds | Source | Kind |+|---|---|---|---|---|+| A | `switch-rooms/switch-rooms-store` | session → connected room | main process, seeded once + live event | push |+| B | `switch-servers/switch-rooms-store` | room catalogue + **per-agent** membership | gateway HTTP | pull |+| C | `locations/stores/agents-store` | this install's agents | main process (SQLite) | pull |+| D | session manager / session stores | sessions and their status | main process, live events | push |+| E | `switch-servers-store` | server connection status | gateway HTTP | pull |++Plus **react-query**, used by the invite picker only, as a sixth cache holding a+sixth copy of room membership.++### Per rendered element++| Rendered | Read from | Refreshed by |+|---|---|---|+| Room rows (which rooms exist) | B `allRoomsByServer` / `ownedRoomsByServer`, unioned with membership keys and session buckets | mount, window focus, create-room, add-agent |+| Room name, bridge icon, channel link, createdAt | B `roomNames` etc. | same as above |+| **Number badge on a room row** | **D + A** — count of live sessions bucketed into that room | session events (push, continuous) |+| **Agent rows under a room** | **B `roomsByAgent`, inverted** | mount, window focus, add/remove agent |+| Agent display name on those rows | react-query, per row | own query lifecycle |+| Sessions under an agent-in-room | D | session events |+| Agent status dot | D, via `sessionAgentStatusChangedChannel` | push, continuous |+| Server status dot | E | mount, window focus, login/logout |+| Room ordering | local view-state | drag, persisted debounced |+| Expand/collapse | local view-state | user |++### The shape problem++Membership is stored **agent-keyed** — "which rooms is this agent in?" — and the+rooms view needs the opposite — "who is in this room?". It gets there by+inverting the per-agent cache at render time.++That inversion is only as complete as the set of agents that happen to be in the+cache, and that set is only ever this install's **local** agents. Two facts+follow, and they cause most of the observed bugs:++1. A room's member list can only ever contain agents that exist locally in this+ switchdash. Server-side agents are structurally unrenderable.+2. A membership that was never fetched, and a membership that failed to fetch,+ both read as "this agent is in no rooms" — indistinguishable from the truth.++## Part 2 — Mutation → view paths, and which are broken++Legend: ✅ converges · ⚠️ converges only on window focus · ❌ never converges++| # | Mutation | Path today | |+|---|---|---|---|+| 1 | Add agent to room (local agent) | modal refetches memberships + room list | ✅ |+| 2 | **Add agent to room (agent not local to this install)** | picker offers it, sidebar can never draw it | ❌ |+| 3 | Remove agent from room | refetch after RPC | ✅ |+| 4 | Create room in-app | refetches room list | ✅ |+| 5 | **Room archived / renamed / deleted** | no in-app path exists; only happens externally | ⚠️ |+| 6 | **Agent created after the sidebar mounted** | membership load runs once on mount with a fixed agent list; the retry helper only refreshes keys already cached | ⚠️ |+| 7 | Agent deleted | agents store reloads | ✅ |+| 8 | **Membership changed externally** (Slack, gateway, another install) | nothing observes it | ⚠️ |+| 9 | **Server becomes unreachable** | room list keeps last-known values silently | ❌ (never disclosed) |+| 9b | **Sign in to a server** | the room load skips disconnected servers and login does not re-run it | ⚠️ (rooms simply absent until focus) |+| 10 | **Membership fetch fails** | agents silently vanish from their rooms | ❌ (never disclosed, never retried) |+| 11 | **Session→room seed fails at boot** | flag is set before the call and there is no error branch, so every badge reads 0 forever | ❌ |+| 12 | Drag-to-reorder | local view-state, applied immediately | ✅ |+| 13 | Session starts/stops/changes room | live events | ✅ |++### The two reported symptoms, explained++**Counter and children disagree.** The badge counts *sessions*; the list under it+shows *members*. Different collections, different stores, different refresh+triggers. A room with three members and nothing running shows three rows above a+badge reading `0`; one agent running two sessions shows one row above a badge+reading `2`. They are not the same question, so no amount of refreshing makes+them agree.++Worth noting: the gateway already returns a real member count per room. It+reaches the renderer's types and is read by nothing.++**Picker doesn't reflect membership.** The picker asks the server the room-keyed+question directly and lists *every* agent on the server. The sidebar asks the+agent-keyed question about *local* agents only. Two different questions, two+different caches. So the picker can correctly hide someone the sidebar cannot+show, and correctly offer someone the sidebar will never draw once added.++Also, when the picker's member lookup fails it treats the room as empty: it+offers agents already in it, and can display "every agent on this server is+already in the room" when in fact it simply failed to ask.++### Two more worth fixing while here++- **Agent filters silently narrow room membership.** The member list is built by+ walking the filtered agent list, so a filter set in the agents view removes+ members from rooms in the rooms view — while the rooms view's own filter+ indicator reads "off". It also suppresses the membership fetch for those+ agents entirely.+- **A room known only through membership renders degraded**: short-id label+ instead of its name, no bridge icon, and both "add agent" and "remove agent"+ silently refuse, because the fields those need are filled by a different fetch.+- **Signing in to a server does not load its rooms.** The room load skips+ servers that are not connected, and nothing re-runs it after login — so a+ server you just signed into contributes no rooms until the window is+ refocused. Same for starting the managed stack.++## Part 3 — Proposed target++### 3.1 One owner per fact++Introduce a single room-state store that owns the room-keyed view of the world,+replacing the render-time inversion:++- `rooms: Map<roomId, RoomState>` where `RoomState` carries the room's identity+ **and** its member list, from one read.+- Membership is fetched **room-keyed** (the endpoint the picker already uses),+ not derived by inverting per-agent caches.+- The per-agent view, where it is still needed, is derived *from* this — not+ alongside it.++### 3.2 Derive rendered numbers from the rendered collection++The badge becomes the length of the collection rendered beneath it. Not a+separate fetch, not the gateway's count, not a session tally. If the row shows+N children, the badge says N — they cannot disagree because there is one array.++Where the gateway's count is genuinely useful is as a **reconciliation signal**,+not as the number: if the server says a room has five members and we can only+render three, that gap is the "agents we cannot draw" case above, and it should+be disclosed on the row rather than silently rendered as three.++### 3.3 Refresh strategy — one rule, uniformly++**No room state reaches the UI by push today** — the renderer is told when a+session changes room, and nothing else. But the plumbing is closer than it+looks, and this is worth knowing before choosing: the main process **already+holds a gateway event stream**, and it **already receives room-join events**.+They are consumed by injecting a line into the agent's terminal and are never+re-emitted to the renderer. The stream is currently per-agent and filtered to+addressed events, so it is not a general room-state feed as-is — turning it into+one needs work on both sides, not just here.++So push is a real option later, not a free one now. The proposal below is+correct either way and leaves a clean seam for it.++Proposed, in order of preference per trigger:++1. **Invalidate on mutation.** Every room mutation invalidates the affected+ room's entry and re-reads it — one code path, not per-callsite refetch calls.+2. **Reconcile on focus**, as today, but as one coherent pass over the whole+ room state rather than three independent refreshes that can half-fail.+3. **No optimistic writes** for membership. The current fire-then-refetch is+ correct and should stay; optimism here would add a fourth kind of truth.+4. **External changes converge on the focus reconcile**, and the UI says how+ fresh it is rather than implying it is live.++This is the decision `CHOO-1868` (stale agent-status indicators) should inherit+rather than reinvent — that ticket is the same defect class for a different+fact, and the two must not end up with competing refresh models. If a room-state+push channel is ever added server-side, it slots in at (1) and the rest stands.++### 3.4 Fail loud on stale++The rule: **"I don't know" must be renderable.** Today it is not — every unknown+collapses to an empty array and renders as a confident zero.++- A membership that has never loaded, failed to load, or belongs to an+ unreachable server renders as *unknown*, not as empty.+- The room row discloses it, and the failed read is retried rather than being+ dropped from the retry set because it has no cache entry.+- The picker refuses to claim "everyone is already in the room" when the lookup+ that would prove it failed.+- The boot seed for session→room gets an error branch instead of wedging.++## Open questions for review++1. **Scope.** Part 3.1 is a real refactor of how the rooms view gets its data.+ The alternative is to fix 3.2 and 3.4 only, which kills the two reported+ symptoms and the silent-empty class, but leaves membership agent-keyed and+ leaves case 2 (non-local agents) unfixable. Worth doing the full thing?+2. **Non-local agents.** Should a room list members this install has no local+ agent for — as read-only rows — or keep them out and just disclose the gap?+ Listing them is the honest answer but it changes what the sidebar is.+3. **Polling.** Focus-only reconcile means a switchdash left open in the+ foreground never notices external changes. Add a slow background poll, or+ accept it and rely on the freshness disclosure?