import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, TerminalIcon } from '#lib/ui/lucide.ts';
const question = 'Which package managers are installed?';
const answer = 'Node 24 and npm 11 are installed. pnpm is not.';
type ToolPart =
| { state: 'output-available'; command: string; stdout: string }
| { state: 'output-error'; command: string; errorText: string }
| { state: 'input-available'; command: string };
const tools: ToolPart[] = [
{ state: 'output-available', command: 'node --version', stdout: 'v24.18.0' },
{ state: 'output-available', command: 'npm --version', stdout: '11.6.2' },
{ state: 'output-error', command: 'pnpm --version', errorText: 'command not found: pnpm' },
];
// One tool part as a row. A call with output expands to it, and a failed
// call starts open once the reply has finished. A call with no output yet is
// a plain line: running while the reply streams, failed once it has stopped.
function ToolRow(part: ToolPart, streaming: boolean) {
if (part.state === 'output-available' || part.state === 'output-error') {
const failed = part.state === 'output-error';
return html`
<details data-slot="trace-collapsible" ?open=${!streaming && failed} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" data-status=${failed ? 'error' : nothing} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${failed ? 'Failed to run' : 'Ran'} ${part.command}</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
<pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${failed ? part.errorText : part.stdout}</code></pre>
</div>
</div>
</details>
`;
}
return html`<span data-slot="trace-line" data-status=${streaming ? 'running' : 'error'} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${streaming ? 'Running' : 'Failed to run'} ${part.command}</span>
</span>`;
}
// The conversation once the reply has finished streaming.
export default function ToolDemo() {
return html`
<div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
<div data-slot="message" data-align="end" class=${messageClass()}>
<div data-slot="message-content" class=${messageContentClass()}>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
</div>
</div>
</div>
<div data-slot="message" data-align="start" class=${messageClass()}>
<div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
<div data-slot="trace" class=${traceClass()}>
${tools.map((part) => ToolRow(part, false))}
</div>
<p>${answer}</p>
</div>
</div>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
Replay
</button>
</div>
`;
}
View Code
Tool is a tool call the agent makes, such as running a command or reading a file. The line follows the call from input to output, including errors and calls that wait for approval.
Tool is built with a trace, with a trace collapsible for each call that has output.
Installation
Tool is built with the Trace and Code Block components.
Install the following dependencies:
Copy and paste the following code into your project.
/**
* Trace: a vertical timeline of steps (a tool call, a reasoning step, a
* deploy stage), each with an icon on a connecting line, a title and an
* optional collapsible detail. Tier-1 class helper; compose with plain
* elements and `<details>` for the collapsible part.
*
* shadcn parity:
* Trace → traceClass()
* TraceLine / TraceIcon → traceLineClass() / traceIconClass()
* TraceTitle / TraceDescription
* → traceTitleClass() / traceDescriptionClass()
* TraceCollapsible / TraceCollapsibleTrigger / TraceCollapsibleContent
* → <details> / <summary> / a div, with the
* trace collapsible helpers
*
* shadcn has no new-york version of this component, so its look in the
* default style is shadcn's vega style, the classic shadcn look.
*
* A11y (required for accessible output): a trace is an ordered list of steps,
* so render it as `<ol>` with each step an `<li>`. A step's status must be in
* text, not only in the icon colour ("Failed", "Done"), and a decorative icon
* takes `aria-hidden="true"`. A collapsible step is a native `<details>` with a
* `<summary>`, which carries the expanded state by itself.
*
* Design tokens used: --border, --muted-foreground, --foreground.
*
* @example
* ```html
* <ol class=${traceClass()} data-slot="trace">
* <li class=${traceLineClass()} data-slot="trace-line">
* <span class=${traceTitleClass()} data-slot="trace-title">Fetched the issue</span>
* </li>
* </ol>
* ```
*/
/** Set `data-slot="trace"` on the element. */
export function traceClass(): string {
return 'gap-2 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 flex w-full min-w-0 flex-col *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:text-start *:has-[>[data-slot=trace-line]]:outline-none';
}
/** Set `data-slot="trace-line"` on the element. */
export function traceLineClass(): string {
return 'gap-2 text-sm flex w-fit max-w-full min-w-0 items-center text-muted-foreground transition-colors in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer';
}
/** Set `data-slot="trace-icon"` on the element. */
export function traceIconClass(): string {
return "size-4 [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ms-1 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none";
}
/** Set `data-slot="trace-title"` on the element. */
export function traceTitleClass(): string {
return 'min-w-0 truncate motion-reduce:shimmer-none';
}
/** Set `data-slot="trace-description"` on the element. */
export function traceDescriptionClass(): string {
return 'shrink-0 text-muted-foreground/70 tabular-nums';
}
/** Set `data-slot="trace-collapsible"` on the element. */
export function traceCollapsibleClass(): string {
return 'flex w-full min-w-0 flex-col';
}
/** Set `data-slot="trace-collapsible-trigger"` on the element. */
export function traceCollapsibleTriggerClass(): string {
return 'gap-1 rounded-md focus-visible:ring-3 focus-visible:ring-ring/50 group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center text-start text-muted-foreground transition-colors outline-none hover:text-foreground has-[[data-status=error]]:text-destructive';
}
/** Set `data-slot="trace-collapsible-content"` on the element. */
export function traceCollapsibleContentClass(): string {
return 'mt-2 mb-1 ms-[calc(--spacing(2)-1px)] border-s pe-1 ps-4 leading-relaxed min-w-0 wrap-break-word text-muted-foreground';
}
Update the import paths to match your project setup.
Usage
import {
codeBlockClass,
codeBlockCodeClass,
codeBlockContentClass,
} from '#components/ui/code-block.ts';
import {
traceClass,
traceCollapsibleClass,
traceCollapsibleContentClass,
traceCollapsibleTriggerClass,
traceIconClass,
traceLineClass,
traceTitleClass,
} from '#components/ui/trace.ts';
<div data-slot="trace" class=${traceClass()}>
<details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
${TerminalIcon()}
</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Ran git status --short</span>
</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="code-block" data-size="sm" class=${codeBlockClass()}>
<pre data-slot="code-block-content" data-wrap tabindex="0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code
data-slot="code-block-code" class=${codeBlockCodeClass()}>${output}</code></pre>
</div>
</div>
</details>
</div>
States
A trace does not read tool parts. Map each part's state to a data-status and a title.
M app/api/chat/route.ts
M components/chat.tsx
Command timed out after 120 seconds.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, TerminalIcon } from '#lib/ui/lucide.ts';
// A row that expands to the command's output.
function outputRow(title: string, output: string, status: string | null) {
return html`
<details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" data-status=${status} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${title}</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
<pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${output}</code></pre>
</div>
</div>
</details>
`;
}
// A line with nothing to expand.
function line(title: string, status: string | null) {
return html`<span data-slot="trace-line" data-status=${status} class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${title}</span>
</span>`;
}
export default function ToolStates() {
return html`
<div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
${outputRow('Ran git status --short', ' M app/api/chat/route.ts\n M components/chat.tsx', null)}
${outputRow('Failed to run pnpm dev', 'Command timed out after 120 seconds.', 'error')}
${line('Denied rm -rf dist', null)}
${line('Running pnpm test', 'running')}
</div>
`;
}
View Code
A tool is a plain trace line while it runs, and a trace collapsible once its output arrives.
function toolLine(part: ToolPart, streaming: boolean) {
const command = part.input?.command;
const icon = html`<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>`;
if (part.state === 'output-denied' || (part.state === 'approval-responded' && !part.approval.approved)) {
return html`<span data-slot="trace-line" class=${traceLineClass()}>
${icon}<span data-slot="trace-title" class=${traceTitleClass()}>Denied ${command}</span>
</span>`;
}
if (part.state === 'output-available' || part.state === 'output-error') {
const failed = part.state === 'output-error';
return html`<details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" data-status=${failed ? 'error' : nothing} class=${traceLineClass()}>
${icon}<span data-slot="trace-title" class=${traceTitleClass()}>${failed ? 'Failed to run' : 'Ran'} ${command}</span>
</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="code-block" data-size="sm" class=${codeBlockClass()}>
<pre data-slot="code-block-content" data-wrap tabindex="0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code
data-slot="code-block-code" class=${codeBlockCodeClass()}>${failed ? part.errorText : part.output.stdout}</code></pre>
</div>
</div>
</details>`;
}
return html`<span data-slot="trace-line" data-status=${streaming ? 'running' : 'error'} class=${traceLineClass()}>
${icon}<span data-slot="trace-title" class=${traceTitleClass()}>${streaming ? 'Running' : 'Failed to run'} ${command}</span>
</span>`;
}
<div data-slot="trace" class=${traceClass()}>
${repeat(
message.parts.filter((part) => part.type === 'tool-runCommand'),
(part) => part.toolCallId,
(part) => toolLine(part, streaming),
)}
</div>
A tool that runs in the browser stays input-available after the chat stops until you send its output back. Treat it as waiting, not failed.
Output in a Sheet
For long output, wrap the trace line in a <ui-sheet-trigger> and show the output in the sheet.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
codeBlockClass, codeBlockContentClass, codeBlockCodeClass, codeBlockLines,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
sheetHeaderClass, sheetTitleClass, sheetDescriptionClass,
} from '#components/ui/sheet.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, FileTextIcon } from '#lib/ui/lucide.ts';
const PACKAGE_JSON = `{
"name": "acme-chat",
"private": true,
"dependencies": {
"@ai-sdk/react": "^4.0.0",
"ai": "^7.0.0",
"next": "^16.3.0"
}
}`;
const path = 'package.json';
// The conversation once the reply has finished. The read is a trace line
// wrapped in the sheet's trigger, so the long output opens beside the chat
// instead of expanding inside it.
export default function ToolSheet() {
return html`
<div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
<div data-slot="message" data-align="end" class=${messageClass()}>
<div data-slot="message-content" class=${messageContentClass()}>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Which AI SDK version does this app use?</div>
</div>
</div>
</div>
<div data-slot="message" data-align="start" class=${messageClass()}>
<div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
<div data-slot="trace" class=${traceClass()}>
<ui-sheet>
<ui-sheet-trigger>
<button type="button" class="flex w-fit max-w-full min-w-0 text-start outline-none">
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Read ${path}</span>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
</span>
</button>
</ui-sheet-trigger>
<ui-sheet-content side="right">
<div data-slot="sheet-header" class=${sheetHeaderClass()}>
<h2 data-slot="sheet-title" class=${cn(sheetTitleClass(), 'font-mono')}>${path}</h2>
<p data-slot="sheet-description" class=${sheetDescriptionClass()}>${PACKAGE_JSON.split('\n').length} lines</p>
</div>
<div data-slot="code-block" data-variant="default" class=${cn(codeBlockClass(), 'mx-6 mb-6 w-auto')}>
<pre data-slot="code-block-content" data-numbered tabindex="0" dir="ltr" style="counter-reset: line 0" class=${codeBlockContentClass()}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${codeBlockLines(PACKAGE_JSON)}</code></pre>
</div>
</ui-sheet-content>
</ui-sheet>
</div>
<p>It uses ai 7 with @ai-sdk/react 4.</p>
</div>
</div>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
Reset
</button>
</div>
`;
}
View Code
See Trace.
Approval
A pending approval is a question for the person, not a step the agent took, so it sits outside the trace as an Item. Once the person answers, the tool goes back to being a line. See Confirmation.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
itemClass, itemActionsClass, itemContentClass, itemDescriptionClass,
itemMediaClass, itemTitleClass,
} from '#components/ui/item.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleCheckIcon, TerminalIcon } from '#lib/ui/lucide.ts';
const reasoning =
'The build output lives in dist. Deleting it cannot be undone, so I should ask before I run the command.';
// The turn waiting on the person: the thinking has settled and the command
// asks for a yes or no. A pending approval is a prompt, not a step the agent
// took, so it sits outside the trace. Deny and Approve are the reader's to
// wire to the action that answers the approval.
export default function ToolApproval() {
return html`
<div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
<div data-slot="message" data-align="end" class=${messageClass()}>
<div data-slot="message-content" class=${messageContentClass()}>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Clean up the build folder.</div>
</div>
</div>
</div>
<div data-slot="message" data-align="start" class=${messageClass()}>
<div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
<div data-slot="trace" class=${traceClass()}>
<details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Thought</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'whitespace-pre-wrap')}>${reasoning}</div>
</details>
</div>
<div data-slot="item" data-variant="outline" data-size="sm" class=${itemClass({ variant: 'outline', size: 'sm' })}>
<div data-slot="item-media" data-variant="icon" class=${itemMediaClass({ variant: 'icon' })}>
${TerminalIcon()}
</div>
<div data-slot="item-content" class=${itemContentClass()}>
<div data-slot="item-title" class=${itemTitleClass()}>Run rm -rf dist?</div>
<p data-slot="item-description" class=${itemDescriptionClass()}>The command runs in this project.</p>
</div>
<div data-slot="item-actions" class=${itemActionsClass()}>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Deny</button>
<button type="button" data-slot="button" data-variant="default" data-size="sm" class=${buttonClass({ size: 'sm' })}>Approve</button>
</div>
</div>
</div>
</div>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
Reset
</button>
</div>
`;
}
View Code
if (part.state === 'approval-requested') {
return html`<div data-slot="item" data-variant="outline" data-size="sm" class=${itemClass({ variant: 'outline', size: 'sm' })}>
<div data-slot="item-media" data-variant="icon" class=${itemMediaClass({ variant: 'icon' })}>${TerminalIcon()}</div>
<div data-slot="item-content" class=${itemContentClass()}>
<div data-slot="item-title" class=${itemTitleClass()}>Run ${part.input.command}?</div>
</div>
<div data-slot="item-actions" class=${itemActionsClass()}>
<button type="button" data-slot="button" class=${buttonClass({ variant: 'outline', size: 'sm' })}
@click=${() => this.answer(part.approval.id, false)}>Deny</button>
<button type="button" data-slot="button" class=${buttonClass({ size: 'sm' })}
@click=${() => this.answer(part.approval.id, true)}>Approve</button>
</div>
</div>`;
}
answer is your component's method. It records the response and calls the action again, so the chat continues once every approval has an answer.
Migrating from AI SDK Elements
If you used Tool from AI SDK Elements, its wrapper lives in components/ai-elements/tool.tsx. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:
API Reference
See Trace.