Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Agent UI Components
| Status | Updated | Covered Files |
|---|
| 🟢 Stable | 2026-02-21 | features/agents/components/*, features/agents/hooks/useAgentRuns.ts, features/agents/index.ts |
Overview
The Agent UI layer provides full cost-transparency and operational visibility for the AI agent execution framework. It comprises four components and one data-fetching hook, all exported via the features/agents/index.ts barrel.
AgentDashboard ← full-page 3-tab view (overview / runs / credits)
CreditUsageWidget ← embeddable credit + runs gauge panel
AgentRunDetail ← single-run deep-dive with step timeline
AgentAttributionBadge ← inline badge marking agent-generated content
useAgentRuns ← Firestore query hook + summary computation
AgentDashboard
File: src/features/agents/components/AgentDashboard.tsx
The main entry point for agent operations. Renders a page-level view with three tabs.
Layout
PageLayout
└─ PageHeader (title="AI Agents", description, actions=[Refresh])
└─ PageTabs (tabs=[Overview, Runs, Credits])
├─ Overview Tab
│ ├─ 4× StatCard (total / completed / failed / active runs)
│ ├─ AgentTypeBreakdown (horizontal bar chart)
│ └─ RecentRunsTable (last 10 runs)
├─ Runs Tab
│ ├─ Filter bar (status Select + agent type Select)
│ └─ Full RunsTable with RunRow components
└─ Credits Tab
└─ <CreditUsageWidget />
Key Implementation Details
| Aspect | Detail |
|---|
| Tab routing | URL-based via useParams — /agents/:tab? |
| Data source | useAgentRuns(filters, maxResults) |
| Status mapping | STATUS_MAP: Record<AgentRunStatus, { status: StatusType; label: string }> converts run statuses to StatusBadge-compatible values |
| StatCard | Locally defined (not a shared component) — 4-metric grid at top of overview |
| AgentTypeBreakdown | Groups runs by agentType, renders <Progress> bars with percentage labels |
| RunRow | Table row with StatusBadge, agent type Badge, credit count, duration, timestamp |
| Empty state | Uses <EmptyState> with Bot icon when no runs exist |
Dependencies
PageLayout, PageHeader, PageTabs, Card, Button, Select, StatusBadge, Badge, Progress, EmptyState, Tooltip, useTenant, useAgentRuns, AGENT_DEFINITIONS_MAP
File: src/features/agents/components/CreditUsageWidget.tsx
Embeddable panel showing credit consumption, run quotas, and projected exhaustion.
Sections
CreditUsageWidget
├─ Credit Gauge Card (used / total, circular progress)
├─ Runs Gauge Card (runs used / max per month)
├─ Projected Exhaustion Warning (conditional, amber Card)
└─ Agent Type Breakdown (credits per agent type with Progress bars)
Key Implementation Details
| Aspect | Detail |
|---|
| Allocation source | Derives monthlyAllocation from organization.subscription.features.agentCreditsPerMonth via useTenant(), with fallback to TIER_LIMITS[tier].maxAgentCreditsPerMonth |
| Color thresholds | getUsageColor() / getProgressColor(): emerald < 75%, amber 75–90%, rose > 90% |
| Exhaustion projection | Calculates days remaining based on daily burn rate; shows amber warning card when < 7 days |
| Breakdown | Groups runs by agentType, sums creditsConsumed, renders sorted Progress bars |
| Responsive | 2-column grid for gauges, single column for breakdown |
Props
interface CreditUsageWidgetProps {
runs: AgentRun[]; // Pre-fetched runs (from useAgentRuns)
className?: string;
}
AgentRunDetail
File: src/features/agents/components/AgentRunDetail.tsx
Deep-dive view for a single agent run with full step timeline.
Sections
AgentRunDetail
├─ Header Card
│ ├─ Title (agent name + run ID) with StatusBadge
│ ├─ 4-metric grid: Duration | Steps | Credits | Tokens
│ └─ Triggered-by line with timestamp
├─ Error Banner (conditional, rose Card with error.message + code)
├─ Escalation Banner (conditional, amber Card)
│ ├─ Reason text
│ ├─ Options list
│ └─ Resolution details (if resolved)
└─ Step Timeline
└─ StepCard[] (vertical timeline with connector lines)
├─ Status icon (color-coded circle)
├─ Tool name + step index
├─ Metrics: credits, tokens, duration
└─ Expandable Input/Output JSON previews
Key Implementation Details
| Aspect | Detail |
|---|
| Step status icons | Color-coded: emerald (completed), rose (failed), amber (running), slate (pending/skipped) |
| Timeline connector | Vertical border-l-2 between step cards; last step omits connector |
| JSON preview | Collapsible <pre> blocks with JSON.stringify(data, null, 2) |
| Escalation display | Shows all EscalationOption items, highlights the chosen resolution |
| Error display | Rose-tinted Card showing error.message, optional error.code, and error.stepId link |
Props
interface AgentRunDetailProps {
run: AgentRun;
className?: string;
}
AgentAttributionBadge
File: src/features/agents/components/AgentAttributionBadge.tsx
Inline badge that marks content as agent-generated. Appears next to any entity that was created or modified by an agent run.
Behavior
| Condition | Renders |
|---|
agentRunId present | Violet Bot icon with Tooltip showing agent type + triggered-by name |
agentRunId absent + showHumanBadge=true | Slate User icon with “Manual” tooltip |
agentRunId absent + showHumanBadge=false | null (renders nothing) |
Props
interface AgentAttributionBadgeProps {
agentRunId?: string;
agentType?: string;
triggeredByName?: string;
showHumanBadge?: boolean; // default: false
size?: 'sm' | 'md'; // default: 'sm'
}
Usage Example
<AgentAttributionBadge
agentRunId={expense.agentRunId}
agentType={expense.agentType}
triggeredByName={expense.triggeredByName}
/>
useAgentRuns Hook
File: src/features/agents/hooks/useAgentRuns.ts
Data-fetching hook that queries the organizations/{orgId}/agent_runs Firestore subcollection.
Signature
function useAgentRuns(
filters?: Partial<Omit<AgentRunFilters, 'organizationId'>>,
maxResults?: number // default: 50
): UseAgentRunsReturn;
Return Type
interface UseAgentRunsReturn {
runs: AgentRun[];
loading: boolean;
error: Error | null;
summary: AgentRunsSummary;
refetch: () => void;
}
AgentRunsSummary
Computed via useMemo from the fetched runs:
| Field | Computation |
|---|
totalRuns | runs.length |
completedRuns | Count where status === 'completed' |
failedRuns | Count where status === 'failed' |
activeRuns | Count where status in ['running', 'queued', 'paused', 'awaiting_human'] |
creditsConsumed | Sum of all run.creditsConsumed |
averageCreditCost | creditsConsumed / completedRuns (0 if no completed runs) |
averageDurationMs | Average of durationMs for completed runs with non-null duration |
Supported Filters
| Filter | Firestore Clause |
|---|
status: AgentRunStatus[] | where('status', 'in', ...) |
agentType: string | where('agentType', '==', ...) |
triggeredBy: string | where('triggeredBy', '==', ...) |
startedAt desc with a limit of maxResults.
Re-fetch
Call refetch() to trigger a re-query. Internally increments a counter in the dependency array.
Barrel Export
File: src/features/agents/index.ts
All public API exports from the agents feature module:
| Category | Exports |
|---|
| Types | AgentRun, AgentRunStatus, AgentStep, AgentStepStatus, AgentDefinition, AgentCategory, AgentEscalation, EscalationOption, AgentTool, AgentToolContext, AgentToolResult, AgentRunFilters, AgentRunError |
| Services | agentExecutionService, agentToolRegistry, createAgentTool, agentQuotaService, AGENT_DEFINITIONS, AGENT_DEFINITIONS_MAP |
| Hooks | useAgentRuns, AgentRunsSummary (type), UseAgentRunsReturn (type) |
| Components | AgentDashboard, CreditUsageWidget, AgentRunDetail, AgentAttributionBadge |
| Re-exports | CreditReservation, CreditBalance (from billing), AgentQuotaCheckResult |
import { AgentDashboard, useAgentRuns, type AgentRun } from '@/features/agents';
Maintenance
Update this document when:
- Adding new agent UI components
- Changing the hook query logic or summary computation
- Modifying the barrel export surface
- Adding new props to existing components
