YuhuanStudioYunUIDocs
AI

Agent Timeline

Host-fed reasoning, tool, task and approval rows with terminal statuses, expandable output and file-diff details.

Compact activity inside an assistant turn: reasoning disclosures, tool rows with output and file diffs, task results, and tool approvals. Compose it beside the assistant's Markdown content inside ChatMessage. The host supplies AgentTimelineEntry[], statuses and callbacks. Legacy AgentTimelineBlock retains its reasoning/tool/approval union; the additive entry API supports tasks, cancelled tools and rich outputContent.

Import

tsx1 line
import { AgentTimeline } from "@yuhuanowo/yunui/ai";

Basic

Each block is a discriminated union on kind. A reasoning block collapses its trace behind a one-line label; a tool block shows the verb, an optional mono summary, a status glyph, and — when command/output are set — an expandable console.

Basic

Tool states & nesting

status drives the node: running spins a loader in the brand tone, done shows a check, error recolors the row and console red. Set indent to nest a row one level in — e.g. a subagent step under the call that dispatched it.

Tool states & nesting

Approval prompts

An approval block renders an inline allow/deny panel and fires onApprove / onReject with the block id. Once decided, pass decision (and decidedLabel) to freeze it into a resolved state.

Approval prompts

Run commandbash

This will drop the staging database. Continue?

$ dropdb yunui_staging
Write filefs.writeApproved

Overwrite migrations/003.sql

Rendering reasoning as markdown

By default reasoning content renders as pre-wrapped plain text. Pass renderContent to plug in a Markdown renderer (e.g. MarkdownRenderer from @yuhuanowo/yunui/content) so lists, code and emphasis format correctly.

tsx6 lines
import { MarkdownRenderer } from "@yuhuanowo/yunui/content";

<AgentTimeline
blocks={blocks}
renderContent={(text) => <MarkdownRenderer content={text} />}
/>

Task rows, cancellation and detail disclosures

AgentTimelineEntry adds kind: "task" rows with pending, running, done, failed or cancelled status. Existing AgentTimelineBlock[] values remain valid; the old type intentionally does not widen. Use AgentTimelineCancelledToolBlock (or an AgentTimelineEntry[]) for a cancelled tool.

tsx7 linesScroll horizontally
import { AgentTimeline, type AgentTimelineEntry } from "@yuhuanowo/yunui/ai";

const blocks: AgentTimelineEntry[] = [
{ kind: "task", id: "review", label: "Review docs", amount: "12 pages", status: "running", step: 3, details: [{ id: "index", label: "Read the index", meta: "3 / 12" }] },
{ kind: "tool", id: "diff", verb: "Edit", summary: "docs/chat.mdx", status: "done", icon: "terminal", files: [{ id: "chat-doc", file: "docs/chat.mdx", additions: 2, deletions: 1, lines: [{ id: "line-add", text: "Add the menu API", tone: "add" }, { id: "line-del", text: "Remove stale guidance", tone: "del" }] }] },
{ kind: "tool", id: "cancelled", verb: "Run", summary: "pnpm test", status: "cancelled", icon: "terminal" },
];

The summary defaults open, while reasoning, task, tool-output and file-diff rows default closed. Provide defaultOpen for initial row state, or open with onToggleRow / onToggleDiff for host-controlled disclosure. labels.summary(counts) receives actual step/reasoning/tool/task/approval counts; it does not infer message counts.

Use AgentTimelineLabels to replace the summary, process/status, output and diff copy. In particular, waitingForHost labels the busy acknowledgement state without resolving the approval.

Tool details can carry context/add/delete rows and files can carry unified diff lines. Long output stays inside its own scroll region. An approval row's busy state means the host is preparing its acknowledgement and does not resolve the request; use labels.waitingForHost to localize that status. onApprove / onReject still mean an actual host tool decision; without those callbacks the decision buttons are disabled. For a user questionnaire, use Approval Question instead.

Props

For rendered tool content, the additive AgentTimelineToolEntryBlock.outputContent slot accepts a host-composed node such as the public CodeBlock or MarkdownRenderer from @yuhuanowo/yunui/content. It takes precedence over plain output and appears inside the tool's disclosure. The legacy AgentTimelineBlock.output remains a string; the host still owns the content and every tool side effect.

PropTypeDefaultDescription
blocks*AgentTimelineEntry[]—
classNamestring—
defaultOpenbooleantrueThe global summary starts open to retain the previous visible-row default.
labelsAgentTimelineLabels—
onApprove((id: string) => void)—
onOpenChange((open: boolean) => void)—
onReject((id: string) => void)—
onToggleDiff((id: string, open: boolean) => void)—
onToggleRow((id: string, open: boolean) => void)—
openboolean—Controlled run summary. Without onOpenChange it is read-only.
renderContent((text: string) => ReactNode)—Render reasoning text (e.g. with a Markdown renderer). Plain text by default.

On this page