@filigran/chatbot 3.18.1 → 3.19.1

package/CHANGELOG.md

@@ -8,6 +8,188 @@ the versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html).
 This file starts at 3.10.0; earlier releases are on the
 [releases page](https://github.com/FiligranHQ/filigran-ui/releases).
 
+## 3.19.1 — unreleased
+
+### Added
+
+- The panel speaks German, Italian, Korean, Russian and Simplified Chinese on
+  its own: a catalog for each, picked from `locale` by its language whatever
+  the region (`de-de`, `it-it`, `ko-kr`, `ru-ru`, `zh-cn`). Those languages
+  showed in English unless the host translated every key through `t`.
+  Traditional Chinese tags (`zh-TW`, `zh-HK`, `zh-Hant`) keep falling back.
+
+### Fixed
+
+- A refusal whose body has no `detail` shows its `error` when that is a
+  sentence, as the products' proxies answer (`{ "error": "..." }`, beside a
+  `status` or not), never a code (`invalid_token`, `Unauthorized`) nor a
+  status's reason phrase (`Not Found`, `Too Many Requests`). It shows above
+  the composer, in place of the answer, on a failed upload's chip, under the
+  conversation list and on a conversation that could not be loaded. The panel
+  showed its generic message instead.
+- The status line has its own wording when it has no agent's name (`The agent
+  is answering…`, `Consulting an agent…`, `Transferring to another agent…`),
+  where it filled the name with a lowercase `the agent`: `the agent is
+  answering…` started without a capital. A host translating through `t` in a
+  language the panel has no catalog for translates these three keys; it
+  translated `the agent` before, and shows them in English until it does.
+
+## 3.19.0 — unreleased
+
+### Added
+
+- `collapseUnnamedFiles`: the files a reply carries but whose markers it does
+  not name go behind one collapsed `Working files ({count})` line, all of them
+  (`true`) or those a predicate picks, instead of one card each. Opened, each
+  is listed with its card, after a thumbnail for a picture (fetched only once
+  the list opens; the picture icon when there is no URL, the fetch fails or
+  the bytes do not decode), and from 8 files a `Show less` closes it from its
+  end. Opened while following the end, it stops following once it pushes the
+  end out of view, so the list stays in view. Off unless the host asks.
+- `renderReasoningAction`: a host's action in the corner of the reasoning
+  window, shown while the window is and gone with it.
+- An image's lightbox has a Download action when the panel can download the
+  file, so a user's uploaded picture, which replaces its download card, can be
+  downloaded.
+- A `Scroll to bottom` button shows once the reader has scrolled up, and
+  brings the view back to the end, following it again.
+- Older messages load as the reader scrolling up nears the top, a second at
+  least after the last load ended, never while the view follows the end, and
+  only where the button would load them. A load that brings nothing (the
+  backend failing) stops them until the conversation is opened again; the
+  button still tries again. The button reads `Loading earlier messages…` while they load.
+- `maxFileSize` limits each attached file, next to `maxTotalSize` (none by
+  default). A file refused, whichever limit it went past (`maxFileSize`,
+  `maxTotalSize`, `maxFileCount`), is named above the text field with why; it
+  was dropped without a word. `onFileRefused(file, reason)` tells the host too
+  (`ChatFileRefusal`).
+- `acceptFileTypes` sets the file picker's `accept`, and refuses a pasted or
+  dropped file of another type (`'file-type'`). A file the browser gives no
+  MIME type (Chrome on Windows for `.md`, `.yaml`) is judged by the type its
+  extension stands for, and refused by a MIME token when it stands for none.
+- `placeholder` replaces "Ask a question...": a text, or a function of the
+  agent selected.
+- `onBeforeSend`'s draft says how many files the message carries
+  (`fileCount`).
+- The composer takes the focus after a send from it and after a switch to
+  another conversation or a new one, unless the focus is in a field, a dialog
+  or the host's page; opening the panel takes none.
+- `onBeforeMove(conversation, workspace)` is asked before a drag or a row's
+  Move menu files a conversation into a workspace (`workspace` is `null` when
+  taking it out of one): `false`, or a promise of it, leaves the conversation
+  where it was, e.g. once the user declined to share it with a workspace's
+  members. One that throws or rejects refuses the move.
+- `onConversationActionFailed(action, conversation, error)` is told when
+  deleting, renaming, moving or clearing conversations fails (`'delete'`,
+  `'rename'`, `'move'`, `'clearAll'`), with the backend's `detail` when it
+  gave one; returning `true` keeps the panel's own notice from showing.
+- A row of the conversation list shows the last message
+  (`last_message_preview`) under its title, and a small icon for a
+  conversation started in a messaging channel (`channel`), named `Started in
+  {channel}`: Slack, Teams, WhatsApp, Telegram, Discord and Google Chat out
+  of the box; `channelLabel(channel)` names another, or hides one (`null`).
+  `ChatConversationSummary` gains the optional `lastMessagePreview` and
+  `channel`.
+- `sidebarSearchThreshold` sets how many conversations the list holds before
+  its search box shows (default 7, as before; `0` shows it from the first).
+- `headerTitle` and `headerSubtitle`, a node or a function of what is on
+  screen (`ChatHeaderContext`: the conversation as the list holds it, and the
+  agent), show a title beside the header's agent name and a line under it.
+- `agentHref(agent)` makes the header's agent name a link, followed in place
+  (an http(s) URL or a path of the host's origin), and `onAgentNameClick(agent)`
+  takes a plain click on it; the chevron beside the name opens the agent
+  picker then.
+- `clearAllAction: 'archive'` words Clear all as an archive (`Archive all
+  conversations`).
+- `XtmAgent.badges`: short labels the agents list may send (`badges`, strings
+  only), shown after the agent's name in the agent picker.
+- `toolLabels`: the host's names for its tools, by raw name or as a function
+  of it, in the status line (a consult's tools too) and the reasoning details.
+  A name it does not give keeps the built-in one.
+- `sidebarSections` also takes a function of the conversation list's search,
+  `(search: ChatSidebarSearch) => ReactNode`, given what the search box holds,
+  trimmed (`''` when empty). It is drawn again when the search or the function
+  changes, so a host passes a stable one, and puts hooks in a component the
+  function returns. With it the search box shows whatever the number of
+  conversations, and a search no conversation of the user's own matches says
+  "None of your conversations matches". Sections given as an element show as
+  they are.
+
+### Fixed
+
+- The view keeps the last line in view when the thread's own box shrinks
+  while following the end (the composer growing to several lines, a tray
+  opening); only growth inside the thread was followed.
+- Earlier messages already loaded, shown by the button, leave the reader
+  where they were in every browser, as older messages fetched do.
+- A failed upload's chip says why: the upload's `detail`
+  (`ChatFile.uploadError`), or "Upload failed". It showed a bare ✕.
+- A message holding a file that failed to upload is not sent until the user
+  removes the file, turn or no turn; with no turn running it went without the
+  file, and nothing said so.
+- Files attached before a host turns `disableFileManagement` on stay shown
+  and removable; they were hidden, yet still sent, or a failed one held every
+  send without a word.
+- Deleting, renaming or clearing conversations failed silently: the panel now
+  says it under the conversation list, or under the header when the list is
+  not shown, in the backend's words when it gives some. A refused rename
+  still keeps the old title, and now undoes only that row: other changes to
+  the list made meanwhile stay.
+- The conversation list's search matches a conversation's last message and
+  its agent's name too, not its title alone.
+- A message sent in a conversation moves it to the top of its section at
+  once, with the time and its text as the preview; it stayed where it was
+  until the turn ended and the list was read again.
+- A read-only panel showed the welcome screen's "Suggestions" heading over no
+  suggestions: nothing can be sent there, so the section is left out.
+- The status line says what the turn does where it said `Thinking...`:
+  `{agent} is answering…` for each mentioned agent of a turn, with that
+  agent's name before the statuses of its run, in the voice call too
+  (`AgentStatusState.answeringAgentName`);
+  `Transferring to {agent}…` on `transfer_start`; the setup step of
+  `preparing` by its `phase` (`Loading conversation history…`, `Summarizing
+  earlier conversation…`, `Recalling memory…`, `Connecting integrations…`,
+  `Preparing tools…`, else `Preparing…`); `Compacting conversation context…`;
+  `Saving response…` on `persisting`; and `Analyzing results (step {step})…`
+  from the frame's `iteration` after the first step. A host's `statusLabel`
+  reads them as `AgentStatusState.agentName`, `phase` and `iteration`.
+- While mentioned agents answer, a message does not steer: it would reach
+  whichever of them runs. It waits for the turn, held with
+  `holdSendsDuringTurn`, as a message that cannot steer does.
+- A stored answer the server's restart cut short (`interrupted: true`,
+  `ChatMessage.interrupted`) is marked as a truncated one is, and its reasoning
+  details say why.
+- A finished answer with no text and no files says `No response was
+  generated. Please try again.`; it showed `...`.
+- A paste from an office suite or a spreadsheet (Excel, Word, PowerPoint,
+  OneNote, LibreOffice, Numbers) puts the copied text in the composer. These
+  apps copy a selection as its text, its HTML and a picture of it, and the
+  panel attached the picture and dropped the text. A paste whose files are all
+  images, with plain text and an HTML fragment that shows text, attaches
+  nothing and reaches the text box; a screenshot, a browser's "Copy image" and
+  a file copied in a file manager still attach. A picture copied together with
+  text around it (an image and its caption in Word or Outlook) is read the same
+  way: the text is pasted, the picture is not attached; copy the picture alone
+  to attach it.
+- Enter while an input method composes a word (Chinese, Japanese, Korean)
+  confirms the word instead of sending the half-typed message, renaming a
+  conversation or naming a workspace, and Escape then cancels the composition
+  without stopping the turn, closing the field or clearing a search.
+- A file dropped on the panel where it attaches none (a `readOnly` panel, one
+  with `disableFileManagement` or no upload route, or the header and the
+  conversation list of any panel) leaves the page where it is; the browser
+  opened it in the tab, away from the chat. A host's own drop zone around the
+  panel still receives the drop, and a picture or link dragged from a page
+  still goes into a text field as its address.
+- The composer's draft is written when the page goes away (`pagehide`) or is
+  hidden, so a reload right after typing keeps it; a keystroke within the
+  300 ms the draft waits before being written was lost. Two panels on one
+  conversation write only the draft typed in them, so neither erases the
+  other's.
+- A search box hidden as the list shrinks below its threshold clears its
+  query: the list stayed filtered by a search the user could neither see nor
+  clear.
+
 ## 3.18.1 — unreleased
 
 ### Fixed

package/README.md

@@ -92,6 +92,10 @@ import { ChatPanel } from '@filigran/chatbot';
 | `disableFileManagement` | `boolean`                             | `false`      | No attaching or pasting files in the composer                    |
 | `maxFileCount`      | `number`                                  | `10`         | Most files attached to one message                               |
 | `maxTotalSize`      | `number`                                  | 50 MB        | Most bytes the files attached to one message add up to           |
+| `maxFileSize`       | `number`                                  | —            | Most bytes one attached file may hold; none of its own by default, only `maxTotalSize` |
+| `acceptFileTypes`   | `string`                                  | —            | The file types the composer takes, in the file input's `accept` form (`'.pdf,image/*'`): the picker offers only these, and a pasted or dropped file of another type is refused. A file the browser gives no MIME type (Chrome on Windows for `.md`, `.yaml`) is judged by the type its extension stands for (`.md`, `.markdown`, `.yaml`, `.yml`, `.csv`, `.tsv`, `.txt`, `.log`, `.json`), and refused by a MIME token when it stands for none. Any type by default |
+| `onFileRefused`     | `(file: File, reason: ChatFileRefusal) => void` | —      | A file the composer refused: `'file-size'` (over `maxFileSize`), `'total-size'` (past `maxTotalSize`), `'file-count'` (past `maxFileCount`) or `'file-type'` (not of `acceptFileTypes`). The composer names the file and says why above the text field either way |
+| `placeholder`       | `string \| ((agent: XtmAgent \| null) => string)` | `'Ask a question...'` | The composer's placeholder, or one for the agent selected (`null` until the agents load); used as given, so the host translates it |
 | `onMessageFeedback` | `(id, feedback, message) => void`         | —            | Receives each rating of an answer (`null` clears it); `id` is the message's persisted id when the backend reported one (`done.message_id`, a restored entry's `id`), else the panel's own. On its own it enables 👍/👎 and the panel stores nothing; with `apiEndpoints.feedback` set it is called once the backend has stored the rating. With neither, no thumbs. |
 | `locale`            | `string`                                  | browser's    | BCP 47 language tag of the platform's language (e.g. `'fr-FR'`): the language of the panel's catalog for what `t` does not translate, of its message times and of read-aloud. Unset, the browser's — except that a host passing `t` gets no catalog then |
 | `disableImagePreviews` | `boolean`                              | `false`      | Render image attachments as download cards instead of inline previews |
@@ -116,10 +120,14 @@ import { ChatPanel } from '@filigran/chatbot';
 | `headerActions` / `banner` / `composerHeader` / `transcriptFooter` / `welcome` | `React.ReactNode` | — | The host's content in the header, above the thread, above the composer, after the last message, or in place of the welcome screen |
 | `renderMessageExtras` / `messageFooterActions` | `(message, { streaming }) => React.ReactNode` | — | The host's content under a message, and controls in a finished answer's footer; `streaming` while the message is the answer still being written. `message.raw` holds the backend's own fields — see [Host extensions](#host-extensions) |
 | `sidebarRowActions` | `(conversation) => React.ReactNode`       | —            | The host's controls on a row of the conversation list |
-| `sidebarHeaderActions` / `sidebarSections` | `React.ReactNode`  | —            | The host's controls beside New conversation, and sections under the list |
+| `sidebarHeaderActions` | `React.ReactNode`  | —            | The host's controls beside New conversation |
+| `sidebarSections` | `React.ReactNode \| ((search: ChatSidebarSearch) => React.ReactNode)` | — | Sections under the list; a function draws them from the list's search (`query`, trimmed), again when the search or the function changes (pass a stable one, and put hooks in a component it returns), and offers the search box whatever the number of conversations |
 | `statusLabel`       | `(status: AgentStatusState) => string \| undefined` | — | The status line's text for a status, over the built-in one |
+| `toolLabels`        | `Record<string, string> \| ((toolName: string) => string \| undefined)` | — | Tool names as the status line and the reasoning details show them, by the tool's raw name; a name it does not give keeps the built-in one (`search_iocs` → `Search Iocs`). A new function redraws every message: keep one across renders unless its labels change |
 | `waitingMessages`   | `string[]`                                | built-in     | The waiting panel's rotating messages, already translated |
 | `renderWaitingPanel` | `() => React.ReactNode`                  | —            | Replaces the waiting panel's content (its messages and the invitation to play) |
+| `renderReasoningAction` | `() => React.ReactNode`               | —            | An action in the reasoning window's corner (a game to play while the agent works), shown while the window is |
+| `collapseUnnamedFiles` | `boolean \| (attachment, message) => boolean` | `false` | Puts the files a reply does not name behind one collapsed `Working files (N)` line, with a thumbnail for each picture once opened: all of them, or those the predicate picks |
 | `fontFamily`        | `string`                                  | —            | Font of the panel's text |
 | `theme`             | `ChatPanelTheme`                          | —            | The host's colours, type and shapes; see [Custom Theme](#custom-theme) |
 | `agentMentions`     | `boolean`                                 | `false`      | `@` also mentions agents of the agent list; the message carries their ids as `mentioned_agent_ids` |
@@ -130,6 +138,14 @@ import { ChatPanel } from '@filigran/chatbot';
 | `onBeforeSend`      | `(draft) => false \| { text?, displayText?, extras? } \| void` | — | Sees every non-empty send first and takes it over (`false`), rewords it, shows the user's bubble other words or adds body fields (a message with fields of its own is held with `holdSendsDuringTurn`) — see [Host extensions](#host-extensions) |
 | `hideConversationList` | `boolean`                              | `false`      | Hides the conversation list of fullscreen and inline modes, for a rail or a task pane (usable from 320 px wide); the header's history menu stands in for it — see [Host extensions](#host-extensions) |
 | `holdSendsDuringTurn` | `boolean`                               | `false`      | A message that cannot steer is held and sent when the turn ends, instead of waiting in the composer. A turn winding down after a provisional end (until its stored end or its stream's close, at most 5 s) holds sends with or without it |
+| `onBeforeMove`      | `(conversation, workspace \| null) => boolean \| Promise<boolean>` | — | Asked before a drag or a row's Move menu files a conversation into a workspace (`null`: out of one); `false` leaves it where it was |
+| `onConversationActionFailed` | `(action, conversation \| null, error \| null) => boolean \| void` | — | A failed `'delete'`, `'rename'`, `'move'` or `'clearAll'`, with the backend's reason; return `true` when the host told the user itself, and the panel says nothing |
+| `sidebarSearchThreshold` | `number`                             | `7`          | The conversation list's search box shows above this many conversations; `0` shows it from the first |
+| `channelLabel`      | `(channel: string) => string \| null \| undefined` | — | Names the channel a row's conversation was started in (`Started in {channel}`); `null` shows nothing, `undefined` keeps the panel's names (Slack, Teams, WhatsApp, Telegram, Discord, Google Chat) |
+| `headerTitle` / `headerSubtitle` | `React.ReactNode \| ((context: ChatHeaderContext) => React.ReactNode)` | — | A title beside the header's agent name and a line under it, or functions of the conversation on screen (as the list holds it) and the agent |
+| `agentHref`         | `(agent: XtmAgent) => string \| undefined` | —          | Links the header's agent name to this address (http(s) or a path of the host's origin), in place; the chevron beside it opens the picker |
+| `onAgentNameClick`  | `(agent: XtmAgent) => void`               | —            | Takes a plain click on the header's agent name (over `agentHref`); the chevron beside it opens the picker |
+| `clearAllAction`    | `'delete' \| 'archive'`                   | `'delete'`   | What Clear all does, for its wording (`Archive all conversations`) |
 
 Plain-data props (`requestHeaders`, `apiEndpoints`, `pageContext`, `promptSuggestions`) are compared by content and callback props are called
 through a stable wrapper, so building them inline is fine. `t` and `logoIcon` are used as given: keep them stable (`useCallback` / `useMemo`),
@@ -224,8 +240,9 @@ them stable, and a new one re-renders every message, which is also how to
 refresh what they render.
 
 `onBeforeSend(draft)` sees every non-empty send first, synchronously:
-`draft.text`, `draft.source` (`'composer'`, `'host'` or `'voice'`) and
-`draft.turnRunning` (a turn is running). It returns `false` to take the send
+`draft.text`, `draft.source` (`'composer'`, `'host'` or `'voice'`),
+`draft.turnRunning` (a turn is running) and `draft.fileCount` (the files the
+message carries), e.g. to refuse a send whose files the host cannot use. It returns `false` to take the send
 over (the composer keeps its draft), or an object: `text` rewords what the
 backend receives, `displayText` is what the user's bubble shows, and `extras`
 adds body fields. The panel's own fields cannot be set this way, and a message
@@ -439,11 +456,15 @@ Returns available AI agents.
     "name": "General Assistant",
     "slug": "general",
     "icon": null,
-    "description": "A helpful general-purpose assistant"
+    "description": "A helpful general-purpose assistant",
+    "badges": ["Company"]
   }
 ]
 ```
 
+`badges` is optional: short labels, already translated, shown after the
+agent's name in the agent picker. Anything but strings is ignored.
+
 ### `POST {apiBaseUrl}/chat/sessions`
 
 Restores conversation history (and, implicitly, resolves the session).
@@ -499,8 +520,8 @@ conversation. If the endpoint responds with a non-2xx status, the component
 silently resets the stored id and starts fresh on the next message, except
 when it says nothing of the conversation: a `502`, `503` or `504` (or no
 answer at all) keeps the id and reads it back once the backend answers, and a
-`401` or `403` (expired credentials) keeps it, shows the response's `detail`
-(or "This conversation could not be loaded.") with a Retry button, and reads
+`401` or `403` (expired credentials) keeps it, shows the response's
+[reason](#a-refusals-reason) (or "This conversation could not be loaded.") with a Retry button, and reads
 it back as soon as `requestHeaders` change.
 
 Assistant history messages **should echo the same `attachments[]` array** that
@@ -535,11 +556,17 @@ Lists the user's past conversations for the history menu in the chat header.
     "conversation_id": "uuid-here",
     "title": "What is the weather?",
     "updated_at": "2026-06-10T08:30:00Z",
-    "message_count": 12
+    "message_count": 12,
+    "last_message_preview": "It is sunny in Paris.",
+    "channel": "slack"
   }
 ]
 ```
 
+`last_message_preview` and `channel` are optional: a row shows the preview
+under its title, and names a messaging channel the conversation was started
+in (see `channelLabel`).
+
 Selecting a conversation restores it through the existing
 `POST /chat/sessions` contract above. The endpoint is fetched lazily when the
 history menu opens; a backend that doesn't implement it yet (404/405) simply
@@ -556,7 +583,7 @@ the row reverts to its previous title.
 
 With [workspaces](#workspaces) on, the same route files a conversation:
 `{ "workspace_id": "uuid" }`, or `{ "workspace_id": null }` to take it out of
-its workspace. A refusal's `detail` is shown under the list.
+its workspace. A refusal's [reason](#a-refusals-reason) is shown under the list.
 
 ### Workspaces
 
@@ -632,6 +659,17 @@ Deletes a conversation from the history menu. Any 2xx response counts as
 success; deleting the active conversation resets the panel to a fresh chat so
 the next message never targets a dead conversation id.
 
+### A refusal's reason
+
+Where the panel shows why the backend refused a request, it reads the JSON body
+of the non-2xx answer: its `detail` when a string, or the `message` (or
+`detail`) of a `detail` object, as XTM One answers; else its `error` when that
+is a sentence, as the products' proxies answer (`{ "error": "..." }`, beside a
+`status` or not). A code (`invalid_token`, `Unauthorized`), a status's reason
+phrase (`Not Found`, `Too Many Requests`), anything else in the body (a
+top-level `message` included), a string over 500 characters or a body that is
+not JSON shows the panel's own, translated message.
+
 ### `POST {apiBaseUrl}/chat/messages`
 
 Sends a message and streams the response via SSE.
@@ -659,7 +697,7 @@ It must be JSON-serializable — a non-serializable value (circular reference,
 
 A refusal before the stream (a non-2xx answer: a rate limit, a refused
 option, an unknown conversation) shows the response's `detail` in place of the
-answer - a string, or the `message` (or `detail`) of an object - and
+answer ([its reason](#a-refusals-reason)), and
 "Unable to connect. Please check the configuration." when it has none; the
 handle's `send` resolves `'failed'`.
 
@@ -793,7 +831,7 @@ until the next send. On a non-2xx
 response or a network error nothing was stored: the optimistic user bubble is
 rolled back, the text is restored into the composer (prepended on its own line
 if the user already typed something new), the send resolves `'failed'` and the
-refusal's `detail`, when there is one, shows above the composer — so a backend
+refusal's [reason](#a-refusals-reason), when there is one, shows above the composer — so a backend
 without steering support degrades gracefully and the message is never silently
 lost. A `409` means no turn is running any more, an ordinary race: no notice
 shows, and with `holdSendsDuringTurn` the message is held and sent as the next
@@ -808,9 +846,9 @@ mentions or body fields of its own (`send`'s `extras`, `onBeforeSend`'s
 `extras`) never steers, since a steer reaches the agent as text alone: it waits
 for the turn to end (`holdSendsDuringTurn`), and `onBeforeSend` is asked again,
 with `turnRunning: false`, before it goes out. A file that failed to upload
-neither steers nor waits: while a turn runs, winds down or is let go of with
-the event stream, the composer offers no send and says why, and once no turn
-holds the conversation the message goes without that file. `send` and a voice
+neither steers nor waits, nor goes without that file: its chip says why (the
+upload's [reason](#a-refusals-reason)), and the composer offers no send, and says why, until the
+user removes it. `send` and a voice
 call attach no files, so this never holds them. Esc stops generating.
 
 #### Multi-segment responses
@@ -1017,7 +1055,7 @@ chat) opts into six more routes, none with a default:
 
 | `apiEndpoints` key | Request | What it does |
 | --- | --- | --- |
-| `cancel` | `POST {cancel}` with `{ conversation_id }` | Stop asks the backend to end the turn; the panel keeps reading until the stream's `cancelled` frame (or lets go after 10 s, or at once on a network error or an answer of `{ "turn": "none" }`, reading the conversation back for an end it had not read yet). A Stop pressed before the panel's own send started its turn (its stream delivered nothing yet) carries `"awaiting_send": true`, and its `none` says nothing of that turn: the Stop stays pending and is sent again, without the flag, as the turn starts (or as the answer comes, the turn started meanwhile); any other answer reached a turn, and nothing goes again. A backend may keep a Stop with that flag for the send's turn, and must then take a second cancel of one turn; a Stop without it says nothing of a later send. A refusal (non-2xx) keeps the turn running and shows its `detail` above the composer |
+| `cancel` | `POST {cancel}` with `{ conversation_id }` | Stop asks the backend to end the turn; the panel keeps reading until the stream's `cancelled` frame (or lets go after 10 s, or at once on a network error or an answer of `{ "turn": "none" }`, reading the conversation back for an end it had not read yet). A Stop pressed before the panel's own send started its turn (its stream delivered nothing yet) carries `"awaiting_send": true`, and its `none` says nothing of that turn: the Stop stays pending and is sent again, without the flag, as the turn starts (or as the answer comes, the turn started meanwhile); any other answer reached a turn, and nothing goes again. A backend may keep a Stop with that flag for the send's turn, and must then take a second cancel of one turn; a Stop without it says nothing of a later send. A refusal (non-2xx) keeps the turn running and shows its [reason](#a-refusals-reason) above the composer |
 | `skipWait` | `POST {skipWait}` with `{ conversation_id }` | `Continue now` on `status: wait_start` (`{ seconds, reason }`), for as long as the pause lasts (see the status values) |
 | `events` | `GET {events}/{conversation_id}/events?client_id=<id>` → SSE | Turns this panel did not start (another tab, a reload mid-turn), `user_message`, `conversation_title`, `approval_resolved`; every frame of a turn names it (`turn_id`, below) |
 | `messagesPage` | `GET {messagesPage}/{conversation_id}/messages?before=<message id>&limit=50&supports_artifacts=true` → `{ messages, has_more }` | "Load earlier messages" past the restored ones, offered when the restore answers `has_more: true` |
@@ -1263,9 +1301,12 @@ both. The same variables may be set in CSS on an ancestor instead.
 
 ### Internationalization
 
-The panel speaks English, French, Spanish and Japanese on its own: it ships a
-catalog for each and picks one from `locale` (`fr-FR` reads French; English, or
-a language it lacks, is its own keys). A host in another language translates
+The panel speaks English, French, German, Italian, Spanish, Japanese, Korean,
+Russian and Simplified Chinese on its own: it ships a catalog for each and
+picks one from `locale` by its language, whatever the region (`fr-FR` reads
+French, `zh-cn` Chinese; English, or a language it lacks, is its own keys).
+Traditional Chinese (`zh-TW`, `zh-HK`, `zh-Hant`) has no catalog: it reads
+English unless the host translates it through `t`. A host in another language translates
 through `t`. A host with nothing to add only passes `locale`:
 
 ```tsx

package/dist/index.d.ts

@@ -473,6 +473,30 @@ interface ChatPanelProps {
     maxFileCount?: number;
     /** Maximum total size in bytes for attached files. Default: 50 * 1024 * 1024 (50 MB). */
     maxTotalSize?: number;
+    /** Maximum size in bytes of one attached file. Default: none (only `maxTotalSize`). */
+    maxFileSize?: number;
+    /**
+     * The file types the composer takes, in the file input's `accept` form
+     * (`'.pdf,image/*'`): the picker offers only these, and a pasted or dropped
+     * file of another type is refused. A file the browser gives no MIME type
+     * (Chrome on Windows for `.md`, `.yaml`) is judged by the type its extension
+     * stands for (`.md`, `.markdown`, `.yaml`, `.yml`, `.csv`, `.tsv`, `.txt`,
+     * `.log`, `.json`), and refused by a MIME token when it stands for none.
+     * Default: any type.
+     */
+    acceptFileTypes?: string;
+    /**
+     * A file the user attached that the composer refused, and why. The composer
+     * names it and says why above the text field, whether or not the host
+     * listens.
+     */
+    onFileRefused?: (file: File, reason: ChatFileRefusal) => void;
+    /**
+     * The composer's placeholder, over "Ask a question...": a text, or one for
+     * the agent selected (`null` until the agents load). Used as given, so the
+     * host translates it.
+     */
+    placeholder?: string | ((agent: XtmAgent | null) => string);
     /** Additional HTTP headers added to chatbot API requests (messages, sessions, agents, uploads). */
     requestHeaders?: Record<string, string>;
     /**
@@ -546,7 +570,7 @@ interface ChatPanelProps {
     onMessageFeedback?: (messageId: string, feedback: MessageFeedback | null, message: ChatMessage) => void;
     /**
      * The user's language as a BCP 47 tag (`'fr'`, `'en-US'`): the language the
-     * panel speaks (its own catalog: en, es, fr, ja) where `t` does not
+     * panel speaks (its own catalog: en, de, es, fr, it, ja, ko, ru, zh-Hans) where `t` does not
      * translate a key, formats the time under each message and is the language
      * answers are read aloud in. Default: the browser's own, except that a host
      * passing `t` and no `locale` gets no catalog.
@@ -664,14 +688,42 @@ interface ChatPanelProps {
     sidebarRowActions?: (conversation: ChatConversationSummary) => React.ReactNode;
     /** Controls added beside New conversation, atop the conversation list. */
     sidebarHeaderActions?: React.ReactNode;
-    /** Sections added under the conversation list (conversations shared with the user). */
-    sidebarSections?: React.ReactNode;
+    /**
+     * Sections added under the conversation list (conversations shared with the
+     * user). A function draws them from the list's search, so they filter on
+     * what is typed, as the list does. It is drawn again only when the search or
+     * the function changes: pass a stable one (`useCallback`). Hooks go in a
+     * component it returns (`({ query }) => <Shared query={query} />`): hook
+     * calls in the function itself break once it draws another branch. With it,
+     * the search box shows whatever the number of conversations, and a search
+     * with no match among the user's own says so ("None of your conversations
+     * matches").
+     */
+    sidebarSections?: React.ReactNode | ((search: ChatSidebarSearch) => React.ReactNode);
     /** The status line's text for a status, over the built-in one; `undefined` keeps it. */
     statusLabel?: (status: AgentStatusState) => string | undefined;
+    /**
+     * Tool names as the status line and the reasoning details show them, over
+     * the raw name: by name, or a function of it (`undefined` keeps the raw name).
+     * A new function redraws every message: keep one across renders unless its
+     * labels change.
+     */
+    toolLabels?: ChatToolLabels;
     /** The rotating messages of the waiting panel, already translated. */
     waitingMessages?: string[];
     /** Replaces the waiting panel's content (its messages and the invitation to play). */
     renderWaitingPanel?: () => React.ReactNode;
+    /**
+     * An action in the corner of the reasoning window (a game to play while the
+     * agent works), shown while the window is and gone with it.
+     */
+    renderReasoningAction?: () => React.ReactNode;
+    /**
+     * Files a reply carries but whose markers it does not name go behind one
+     * collapsed "Working files (N)" line instead of one card each: all of them
+     * (`true`), or those the predicate picks. Default: one card each.
+     */
+    collapseUnnamedFiles?: boolean | ((attachment: ChatAttachment, message: ChatMessage) => boolean);
     /** Font of the panel's text; the package's own otherwise. */
     fontFamily?: string;
     /**
@@ -753,6 +805,63 @@ interface ChatPanelProps {
      * `sidebar*` slots render nothing meanwhile. Default: false.
      */
     hideConversationList?: boolean;
+    /**
+     * Asked before a conversation is filed into a workspace (`null`: taken out
+     * of its workspace), by a drag or the row's Move menu: `false` (or a promise
+     * of it) leaves it where it is, e.g. once the user declined to share it with
+     * a workspace's members. One that throws or rejects refuses the move.
+     */
+    onBeforeMove?: (conversation: ChatConversationSummary, workspace: ChatWorkspace | null) => boolean | Promise<boolean>;
+    /**
+     * Told when deleting, renaming, moving or clearing conversations fails, with
+     * the backend's reason when it gave one (`conversation` is `null` for
+     * `clearAll`). The panel says it under the conversation list (or the
+     * header) unless this returns `true`: the host told the user itself.
+     */
+    onConversationActionFailed?: (action: ChatConversationAction, conversation: ChatConversationSummary | null, error: string | null) => boolean | void;
+    /**
+     * The conversation list's search box shows once the list holds more than
+     * this many conversations; `0` shows it from the first one. Default: 7.
+     */
+    sidebarSearchThreshold?: number;
+    /**
+     * Names the channel a conversation was started in, on its row (`Started in
+     * {channel}`): a string names it, `null` shows nothing, `undefined` keeps
+     * the panel's own name (Slack, Teams, WhatsApp, Telegram, Discord, Google
+     * Chat; no other channel is shown).
+     */
+    channelLabel?: (channel: string) => string | null | undefined;
+    /** A title beside the agent's name in the header (the conversation's, say), or a function of what is on screen. */
+    headerTitle?: React.ReactNode | ((context: ChatHeaderContext) => React.ReactNode);
+    /** A line under the agent's name in the header (`Agent · Slack`, say), or a function of what is on screen. */
+    headerSubtitle?: React.ReactNode | ((context: ChatHeaderContext) => React.ReactNode);
+    /**
+     * Links the header's agent name to this address (an http(s) URL or a path
+     * of the host's own origin), opened in place; the chevron beside the name
+     * opens the agent picker then. `undefined` links nothing.
+     */
+    agentHref?: (agent: XtmAgent) => string | undefined;
+    /**
+     * Called on a click of the header's agent name, over following `agentHref`
+     * (a click with a modifier key still follows it): a host routes to the
+     * agent's page itself. The chevron beside the name opens the agent picker then.
+     */
+    onAgentNameClick?: (agent: XtmAgent) => void;
+    /**
+     * What Clear all does to the conversations, for its wording: `'archive'`
+     * says "Archive all conversations". Default: `'delete'`. A host words it
+     * otherwise through `t`.
+     */
+    clearAllAction?: 'delete' | 'archive';
+}
+/** A conversation action of the list, as `onConversationActionFailed` names it. */
+type ChatConversationAction = 'delete' | 'rename' | 'move' | 'clearAll';
+/** What the header's `headerTitle` and `headerSubtitle` functions are given. */
+interface ChatHeaderContext {
+    /** The conversation on screen as the conversation list holds it; `null` for a new chat, or before the list is read. */
+    conversation: ChatConversationSummary | null;
+    /** The agent the header names, when the agent list holds it. */
+    agent: XtmAgent | null;
 }
 /** What a marker card is drawn from. */
 interface ChatMarkerContext {
@@ -774,6 +883,8 @@ interface ChatCodeBlockContext {
     /** The answer is still streaming: the block may not be complete yet. */
     streaming: boolean;
 }
+/** Tool names as a person reads them, by the tool's raw name (see `ChatPanelProps.toolLabels`). */
+type ChatToolLabels = Readonly<Record<string, string>> | ((toolName: string) => string | undefined);
 /** Renders one fenced code block of a language (see `ChatPanelProps.codeBlockRenderers`); *code* is the block's text. `null` keeps the block as code. */
 type ChatCodeBlockRenderer = (code: string, context: ChatCodeBlockContext) => React.ReactNode;
 /** What a message slot (`renderMessageExtras`, `messageFooterActions`) is drawn with. */
@@ -844,6 +955,8 @@ interface ChatSendDraft {
     source: 'composer' | 'host' | 'voice';
     /** A turn is running. */
     turnRunning: boolean;
+    /** How many files the message carries (only the composer attaches files); always set by the panel. */
+    fileCount?: number;
     /**
      * A message held while a turn ran, asked about again as it leaves, the turn
      * over (`turnRunning: false`), each send held with it on its own. `false`
@@ -998,6 +1111,12 @@ interface ChatMessage {
      * reasoning-details affordance, mirroring the XTM One web chat.
      */
     isTruncated?: boolean;
+    /**
+     * True when the server restarted while the turn ran, so the answer stopped
+     * before it could finish (`interrupted` on the stored message): marked as a
+     * truncated answer is.
+     */
+    interrupted?: boolean;
     /**
      * The backend's own fields for the message, as it sent them: the restored
      * (or paged, or relayed) entry, or the `done` frame - or the stored end -
@@ -1105,6 +1224,17 @@ interface AgentStatusState {
     waitStartMs?: number;
     /** `consulting`: the consult the agent is waiting on. */
     consult?: ConsultStatus;
+    /** `preparing`: the setup step running (`history`, `compaction`, `memory`, `integrations`, `tools`). */
+    phase?: string;
+    /** `analyzing`: the agent's step, from 1. */
+    iteration?: number;
+    /** `transferring`: the agent the conversation goes to; `mention_answering`: the mentioned agent answering. */
+    agentName?: string;
+    /**
+     * The mentioned agent answering now, on every status of its run: a turn
+     * that answers several mentioned agents runs one after the other.
+     */
+    answeringAgentName?: string;
 }
 /**
  * A consult the agent is waiting on, as the status line shows it. A consulted
@@ -1134,7 +1264,20 @@ interface ChatFile {
     fileId?: string;
     /** Upload status: 'pending' while uploading, 'done' when uploaded, 'error' on failure. */
     uploadStatus?: 'pending' | 'done' | 'error';
+    /** Why the upload failed, as the backend said, when it said: its reason (README, "A refusal's reason"). */
+    uploadError?: string;
+}
+/** The conversation list's search, as a host's sections read it (`sidebarSections`). */
+interface ChatSidebarSearch {
+    /** What the search box holds, trimmed; `''` when it holds nothing. */
+    query: string;
 }
+/**
+ * Why the composer refused a file (see `onFileRefused`): larger than
+ * `maxFileSize`, past `maxTotalSize` with the files attached, past
+ * `maxFileCount`, or not of `acceptFileTypes`.
+ */
+type ChatFileRefusal = 'file-size' | 'total-size' | 'file-count' | 'file-type';
 /**
  * A past conversation surfaced in the history menu (REST backend only).
  * Listed via `GET {apiBaseUrl}{apiEndpoints.history ?? apiEndpoints.sessions ?? '/chat/sessions'}`
@@ -1159,6 +1302,10 @@ interface ChatConversationSummary {
      * backend reports it. Undefined on backends that do not.
      */
     workspaceId?: string | null;
+    /** The last message's text, shortened by the backend (`last_message_preview`), when it sends one. */
+    lastMessagePreview?: string;
+    /** Where the conversation was started (`channel`: `slack`, `teams`, `web`, …), when the backend reports it. */
+    channel?: string;
 }
 /**
  * A conversation the composer's `@` menu offers (see
@@ -1200,6 +1347,8 @@ interface XtmAgent {
     description: string | null;
     /** The heading the agent picker lists it under; ungrouped agents come first. */
     group?: string;
+    /** Short labels shown after its name in the agent picker (`Company`), already translated. */
+    badges?: string[];
 }
 
 /**
@@ -1220,4 +1369,4 @@ interface TransferredAgent {
 declare const voiceCallSupported: () => boolean;
 
 export { ChatPanel, ChatToggleButton, voiceCallSupported };
-export type { AgentStatusState, ApiEndpoints, BackendType, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatStreamEventInfo, ChatToggleButtonProps, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };
+export type { AgentStatusState, ApiEndpoints, BackendType, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationAction, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatFileRefusal, ChatHeaderContext, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatSidebarSearch, ChatStreamEventInfo, ChatToggleButtonProps, ChatToolLabels, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };