← All proposals

Context: AgentInbox

Net-new componentOpen in Storybook

proposals/AgentInbox/AgentInbox.tsx476 lines · View on GitHub
import {
	ComponentProps,
	ComponentPropsWithoutRef,
	useId,
	useState,
} from 'react';

import {
	Badge,
	Button,
	Panel,
	SegmentedButton,
	StatusBadge,
	ThinkingState,
} from '@pantheon-systems/pds-toolkit-react';

import { EventLog } from '../EventLog/EventLog';
import { EventLogItem, EventLogItemStatus } from '../EventLog/EventLogItem';
import { Icon } from '../Icon/Icon';
import { Spinner } from '../Spinner/Spinner';

import './agent-inbox.css';

export type AgentInboxLane = 'done' | 'needs' | 'running';
export type AgentInboxView = 'board' | 'list';
export type AgentTaskStatus = 'done' | 'failed' | 'running' | 'waiting';

export interface AgentTaskStep {
	/**
	 * What the agent did.
	 */
	label: string;
	/**
	 * Where this step is at. Leave it out and the inbox picks one: earlier
	 * steps are `done`, and the last is `error` when the task failed.
	 */
	status?: EventLogItemStatus;
	/**
	 * When it happened, formatted by the consumer (for example "2m ago").
	 */
	time?: string;
}

export interface AgentTask {
	/**
	 * Name of the agent or model.
	 */
	agent: string;
	/**
	 * One or two sentences on what the task is about or where it stands.
	 */
	description?: string;
	/**
	 * Unique id of the task.
	 */
	id: string;
	/**
	 * The sites the task is working on. One site shows its name; more than one
	 * shows the number of sites.
	 */
	sites?: string[];
	/**
	 * Files or sources the agent has read.
	 */
	sourceCount?: number;
	/**
	 * What the agent did so far, oldest first. The last four show when the card
	 * is open.
	 */
	steps?: AgentTaskStep[];
	/**
	 * Where the task is at. `waiting` and `failed` sit in the "needs" lane.
	 */
	status: AgentTaskStatus;
	/**
	 * The feature or area the task is working on (for example "Autopilot").
	 * Shown under the title in the smallest copy size.
	 */
	subtitle?: string;
	/**
	 * Elapsed time, formatted by the consumer (for example "2m 14s"). The
	 * consumer owns the timer.
	 */
	time?: string;
	/**
	 * Name of the task.
	 */
	title: string;
	/**
	 * Tool calls so far.
	 */
	toolCount?: number;
}

export interface AgentInboxLabelStrings {
	approve: string;
	board: string;
	done: string;
	empty: string;
	failed: string;
	list: string;
	needs: string;
	open: string;
	reject: string;
	retry: string;
	running: string;
	sites: string;
	sources: string;
	statusIndicator: string;
	steps: string;
	thinking: string;
	tools: string;
	view: string;
	waiting: string;
}

export interface AgentInboxProps extends ComponentPropsWithoutRef<'div'> {
	/**
	 * Additional class names.
	 */
	className?: string;
	/**
	 * Layout on first render.
	 */
	defaultView?: AgentInboxView;
	/**
	 * Translatable strings: lane names, status words, buttons and the layout
	 * switch.
	 */
	labelStrings?: AgentInboxLabelStrings;
	/**
	 * Which lanes show, in order. Leave it out for all three.
	 */
	lanes?: AgentInboxLane[];
	/**
	 * Called when the user approves a task that is waiting. Without it the
	 * inbox shows exactly the tasks it is given.
	 */
	onApprove?: (task: AgentTask) => void;
	/**
	 * Called when the user opens a running or done task. Shows an Open button.
	 */
	onOpen?: (task: AgentTask) => void;
	/**
	 * Called when the user rejects a task that is waiting.
	 */
	onReject?: (task: AgentTask) => void;
	/**
	 * Called when the user retries a failed task.
	 */
	onRetry?: (task: AgentTask) => void;
	/**
	 * Called when the layout switch changes.
	 */
	onViewChange?: (view: AgentInboxView) => void;
	/**
	 * The tasks to show. The status of each decides its lane.
	 */
	tasks: AgentTask[];
}

// Stand-in for the v2 `mergeClasses` util, which the published package does
// not export. The port uses the real one.
const mergeClasses = (classes: Array<string | null | undefined>) =>
	classes.filter(Boolean).join(' ');

const defaultLabelStrings: AgentInboxLabelStrings = {
	approve: 'Approve',
	board: 'Board',
	done: 'Done',
	empty: 'Nothing here',
	failed: 'Failed',
	list: 'List',
	needs: 'Needs you',
	open: 'Open',
	reject: 'Reject',
	retry: 'Retry',
	running: 'In progress',
	sites: 'sites',
	sources: 'Sources read',
	statusIndicator: 'Status: ',
	steps: 'Latest steps',
	thinking: 'Working',
	tools: 'Tool calls',
	view: 'Layout',
	waiting: 'Needs your input',
};

const allLanes: AgentInboxLane[] = ['needs', 'running', 'done'];

const statusBadgeType: Record<
	AgentTaskStatus,
	ComponentProps<typeof StatusBadge>['statusType']
> = {
	done: 'success',
	failed: 'critical',
	running: 'working',
	waiting: 'warning',
};

const stepStatus = (
	task: AgentTaskStatus,
	isLast: boolean,
): EventLogItemStatus => {
	if (!isLast) return 'done';
	return task === 'failed' ? 'error' : 'done';
};

const laneOf = (status: AgentTaskStatus): AgentInboxLane => {
	if (status === 'waiting' || status === 'failed') return 'needs';
	return status === 'running' ? 'running' : 'done';
};

/**
 * AgentInbox UI component. Every task your agents are working on, grouped by
 * what it needs from you: Needs you, Running and Done. Each card opens in
 * place to show the last steps and the decisions you can make. Narrow
 * containers always get the list.
 */
export const AgentInbox = ({
	className,
	defaultView = 'board',
	labelStrings = defaultLabelStrings,
	lanes = allLanes,
	onApprove,
	onOpen,
	onReject,
	onRetry,
	onViewChange,
	tasks,
	...props
}: AgentInboxProps) => {
	const baseClass = 'pds-agent-inbox';
	const uid = useId();
	const [view, setView] = useState<AgentInboxView>(defaultView);
	const [openId, setOpenId] = useState<string | null>(null);

	const handleView = (value: string) => {
		const next = value as AgentInboxView;
		setView(next);
		onViewChange?.(next);
	};

	const statusIcon = (status: AgentTaskStatus) => {
		if (status === 'running') {
			return (
				<Spinner
					className={`${baseClass}__status`}
					color='var(--agent-inbox-status-color)'
					label={labelStrings.running}
					size='s'
				/>
			);
		}
		const iconName =
			status === 'done'
				? 'check'
				: status === 'failed'
					? 'diamondExclamation'
					: 'circle';
		return (
			<Icon className={`${baseClass}__status`} iconName={iconName} size='xs' />
		);
	};

	const siteText = (task: AgentTask) => {
		const sites = task.sites ?? [];
		if (sites.length === 0) return null;
		return sites.length === 1
			? sites[0]
			: `${sites.length} ${labelStrings.sites}`;
	};

	const card = (task: AgentTask) => {
		const isOpen = openId === task.id;
		const bodyId = `${uid}-${task.id}`;
		const steps = (task.steps ?? []).slice(-4);
		const hasActions =
			task.status === 'waiting' ||
			task.status === 'failed' ||
			(onOpen && (task.status === 'running' || task.status === 'done'));

		return (
			<li className={`${baseClass}__entry`} key={task.id}>
				<Panel
					className={mergeClasses([
						`${baseClass}__card`,
						`${baseClass}__card--${task.status}`,
					])}
					padding='none'
					variant='default'
				>
					<button
						aria-controls={bodyId}
						aria-expanded={isOpen}
						className={`${baseClass}__toggle`}
						onClick={() => setOpenId(isOpen ? null : task.id)}
						type='button'
					>
						<span className={`pds-copy-s ${baseClass}__title-row`}>
							{statusIcon(task.status)}
							<span className={`${baseClass}__heading`}>
								<span className={`${baseClass}__title`}>{task.title}</span>
								{(task.subtitle || siteText(task)) && (
									<span className={`pds-copy-2xs ${baseClass}__subtitle`}>
										{task.subtitle && <span>{task.subtitle}</span>}
										{siteText(task) && <span>{siteText(task)}</span>}
									</span>
								)}
							</span>
							<Icon
								className={`${baseClass}__chevron`}
								iconName='angleDown'
								size='xs'
							/>
						</span>
						{task.description && (
							<span className={`pds-copy-s ${baseClass}__description`}>
								{task.description}
							</span>
						)}
						<span className={`pds-copy-xs ${baseClass}__foot`}>
							<span className={`${baseClass}__state`}>
								<StatusBadge
									hasStatusIndicator
									label={labelStrings[task.status]}
									statusIndicatorText={labelStrings.statusIndicator}
									statusType={statusBadgeType[task.status]}
								/>
								{task.time && (
									<span className={`${baseClass}__time`}>{task.time}</span>
								)}
							</span>
							<span className={`${baseClass}__counts`}>
								{task.sourceCount !== undefined && (
									<span title={labelStrings.sources}>
										<Icon iconName='magnifyingGlass' size='xs' />
										{task.sourceCount}
										<span className='visually-hidden'>
											{labelStrings.sources}
										</span>
									</span>
								)}
								{task.toolCount !== undefined && (
									<span title={labelStrings.tools}>
										<Icon iconName='wrench' size='xs' />
										{task.toolCount}
										<span className='visually-hidden'>
											{labelStrings.tools}
										</span>
									</span>
								)}
							</span>
						</span>
					</button>
					<div className={`${baseClass}__body`} hidden={!isOpen} id={bodyId}>
						<p className={`pds-copy-xs ${baseClass}__agent`}>{task.agent}</p>
						{steps.length > 0 && (
							<EventLog
								aria-label={labelStrings.steps}
								className={`${baseClass}__steps`}
								hasRail
							>
								{steps.map((step, index) => (
									<EventLogItem
										key={`${index}-${step.label}`}
										label={step.label}
										status={
											step.status ??
											stepStatus(task.status, index === steps.length - 1)
										}
										time={step.time}
									/>
								))}
								{task.status === 'running' && (
									<ThinkingState label={labelStrings.thinking} size='xs' />
								)}
							</EventLog>
						)}
						{hasActions && (
							<div className={`${baseClass}__actions`}>
								{task.status === 'waiting' && (
									<>
										<Button
											label={labelStrings.reject}
											onClick={() => onReject?.(task)}
											size='xs'
											variant='secondary'
										/>
										<Button
											label={labelStrings.approve}
											onClick={() => onApprove?.(task)}
											size='xs'
											variant='primary'
										/>
									</>
								)}
								{task.status === 'failed' && (
									<Button
										label={labelStrings.retry}
										onClick={() => onRetry?.(task)}
										size='xs'
										variant='primary'
									/>
								)}
								{onOpen &&
									(task.status === 'running' || task.status === 'done') && (
										<Button
											label={labelStrings.open}
											onClick={() => onOpen(task)}
											size='xs'
											variant='secondary'
										/>
									)}
							</div>
						)}
					</div>
				</Panel>
			</li>
		);
	};

	return (
		<div
			className={mergeClasses([baseClass, className])}
			data-view={view}
			{...props}
		>
			<div className={`${baseClass}__bar`}>
				<SegmentedButton
					defaultValue={view}
					id={`${uid}-view`}
					label={labelStrings.view}
					onChange={handleView}
					options={[
						{ iconName: 'table', label: labelStrings.board, value: 'board' },
						{ iconName: 'list', label: labelStrings.list, value: 'list' },
					]}
					size='s'
				/>
			</div>
			<div className={`${baseClass}__lanes`}>
				{lanes.map((lane) => {
					const items = tasks.filter((task) => laneOf(task.status) === lane);
					const headingId = `${uid}-${lane}`;
					return (
						<Panel
							aria-labelledby={headingId}
							className={`${baseClass}__lane`}
							key={lane}
							padding='none'
							role='region'
							variant='sunken'
						>
							<h3
								className={`pds-copy-xs ${baseClass}__lane-head`}
								id={headingId}
							>
								<span>{labelStrings[lane]}</span>
								<Badge color='ink-muted' label={items.length} size='xs' />
							</h3>
							{items.length > 0 ? (
								<ul className={`${baseClass}__cards`}>{items.map(card)}</ul>
							) : (
								<p className={`pds-copy-xs ${baseClass}__empty`}>
									{labelStrings.empty}
								</p>
							)}
						</Panel>
					);
				})}
			</div>
		</div>
	);
};