Swarm Inbox

Install

npx ax-depute@latest add swarm-inbox

pnpm dlx ax-depute@latest add swarm-inbox

yarn dlx ax-depute@latest add swarm-inbox

bunx ax-depute@latest add swarm-inbox

A centralized attention triage surface for the swarm supervisor. It aggregates critical events (like permission requests, failed nodes, or policy violations) from across the entire agent fleet into a single, prioritized inbox with one-click drill-down actions.

Policy constraint triggered21m ago

Planner-Beta· root → QA Inspector → Researcher

Policy constraint triggered16m ago

Code-Writer-2· root → Data Analyst → Planner

Policy constraint triggered27m ago

Synthesizer-Z· root → Orchestrator → Researcher

Policy constraint triggered10m ago

Code-Writer-1· root → Code Writer → Synthesizer

Agent failure escalated for reviewjust now

Researcher-A· root → Summarizer → Validator

Interactive StorybookView all states, toggle props, and test edge cases.

Basic usage

import { SwarmInbox } from '@/components/SwarmInbox';
import type { SwarmInboxItem } from '@/components/SwarmInbox/SwarmInbox.types';

const mockNotifications: SwarmInboxItem[] = [
  {
    id: 'evt_1',
    type: 'escalation',
    severity: 'critical',
    title: 'Database connection refused',
    agentId: 'SQL Writer Node',
    branchPath: 'Reporting / Q3',
    timestamp: 'Just now',
    detail: 'Allowed duration exceeded (3000ms)'
  },
  {
    id: 'evt_2',
    type: 'approval',
    severity: 'warning',
    title: 'Requested read access to S3 bucket',
    agentId: 'Data Sync Node',
    timestamp: '2m ago'
  }
];

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <SwarmInbox 
        items={mockNotifications}
        onOpenItem={(item) => console.log('Opening detail modal for', item.id)}
        onDismissItem={(id) => console.log('Dismissed', id)}
      />
    </div>
  );
}

Props

Prop	Type	Default	Description
`items`	`SwarmInboxItem[]`	`undefined`	Array of notification items to render in the inbox list.
`onOpenItem`	`(item: SwarmInboxItem) => void`	`undefined`	Callback fired when the user clicks the "View" button to drill down into an issue.
`onDismissItem`	`(id: string) => void`	`undefined`	Callback fired when the user clicks the "×" (dismiss) button on a non-critical item.
`className`	`string`	`undefined`	Additional CSS class for the root element.

Types

`SwarmInboxItem`

export type SwarmInboxSeverity = 'critical' | 'warning' | 'info';

export interface SwarmInboxItem {
  id: string;
  type: 'approval' | 'escalation' | 'policy_violation' | 'stalled' | 'budget_overrun' | 'conflict';
  severity: SwarmInboxSeverity; 
  title: string;
  agentId: string;         // The agent requiring attention
  branchPath?: string;     // The organizational sub-tree where this agent lives
  timestamp: string;       // Formatted time string, e.g., "Just now"
  detail?: string;         // Optional one-liner description for extra context
}

Composition flow

Swarm Inbox aggregates cross-agent communication. It is typically a top-level navigational element alongside the Swarm Monitor or Agent Roster:

[Swarm Inbox] ← Inter-agent messages & escalations

It serves as the central notification center for human operators.

Design rationale

1. The "Exception-Only" Workflow
Supervising a multi-agent swarm requires shifting from "babysitting" to an "exception-only" workflow. The human should only look at the UI when the UI explicitly asks for help. Swarm Inbox is the funnel for all of those system interrupts.

2. Type-Driven Visual Sorting
Not all interruptions are equal. A policy_violation (an agent trying to access a restricted tool) gets a distinct visual treatment from a standard approval loop. The critical severity visually dominates the list, pulsing if necessary, ensuring triage happens in the correct order.

3. Actionable Drill-Downs
An inbox without actions is just a log. The onOpenItem callback is designed to transition the user smoothly from the macro view (the inbox) to the micro view (opening an Escalation Router or an Approval Gate inside a modal) to resolve the exact issue.