feat: Inbox — structured notification feed for agent activity

[OneStepAt4time]

Inbox — Structured Notification Feed

Why

Users need to know what happened while they were away. Currently we have raw SSE events but no structured inbox. An inbox gives users a scannable feed of agent completions, failures, blockers, and mentions.

Concept

• Inbox items are structured notifications about agent activity
• Types: task completed, task failed, blocker reported, mention, session idle
• Read/unread state, archive, batch operations
• Real-time updates via SSE

DB Schema

CREATE TABLE inbox_item (
  id TEXT PRIMARY KEY,
  workspace_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  actor_type TEXT NOT NULL CHECK(actor_type IN ('agent', 'system')),
  actor_id TEXT NOT NULL,
  type TEXT NOT NULL,  -- task_completed, task_failed, blocker, mention, session_idle
  title TEXT NOT NULL,
  body TEXT,
  reference_type TEXT,  -- session, autopilot, squad, chat
  reference_id TEXT,
  read_at TEXT,
  archived_at TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX idx_inbox_user_unread ON inbox_item(user_id, read_at) WHERE read_at IS NULL;

API Endpoints

• GET /v1/inbox — list inbox items (with unread count)
• POST /v1/inbox/:id/read — mark as read
• POST /v1/inbox/read-all — mark all as read
• POST /v1/inbox/:id/archive — archive
• POST /v1/inbox/archive-all — archive all read

Frontend

• Inbox page/drawer: list of items with icon, title, time
• Unread badge in navigation
• Click to navigate to referenced entity

Acceptance Criteria

• Inbox item creation triggered by agent events
• CRUD API for inbox operations
• SSE events for new inbox items
• Dashboard inbox view with unread badge
• Tests
• npm run gate passes

Reference

Competitive analysis: references/multica-competitive-analysis.md §2.6

[OneStepAt4time]

🚧 Blocked by: #3970 (Task Queue) — foundational state machine required before this feature can be implemented.

[OneStepAt4time]

Inbox Notification Feed — Dashboard Design Spec

Component Architecture

dashboard/src/
├── components/
│   └── inbox/
│       ├── InboxDrawer.tsx        — Slide-in panel, triggered from sidebar bell icon
│       ├── InboxItem.tsx          — Single notification row (icon + title + time + read state)
│       ├── InboxBadge.tsx         — Unread count badge for sidebar
│       └── InboxEmpty.tsx         — Empty state illustration
├── hooks/
│   └── useInbox.ts               — Data fetching + SSE subscription + read/archive mutations
├── store/
│   └── useInboxStore.ts          — Zustand store for inbox state (items, unreadCount, loading)
├── types/
│   └── inbox.ts                  — InboxItem type, filter types
└── pages/
    └── (no new page — inbox is a drawer, not a route)

Data Model (Frontend)

interface InboxItem {
  id: string;
  type: "task_completed" | "task_failed" | "blocker" | "mention" | "session_idle" | "approval_needed";
  title: string;
  body?: string;
  actorType: "agent" | "system";
  actorId: string;
  referenceType?: "session" | "autopilot" | "squad" | "chat";
  referenceId?: string;
  readAt: string | null;
  archivedAt: string | null;
  createdAt: string;
}

SSE/Polling Approach

Primary: SSE events → store

• Subscribe to global SSE stream (GET /v1/events)
• Filter for inbox-relevant events: session_ended, session_stall, session_dead, session_approval
• Map each to an InboxItem and prepend to store
• No additional SSE channel needed — reuse existing global stream

Secondary: REST polling via useSseAwarePolling

• GET /v1/inbox — fetch full inbox list on mount + periodic refresh
• Same pattern as SessionBoard/SessionTable: 5s fallback, 30s when SSE healthy
• SSE events are debounced (1s) before triggering REST refetch for consistency

Unread count:

• Computed from store: items.filter(i => !i.readAt).length
• Badge in sidebar header, updates in real-time via SSE

UI Design

Sidebar:

• Bell icon (Bell from lucide-react) in header area
• InboxBadge overlays unread count (red dot or number for 1-99+)

InboxDrawer:

• Slides in from right (reuse existing drawer pattern from NewSessionDrawer)
• Header: "Inbox" + unread count + "Mark all read" + "Archive all read" buttons
• Filter tabs: All | Unread | Mentions
• List: InboxItem rows with:
  • Type icon (✅ completed, ❌ failed, 🚫 blocker, 💬 mention, ⏸️ idle, 🔐 approval)
  • Title text
  • Relative timestamp
  • Unread dot indicator
  • Click → navigate to referenced entity (e.g. session detail page)
• Infinite scroll or "Load more" (same pattern as board pagination)
• Empty state: InboxEmpty with illustration

InboxItem actions:

• Click → mark as read + navigate to reference
• Swipe/button → archive

API Endpoints (consumed by dashboard)

Endpoint	Method	Purpose
`GET /v1/inbox`	GET	List items (paginated, filterable by read/archived)
`POST /v1/inbox/:id/read`	POST	Mark single item as read
`POST /v1/inbox/read-all`	POST	Mark all as read
`POST /v1/inbox/:id/archive`	POST	Archive single item
`POST /v1/inbox/archive-all`	POST	Archive all read items

Implementation Order

1. Types — `types/inbox.ts`
2. Store — `useInboxStore.ts` with items, unreadCount, actions
3. Hook — `useInbox.ts` wrapping `useSseAwarePolling` + REST calls
4. Components — InboxDrawer, InboxItem, InboxBadge, InboxEmpty
5. Layout integration — Bell icon + badge in sidebar, drawer toggle
6. Tests — InboxDrawer rendering, badge count, mark read, archive

Dependencies

• Backend: Hephaestus needs to ship the inbox API endpoints + SSE event mapping first
• Dashboard: can start with mock data while API is in development

Out of Scope

• Push notifications (browser/web push)
• Email notifications
• Per-user inbox routing (requires auth multi-user)
• Inbox search/filter by text content

— Daedalus 🏛️