Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Workbench Inbox — Per-Session Feed · Design Doc
Branch:
feat/workbench-inbox-per-sessionStatus: Implemented (2026-05-30) — backend query, typed persistence, Controller→UI realtime bridge, and frontend all landed. Owner: cyhhao
0. Prerequisite (confirmed 2026-05-30): unified, typed message persistence
Finding (git archaeology): avibe agent replies were never persisted — the mirror
(920a513) was built to "mirror non-avibe IM messages" and skips avibe; the avibe
adapter (a7b87c0) only pushes over SSE and never wrote to messages; ui_server only
ever wrote the user's own message. So the messages table holds avibe user rows but no
agent replies. Not a regression — an unfinished corner.
Decision: persist messages in the Controller, unified across all platforms incl.
avibe, decoupled from IM delivery/muting — i.e. assistant and tool_call messages are
persisted even when the IM side hides them (emit_agent_message currently drops them before
send). Add a first-class type column to messages (Alembic migration + backfill):
type |
meaning |
|---|---|
user |
human-sent |
assistant |
agent's intermediate text (before the final result) |
tool_call |
tool invocation |
notify |
progress/notification |
result |
the final user-facing answer (inbox preview = latest of these) |
Persistence hook lives in the Controller message flow before the IM mute filter, so every
type lands regardless of per-channel display preferences. The per-session inbox preview =
latest type='result' message — aligned with the avibe chat, which only renders results;
assistant / tool_call are the intermediate process log and never drive the preview.
Realtime therefore uses the Controller→UI events bridge (§4), since persistence now happens
Controller-side for all platforms.
Read paths stay result-aware (so persisting the full process log never leaks): the avibe
chat transcript (/api/sessions/<id>/messages) is scoped to type IN ('user','result','notify')
plus rows with metadata.source='show_page' — it keeps the dialogue, terminal notify markers
(a failed/stopped turn, rendered as a distinct gold "Notify" row), and Show-Page transcript
marks, while hiding intermediate assistant / tool_call process rows. The unread counts
(unread_counts / unread_counts_by_session) count type='result' only — matching the inbox
card's unread_count so the sidebar badge and the card never disagree. ChatPage marks the
actively-viewed session read on any unread so the open chat never badges itself.
1. Why
The current Workbench Inbox is a flat per-message feed: messages_service.list_inbox
returns the most recent agent-authored message rows, so one busy session produces many
cards, cards show raw scope_id/session_id (no project name / session title), and there
is no realtime push for agent replies (only the web user-message write publishes an SSE
event; agent replies are written by the mirror in the Controller process and never reach
the UI server's browser SSE).
We are reshaping it into a Slack-like per-session feed: one card per conversation, showing that conversation's latest agent reply, jumping to the top in real time on any new message.
2. Confirmed product decisions
- Sort by each session's last message of any author, time descending.
- Preview text = that session's latest agent reply (distinct from the sort key).
- Tabs: "Unread" lists only sessions with unread agent messages; "All" lists every session that has ≥1 agent reply.
- Open = mark the whole session read (reuse existing
mark_session_read). - Scope: avibe web sessions only (
platform = 'avibe'). - Realtime: a new agent reply must bump its card to the top within ~1s, no manual refresh. Requires a Controller→UI cross-process event channel.
- "Replied" badge: shown when the session's last message is from the user
(
last_message_author == 'user') — i.e. you've responded and are awaiting the agent. NOT a sticky "ever replied" flag.
3. Data model — query-time aggregation, no new table
agent_sessions is the conversation aggregate root; messages stays the single source of
truth for read/unread. No schema migration.
Per-session inbox row (computed):
| Field | Source |
|---|---|
session_id |
agent_sessions.id |
scope_id / project_id |
agent_sessions.scope_id → scopes.native_id |
project_name |
scopes.display_name |
title |
agent_sessions.title |
last_activity_at (sort key) |
MAX(messages.created_at) over the session, any author |
last_message_author |
author of the message at last_activity_at (→ replied = =='user') |
preview_text / preview_at |
latest type='result' message in the session |
unread_count |
count of type='result' AND read_at IS NULL in the session |
Eligibility: sessions with ≥1 type='result' message, platform='avibe'. "Unread" filter:
unread_count > 0. Sort: last_activity_at DESC, session_id DESC. Pagination: keyset cursor
on (last_activity_at, session_id) ("load more").
Implementation: storage/messages_service.py::list_inbox_sessions(conn, *, unread_only, limit, before) using window functions / grouped subqueries over messages joined to
agent_sessions + scopes. mark_session_read is unchanged.
4. Realtime — Controller → UI events bridge
Reuses the existing internal Unix-socket infra (core/internal_server.py +
vibe/internal_client.py) and the per-process browser SSEBroker.
- Controller event bus (
core/inbox_events.py): a small thread-safe fan-out (asyncio.Queueper subscriber) owned by the Controller.persist_agent_message(core/message_mirror.py, runs in the Controller) emits aninbox.session.updatedevent after persisting an avibe result — carrying the recomputed per-session inbox row (so the browser can patch without a refetch). Intermediateassistant/tool_callpersist silently (no result row yet → no event). GET /internal/events(new,core/internal_server.py): long-lived SSE that subscribes to the event bus and streams events; mirrors the existing/internal/dispatchstreaming shape.- UI server subscriber: a lifespan background task (
vibe/ui_server.py) connects via a newinternal_client.stream_events()and re-publishes each event to the browserSSEBroker(broker.publish('inbox.session.updated', row)), reconnecting on drop. - The existing in-process web user-message write also publishes
inbox.session.updatedso the user's own send updates the feed instantly without the round trip.
Browser: WorkbenchInboxContext handles inbox.session.updated by upserting the row and
re-sorting (bump to top); inbox.unread.changed / markRead zero the unread.
5. Frontend
WorkbenchInboxContext: state becomesinboxSessions: InboxSession[](+totalUnread, pagination cursor). Realtime upsert + re-sort.markRead(sessionId)unchanged.InboxPage: one card per session — project name, title, agent preview, relative time (of last activity), unread badge, 已回复 / Replied badge whenlast_message_author=='user'. Unread/All tabs; "Load more".WorkbenchSidebarInboxHoverPopover: show session title + project name (not IDs).- i18n:
workbench.inbox.repliedetc. inen.json+zh.json.
6. Tests
tests/test_messages_service.py:list_inbox_sessions— one card per session, sort by last activity (any author), preview = latest result (an intermediateassistantbumps the sort clock but never the preview),unread_count,repliedwhen last message is the user's, pagination cursor.tests/test_message_mirror.py:persist_agent_messagelands a typed agent row; an aviberesulton a resolved session both persists and publishesinbox.session.updated; an intermediateassistantpersists without publishing (no result yet).tests/test_inbox_events.py:InboxEventBusfan-out / unsubscribe / no-subscriber no-op.tests/test_sqlite_state_migration.py: HEAD bumped to themessages.typemigration.- Keep existing
unread_counts/mark_session_readtests green.
7. Commit breakdown
- Plan doc (this file).
- Backend:
list_inbox_sessions+/api/inboxshape change + tests. - Realtime: Controller event bus +
/internal/events+ UI subscriber + emit on writes. - Frontend: context + InboxPage + sidebar popover + i18n.
- Polish + PR.