> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic UI components

> The agentic component families in smithers-orchestrator/ui for prompt, approvals, artifacts, sandbox, and canvas surfaces.

`smithers-orchestrator/ui` ships a full set of agentic UI families with shadcn
component anatomy: compound slots, `data-slot` attributes, typed props, and
self-injected namespaced (`sui-*`) styles. Every component calls
`useInjectUiCss()` plus its lane fragment, so rendering any component is enough
to style it; rendering `<SmithersUiStyles />` once at the root composes all
fragments in one sheet with the reduced-motion block last.

All families are correct in light and dark themes and honor
`prefers-reduced-motion`.

## Naming reconciliation

The agentic-ui program planned some names that collided with existing exports,
so the frozen collision policy shipped them under collision-free names. The
shipped names are the contract:

| Planned name                                      | Shipped name                                                          |
| ------------------------------------------------- | --------------------------------------------------------------------- |
| `Task`, `TaskTrigger`, `TaskContent`, `TaskGroup` | `AgentTask`, `AgentTaskTrigger`, `AgentTaskContent`, `AgentTaskGroup` |
| `Agent`                                           | `AgentDefinition`                                                     |
| `Test`                                            | `TestRow`                                                             |

## Conversation

Compound transcript primitives from `smithers-orchestrator/ui`.

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Message, MessageAvatar, MessageHeader, MessageContent, MessageFooter, MessageActions, MessageGroup,
  MessageBranch, MessageBranchContent, MessageBranchSelector, MessageBranchPrevious, MessageBranchNext, MessageBranchPage,
  Bubble, BubbleContent, BubbleActions, BubbleReactions,
  CompactGroup, ConversationCheckpoint, Marker, Shimmer,
  MessageScroller, MessageScrollerProvider, MessageScrollerViewport, MessageScrollerContent,
  MessageScrollerItem, MessageScrollerButton,
  useMessageScroller, useMessageVisibility, useMessageScrollerState,
} from "smithers-orchestrator/ui";
```

* `Message` family: one chat turn with avatar, header, content, footer, and actions slots. `MessageGroup` clusters consecutive turns.
* `MessageBranch` family: branch selector with previous/next/page controls for alternate completions.
* `Bubble` family: lightweight bubble layout with content, actions, and reactions slots.
* `MessageScroller`: both a drop-in scrollport (existing API) and a compound provider/viewport/content/item/button anatomy with `useMessageScroller` commands, `useMessageVisibility`, and `useMessageScrollerState` for streaming transcripts.
* `CompactGroup`, `ConversationCheckpoint`, `Marker`, `Shimmer`: transcript density, checkpoint separators, and streaming placeholders.

## Prompt and attachments

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  PromptInput, PromptInputHeader, PromptInputBody, PromptInputTextarea, PromptInputFooter,
  PromptInputTools, PromptInputButton, PromptInputSubmit, PromptInputStop,
  PromptInputActionMenu, PromptInputActionMenuTrigger, PromptInputActionMenuContent, PromptInputActionAddAttachments,
  usePromptInputAttachments,
  Attachment, AttachmentMedia, AttachmentContent, AttachmentTitle, AttachmentDescription,
  AttachmentActions, AttachmentAction, AttachmentTrigger, AttachmentGroup, AttachmentPreview, AttachmentRemove,
} from "smithers-orchestrator/ui";
```

`PromptInput` is a controlled composer form with submit/stop states
(`ready | submitted | streaming | error`) and an action menu; the attachments
context (`usePromptInputAttachments`) drives the `Attachment` compound, which
renders upload states (`uploading | processing | ready | error`) with preview
and remove slots.

## Reasoning and tools

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Reasoning, ReasoningTrigger, ReasoningContent, ReasoningSummary,
  ChainOfThought, ChainOfThoughtStep, chainOfThoughtStepStatus,
  ToolCall, ToolCallHeader, ToolCallContent, ToolCallInput, ToolCallOutput, ToolCallError, ToolCallApproval,
  toolCallStatus, TOOL_CALL_STATE_LABELS,
  AgentOutput, MessageResponse, parseAgentOutput, formatPartialJson,
  CodeBlock, CodeBlockHeader, CodeBlockFilename, CodeBlockGroup, CodeBlockTabs,
} from "smithers-orchestrator/ui";
```

* `Reasoning`: collapsible reasoning trace with a streaming-aware `ReasoningSummary`.
* `ChainOfThought`: ordered step list; `ChainOfThoughtStep` is both the step model type and the row component.
* `ToolCall`: legacy flat props or the compound header/content/input/output/error/approval anatomy. `toolCallStatus` maps tool states onto status tones.
* `CodeBlock`: token-themed code with header, filename, multi-file groups, and tabs (see [CodeBlock](/components/code-block)).
* `formatPartialJson` repairs truncated JSON for streaming previews; `parseAgentOutput` normalizes agent envelopes for `AgentOutput`.

## Plans, tasks, and queues

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Plan, PlanHeader, PlanTitle, PlanDescription, PlanTrigger, PlanContent, PlanStep, PlanAction, PlanFooter, planStepStatus,
  TaskItem, TaskItemFile,
  AgentTask, AgentTaskTrigger, AgentTaskContent, AgentTaskGroup,
  Queue, QueueSection, QueueSectionTrigger, QueueSectionLabel, QueueSectionContent,
  QueueList, QueueItem, QueueItemIndicator, QueueItemContent, QueueItemDescription,
  ActivityTimeline, ActivityItem, ActivityGroup,
} from "smithers-orchestrator/ui";
```

`Plan` renders a step plan (legacy props or compound anatomy) with per-step
status; `AgentTask` is a collapsible unit of agent work; `Queue` lists pending
and completed work in sections; `ActivityTimeline` groups run activity into
labeled clusters.

## Approvals and checkpoints

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Confirmation, ConfirmationTitle, ConfirmationRequest, ConfirmationAccepted, ConfirmationRejected,
  ConfirmationActions, ConfirmationAction, approvalStateToStatus,
  ApprovalCard, ApprovalRisk, ApprovalResources, ApprovalNote,
  Checkpoint, CheckpointIcon, CheckpointMetadata, CheckpointTrigger, CheckpointActions,
  useCheckpoint, CHECKPOINT_ACTION_KINDS,
} from "smithers-orchestrator/ui";
```

`Confirmation` renders the approval lifecycle (pending, accepted, rejected)
with action slots; `ApprovalCard` adds risk level, affected resources, and a
reviewer note; `Checkpoint` presents a durability checkpoint with restore,
fork, replay, rewind, and return-to-live actions. Gateway-bound wrappers live
in `smithers-orchestrator/gateway-ui` as `GatewayApprovalList`,
`GatewayApprovalConfirmation`, and `GatewayCheckpointControls`.

## Sources and citations

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Sources, SourcesTrigger, SourcesContent, Source,
  InlineCitation, CitationCard, CitationCarousel, CitationQuote,
  Suggestion, SuggestionGroup, OpenInChat,
} from "smithers-orchestrator/ui";
```

`Sources` lists cited origins; `InlineCitation` anchors inline references with
card, carousel, and quote companions; `Suggestion` renders follow-up prompts;
`OpenInChat` deep-links a subject into a chat surface.

## Agents and context

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  AgentDefinition, AgentHeader, AgentContent, AgentInstructions, AgentTools, AgentTool, AgentOutputSchema,
  AgentAvailabilityBadge, availabilityLabel,
  AgentCard,
  ModelSelector, ModelSelectorTrigger, ModelSelectorContent, ModelSelectorGroup, ModelSelectorItem,
  ModelBadge, ProviderBadge,
  ContextUsage, ContextTrigger, ContextContent, ContextContentHeader, ContextContentBody, ContextContentFooter,
  ContextInputUsage, ContextOutputUsage, ContextReasoningUsage, ContextCacheUsage, contextUsagePercent,
} from "smithers-orchestrator/ui";
```

`AgentDefinition` documents an agent (instructions, tools, output schema) with
availability badges; `ModelSelector` is a grouped model picker built on
`Select`; `ContextUsage` breaks down token usage (input, output, reasoning,
cache) in a popover anatomy.

## Coding artifacts

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  Artifact, ArtifactHeader, ArtifactTitle, ArtifactDescription, ArtifactActions, ArtifactAction, ArtifactClose, ArtifactContent,
  Snippet, PackageInfo, SchemaDisplay,
  StackTrace, StackFrame, parseStackTrace,
  TestResults, TestResultsHeader, TestResultsSummary, TestResultsDuration, TestResultsProgress, TestResultsContent,
  TestSuite, TestSuiteName, TestSuiteStats, TestSuiteContent, TestRow, TestStatus, TestName,
  testCaseStatusToStatus, formatTestDuration,
  Commit, CommitHeader, CommitAuthor, CommitInfo, CommitMessage, CommitMetadata, CommitHash, CommitTimestamp,
  CommitActions, CommitFiles, CommitFile, CommitFileStatus, CommitFilePath, useCommitModel,
  ChangeSummary, EnvironmentVariables, EnvironmentVariable, SecretField,
} from "smithers-orchestrator/ui";
```

Review-surface families: `TestResults` (suite/test rows with status and
duration), `Commit` (hash, author, files), `ChangeSummary`, `StackTrace`
(parsed frames via `parseStackTrace`), `Artifact` (side-panel container),
plus `Snippet`, `PackageInfo`, `SchemaDisplay`, `EnvironmentVariables`, and
`SecretField` for redacted secrets.

## Sandbox previews

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  AgentSandbox, AgentSandboxHeader, AgentSandboxStatus, AgentSandboxActions, AgentSandboxContent, sandboxStateToStatus,
  WebPreview, WebPreviewToolbar, WebPreviewAddress, WebPreviewContent,
  JSXPreview,
} from "smithers-orchestrator/ui";
```

`AgentSandbox` shows sandbox lifecycle state; `WebPreview` embeds a sandboxed
iframe preview with toolbar and address slots; `JSXPreview` renders an inert
React subtree.

## Workflow canvas

```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  WorkflowCanvas, WorkflowNode, WorkflowNodeHeader, WorkflowNodeContent, WorkflowNodeStatus,
  WorkflowEdge, WorkflowConnection, WorkflowControls, WorkflowPanel, WorkflowToolbar, WorkflowMinimap,
} from "smithers-orchestrator/ui";
```

Canvas anatomy for workflow graphs. The gateway binding
(`SmithersCanvasNode`, `SmithersNodeHandles` from
`smithers-orchestrator/gateway-ui`) adapts these slots into
`WorkflowGraph` `nodeTypes`.