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.

Output conflict detected between two agents26m ago

Orchestrator-Prime· root → Code Writer → Retrieval

Code-Writer-1 and Code-Writer-2 produced conflicting implementations for auth.ts.

Agent stalled — no progress in 5 minutesjust now

Code-Writer-1· root → Code Writer → Researcher

Policy constraint triggered12m ago

Code-Writer-1· root → QA Inspector → Validator

Token budget exceeded8m ago

Data-Analyst· root → Orchestrator → Researcher

Agent consumed 142% of its allocation (28,400 / 20,000 tokens).

Output conflict detected between two agents20m ago

Orchestrator-Prime· root → Summarizer → Researcher

Code-Writer-1 and Code-Writer-2 produced conflicting implementations for auth.ts.

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
}

Solution Patterns

The Exception-Only Console

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

[Swarm Monitor] ← Global KPIs + kill switch
[Swarm Inbox]   ← Prioritized interrupts requiring human action
[Agent Roster]  ← At-a-glance agent status

Composition: SwarmInbox → EscalationRouter

The onOpenItem callback is designed to transition the user from the macro view (inbox) to the micro view (resolution). For escalation-type items, the standard pattern is to open an Escalation Router in a modal:

<SwarmInbox
  items={notifications}
  onOpenItem={(item) => {
    if (item.type === 'escalation') {
      openModal(<EscalationRouter
        failedAgent={item.agentId}
        branchId={item.branchPath}
        errorSummary={item.detail}
        onRetry={() => retryAgent(item.agentId)}
        onReassign={() => reassignTask(item.id)}
        onCancelBranch={() => cancelBranch(item.branchPath)}
      />);
    }
  }}
/>

For approval-type items, open an ApprovalGate instead. The inbox is the funnel — the specific component you open depends on the event type.

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 transitions the user from the inbox to resolution — typically opening an Escalation Router or Approval Gate inside a modal.

Swarm Inbox