Skip to content
WebJs
Menu

Displays a tool call the agent makes, from input to output.

Which package managers are installed?
Ran node --version
v24.18.0
Ran npm --version
11.6.2
Failed to run pnpm --version
command not found: pnpm

Node 24 and npm 11 are installed. pnpm is not.

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.

pnpm dlx @webjsdev/ui add trace code-block

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.

Ran git status --short
 M app/api/chat/route.ts
 M components/chat.tsx
Failed to run pnpm dev
Command timed out after 120 seconds.
Denied rm -rf dist Running pnpm test
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
Tool part statedata-statusTitle
input-streaming, input-available"running" while the chat streamsRunning …
input-streaming, input-available after the chat stops"error"Failed to run …
approval-requestednoneNot a line. An item outside the trace with Approve and Deny buttons.
approval-responded"running" if approved, none if notRunning … if approved, Denied … if not
output-availablenoneRan …
output-error"error"Failed to run …
output-deniednoneDenied …

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.

Which AI SDK version does this app use?

package.json

9 lines

{  "name": "acme-chat",  "private": true,  "dependencies": {    "@ai-sdk/react": "^4.0.0",    "ai": "^7.0.0",    "next": "^16.3.0"  }}

It uses ai 7 with @ai-sdk/react 4.

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.

Clean up the build folder.
Thought
The build output lives in dist. Deleting it cannot be undone, so I should ask before I run the command.
Run rm -rf dist?

The command runs in this project.

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:

AI SDK ElementsWebJs UI
ToolA trace with a trace collapsible.
ToolHeaderThe collapsible's <summary>, holding a trace line with an icon and a title, in place of the status badge. Map the state to the status and title as the States table does.
ToolContentThe trace collapsible content.
ToolInput, ToolOutputA small code block. The output shows errorText when the tool failed.
getStatusBadge, ToolPartNot needed: the state maps to a data-status, and the part type comes from your messages.

API Reference

See Trace.