Skip to content

Latest commit

 

History

History
363 lines (302 loc) · 19.2 KB

chat.md

File metadata and controls

363 lines (302 loc) · 19.2 KB

The chat panel

<AgentChat> is the drop-in UI: a transcript where every answer keeps its own activity, a composer with everything around the input, and optional side panels for saved chats and the agent's workspace. Every part can be switched off, relabelled, rendered by you, or swapped for your own component — and everything it does is also available as hooks and pure helpers for a fully custom UI.

import {
  AgentChat,
  ChatHistoryStore,
  VirtualFileSystem,
  createFileTools,
  useAgent,
} from '@dudko.dev/agent-web-react'
import '@dudko.dev/agent-web-react/styles.css'

const files = new VirtualFileSystem({ namespace: 'my-app' }) // IndexedDB
const history = new ChatHistoryStore()                        // IndexedDB

function Assistant() {
  const agent = useAgent({
    model,
    tools: { ...myTools, ...createFileTools(files) }, // the agent can use the workspace too
    memory: new IndexedDBStore(),                     // a reopened chat keeps its context
    toolApproval: { mode: 'ask-writes' },
  })
  return (
    <AgentChat
      controller={agent}
      title="Assistant"
      history={history}
      files={files}
      composer={{
        model: { label: 'Gemini 3.5 Flash', options: models, value, onSelect },
        thinking: { value: level, onChange: setLevel },
        convertFile: pdfToMarkdown, // PDFs the model can't read become Markdown
        dropZone: 'window',
      }}
      style={{ height: 640 }}
    />
  )
}

Contents

Transcript

Each assistant message keeps its own activity after the next run starts — the reducer mirrors the run onto the message:

  • a collapsible summary ("2 steps · 3 tool calls · skills: …"), open while the answer is being produced;
  • every step with its streamed text and thoughts;
  • every tool call — name, arguments, status, ≈tokens of its arguments and of the result fed back to the model, its duration, and any images it returned (data URLs or { type: 'image' } parts are shown as thumbnails);
  • consent decisions and subagent delegations under the step that made them;
  • the answer's thoughts (when the model thinks);
  • a usage line with tokens by kind: in 12k · out 456 · think 120 · cached 9k · 4.2 s.

User messages show their text and attachments: image thumbnails (click to open full size) and file chips. The header shows the conversation's total.

Prop Default
showActivity true the per-answer activity block
showToolCalls true each tool call inside it
showUsage true per-answer and per-tool-call tokens
showTotalUsage true the conversation total in the header
showThoughts true step and answer thoughts
showStatus true the status dot in the header
showContext false context meter above the composer (number = budget bar)
activityOpen false keep finished answers' activity expanded
emptyState labels.emptyState what the transcript shows before the first message (any node)
defaultHistoryOpen wide panel: yes · narrow: no whether the saved-chats sidebar starts open
defaultFilesOpen false whether the Files panel starts open
narrowWidth 760 below this width (px) the side panels overlay the chat

Composer

<AgentComposer> (the footer of <AgentChat>, usable on its own):

  • notices above the input: a limit that stopped the run, a compaction, a start failure, an attachment the model can't take, a microphone error — dismissible;
  • "+", Ctrl+V and drag & drop for files and images;
  • "/" commands: /compact, /new, /stop, /autopilot, /ask, /ask-all, /read-only, /think <level>, and every skill as /skill-name <goal>; add your own with commands;
  • run timer, running subagents ("2 agents"), the model + thinking chip (with a switcher), the consent-mode chip ("⚡ Auto"), a mic (speech to text with the browser's Web Speech API) and send / stop.
Prop
model { label, options?, value?, onSelect? } — chip and switcher
thinking { value, options?, onChange } — shown next to the model; default levels off (the provider's default), none (thinking off), low, medium, high
commands / builtinCommands / skillCommands slash commands
attachments false, or { accept, maxBytes, imageMaxDimension, imageMaxPixels }
convertFile / convert file → text (e.g. PDF → Markdown), 'when-needed' or 'always'
files save attachments into a VirtualFileSystem under /attachments/
dropZone 'self' (default), 'window', or a ref (<AgentChat> passes its panel)
speech false, or { lang }
steering / showQueued typing to the agent while it works; the queue strips (below)
showTimer / showAgents / showApprovalMode / showNotices toolbar parts
toolbarExtra / toolbarEnd your own toolbar content
compactWidth below this width (px) the toolbar chips show icons and numbers only (default 460)
renderAttachment render a pending attachment chip yourself
labels, placeholder, disabled, className

Speech to text uses SpeechRecognition / webkitSpeechRecognition (Chrome, Edge, Safari). In Chrome the audio is recognised by Google's service; the mic button only appears where the API exists.

Talking to the agent while it works

The input stays live during a run. Text typed then is said to the running agent (the send button, or Enter): it is shown to the model at the next boundary — between tool calls, or when the step ends, where the replanner re-checks the plan against it. It never cuts a tool call short. Needs @dudko.dev/agent-web with createRunControl (see the core's steering docs).

What the user sees:

  • a message waiting for a boundary shows above the input as queued ("waiting for the agent's next step");
  • once the agent has it, the queue entry becomes a note under the step it reached — "you said, between tool calls" / "after this step" / "before the answer". It is a note on that run, not a new turn, and it is saved with the chat;
  • a message that arrives too late for the run (while the answer is being written) is sent as the next message when the run ends (followUp, default on);
  • Stop does not send behind the user's back: whatever the run never showed the agent is offered above the input — "Not delivered (1 message)" with Send now / Discard;
  • every running subagent gets a stop button (and shows its profile, when the parent chose one). Stopping one fails only that delegation — the parent model is told and routes around it; the run and its siblings go on. It then shows as "stopped".
  • files cannot join a run that is going (they are sent with the next message) — the composer says so instead of dropping them.
const agent = useAgent(config)
agent.send('use the staging database') // false: no run in flight (or empty) — use run()
agent.stopSubagent(agent.subagents.find((s) => s.status === 'running')!.id)
agent.queued // [{ id, text }] — sent, not yet shown to the model
agent.notes // [{ id, text, at: 'round' | 'step' | 'final', stepId? }] — shown, and where
agent.undelivered // string[] — a stopped run's leftovers; sendUndelivered() / discardUndelivered()
Prop / option
steering (composer, default true) off: the input does nothing during a run, as before
showQueued (composer, default true) the queue and "not delivered" strips
showNotes (chat / message list / step list, default true) the notes under the steps
stoppableSubagents (chat, default true) the stop button on running subagents
followUp (useAgent option, default true) send what a run never showed the agent as the next message
onStopSubagent (message list / step list) wire your own stop button (useAgent().stopSubagent)

Labels: placeholderBusy, steer, noAttachmentsWhileBusy, queuedWaiting, noteAt, undelivered, sendUndelivered, discardUndelivered, stopSubagent, subagentStopped. A replan caused by a message has replan.byUser === true.

The agent's notebook, and what it fetched

With learning in the agent's config (core: learning: true, or { store: new VfsSkillStore(files) } to keep lessons as SKILL.md in the workspace) the agent writes down what it figured out. The UI follows it:

  • The turn says what the agent learned in that answer ("learned: image-format-jpg") and, with egress, what it fetched - each request with its status, a refused one with the reason ("refused: not on the allow list"). Hide it with showLearned={false} (chat / message list).
  • <LearnedSkills /> is the notebook itself: each lesson with when it applies, its revision and where it came from (the sources it named, the pages it read), and a button to forget it. Place it anywhere - a settings panel, a sidebar (slots.sidebar). Props: controller (default: the provider's), lessons (to show your own list), onForget (default controller.forgetSkill; false = read-only), showSources, hideTitle, empty, labels.
  • State: learned (the notebook, LessonView[]) belongs to the agent, not to a conversation - it survives reset and a chat switch, and the hook re-reads it whenever the agent is rebuilt (so a store that persists brings its lessons back). learnedNow / fetches are the current run's; each assistant message keeps its own learned / fetches. useAgent().forgetSkill(name) deletes one.

Labels: learnedNow, fetches, fetchRefused, notebookTitle, notebookEmpty, notebookForget, notebookRevision, notebookFrom.

Attachments: images, PDFs, files, URLs

What the composer does with each file:

Kind Goes to the model as When the model can't take it
text (.md, .json, .ts, …) inlined into the goal, fenced — (every model reads text)
image a file part (downscaled to ≤ 1568 px / 1.15 MP first) refused with a sentence the user can act on
PDF a file part converted with convertFile if given, else refused
other a file part convertFile, else refused

"Can't take it" comes from the core's agent.capabilities (images, pdf, files: true / false / unknown). Unknown means try: if the provider refuses, the run fails with an AttachmentsNotSupportedError naming the model and what to do instead — never a raw provider error.

Images are downscaled because providers bill images by their pixel size and resize anything larger themselves; a 12 MP phone photo costs the same tokens as its 1.15 MP version but uploads ten times slower.

The core also takes URLs: agent.run(goal, { files: [{ data: new URL('https://…/report.pdf') }] }) — providers that accept links fetch them themselves; for the rest the AI SDK downloads them (from a browser: subject to CORS).

Saved chats (IndexedDB)

history on <AgentChat>: true (a default ChatHistoryStore), your own ChatHistoryStore, or the result of your own useChatHistory() (to render the list elsewhere). Each chat stores the transcript with its tool calls, usage and image attachments, and its id becomes the agent's memory session — use a persistent memory (IndexedDBStore) and a reopened chat continues with the model's context intact.

The sidebar sits beside a wide panel and overlays a narrow one (under narrowWidth, default 760 px), where it starts closed.

const store = new ChatHistoryStore({ dbName: 'my-app-chats' }) // or { memory: true }
const chats = useChatHistory(agent, { store, resumeLatest: true })
chats.chats      // [{ id, title, createdAt, updatedAt, messageCount, totalUsage }]
chats.select(id) // open one
chats.newChat()  // start fresh
chats.remove(id)

Chats are saved when a run settles, not on every streamed token.

<ChatHistoryList> (the sidebar, usable on its own) also takes renderChat(chat, active, fallback) to draw a row yourself and formatTime(ms) for the timestamps.

Workspace (virtual file system)

files takes the core's VirtualFileSystem (IndexedDB, browser only — in Node use the real file system). The composer saves attachments into it under /attachments/, the Files panel shows it live (preview text and images, download, delete, upload), and createFileTools(files) gives the agent fs_list, fs_read (read-only), fs_write and fs_delete over the same files — so "summarise the PDF I attached and save the summary next to it" works.

<FilesPanel> (usable on its own) props: allowUpload / allowDelete (both default true), uploadDir (where uploads go, default /uploads), onOpen(file) (a row was clicked, in addition to the preview) and renderFile(file, fallback) to draw a row yourself.

Tool consent

With a toolApproval mode other than autopilot, consent requests appear as cards in the transcript ("Allow once", "Always allow", "Deny"); the consent chip in the composer and the /autopilot, /ask, /ask-all, /read-only commands switch the mode live, even mid-run.

<ToolApprovalPrompt> (usable on its own) takes approvals (e.g. useAgent().pendingApprovals), onApprove(id, { remember }) and onDeny(id, reason) (wire them to useAgent().approve / .deny), and allowRemember (default true; false hides "Always allow"). <ContextMeter> shows tokens against budgetTokens and, with onCompact (e.g. agent.compact), a "Compact" button — compacting disables it while it runs.

Customising

Show / hide — the show* props above, composer={false}, history, files.

Labels (i18n) — every string is a label, counted phrases are functions so plurals work in any language:

<AgentChat labels={{ send: 'Отправить', steps: (n) => `${n} шаг(ов)` }} />
// or for a whole tree:
<AgentLabelsProvider labels={ruLabels}>…</AgentLabelsProvider>

See defaultLabels for the full list (the demo ships a complete Russian set in demo/src/i18n.ts).

Render props — take over a part and keep the rest; each gets the built-in rendering as fallback:

<AgentChat
  renderContent={(m) => <Markdown>{m.content}</Markdown>}
  renderToolCall={(call, fallback) =>
    call.name === 'make_move' ? <li><ChessMove move={call.input} /></li> : fallback}
  renderAttachment={(a) => <MyThumb attachment={a} />}
  renderMessage={(m, fallback) => <Animated key={m.id}>{fallback}</Animated>}
  renderApproval={(req, fallback) => fallback}
/>

Slots — slots={{ header, headerStart, headerEnd, beforeMessages, afterMessages, footerStart, sidebar }} (header: false hides it).

Components — swap whole parts with your own (same props): components={{ Composer, MessageList, HistoryList, FilesPanel, ApprovalPrompt }}.

Theme — theme="auto" | "light" | "dark", the --awr-* custom properties (colours, radius, fonts, --awr-sidebar-width, --awr-files-width), classNames={{ root, main, header, body, footer, sidebar, files }} and className / style. Components used outside <AgentChat> get the theme tokens inside an element with class awr-theme.

Hooks and helpers for your own UI

useAgent the agent, its UI state, run(goal, { images, files, attachments, label }), send / stopSubagent (steer a running agent), forgetSkill (the notebook), consent, compact, sessionId, loadChat
useChatHistory saved chats over a ChatHistoryStore
lessonsOf the agent's own skills (agent.listLearnedSkills()) as LessonView[] - what the hook seeds the notebook with
useVirtualFiles a live listing of a VirtualFileSystem + upload / remove / read
useSpeechToText Web Speech API: { supported, listening, interim, start, stop, toggle }
useMcpServers several MCP servers, merged tools — import from @dudko.dev/agent-web-react/mcp
agentStateReducer the pure event → UI reducer
useAgentContext / useOptionalAgentContext the controller of the enclosing <AgentProvider> (the first throws outside one, the second returns undefined)
useLabels / mergeLabels / defaultLabels the labels in effect, merged over a base, and the English defaults (below)
parseSlash, filterCommands, attachmentKindOf, withAttachments, attachmentRefusal, noticesOf, formatElapsed, usageLine the composer's and transcript's pure logic
downscaleImage the image downscaler

Label reference

Every string the components show is a key of AgentLabels. Pass a partial object as labels (to a component or <AgentLabelsProvider>); whatever you leave out falls back to defaultLabels. Keys marked (fn) are functions, so plurals work in any language; (map) keys are objects keyed by something.

  • Frame and transcript: emptyState, status (map by status), history, newChat, files, totalUsage, showHistory, showFiles, close, steps (fn: n), toolCalls (fn: n), subagents (fn: n), skillsUsed (fn: names), answerThoughts, stepThoughts, usageTitle, attachments, planned, replanned (fn: mode, reason), failed, toolCostTitle.
  • Notebook and fetches: learnedNow (fn: names), fetches (fn: n), fetchRefused (fn: reason), notebookTitle, notebookEmpty, notebookForget, notebookRevision (fn: n), notebookFrom.
  • Composer: placeholder, listening, message, dropHint, attach, attachTitle, commands, commandsTitle, send, stop, dismiss, remove (fn: name), dictate, dictateTitle, stopDictation, microphone, model, thinking, toolConsent, modes (map by approval mode: { label, hint }), timerRunning, timerLast, agents (fn: n), agentsTitle, notices (map of notice texts), attachmentsOnly, seeAttachments, tooLarge (fn: name, mb), binaryText (fn: name), commandGroups (map), commandDescriptions (map), thinkingLevels (map).
  • Steering: placeholderBusy, steer, noAttachmentsWhileBusy, queuedWaiting, noteAt (map by round / step / final), undelivered (fn: n), sendUndelivered, discardUndelivered, stopSubagent, subagentStopped.
  • Files and saved chats: filesEmpty, upload, download, delete, preview, bytes (fn: n), historyEmpty, deleteChat, messagesCount (fn: n).
  • Consent: approvalLead, approve, alwaysAllow, deny, declinedReason, readOnlyTool, consentWaiting, consentAllowed, consentDenied (fn: reason?).

tests/chat.test.ts fails if a key is added to AgentLabels and not listed here.