@filigran/chatbot 3.7.3 → 3.9.0

package/README.md

@@ -6,11 +6,18 @@ Filigran chat panel — a standalone React + Tailwind chatbot component with SSE
 
 - 🔄 **SSE Message Streaming** — Real-time response streaming with status indicators
 - ⚡ **Mid-Run Steering** — Send messages while the agent is generating; they are injected into the running agentic loop instead of waiting for the turn to finish
-- 🗂️ **Conversation History** — Switch between (and delete) past conversations from a history menu in the header
+- ✋ **Tool Approval** — When the agent stops at a tool that needs a human's consent, the turn pauses mid-answer and the reviewer approves, declines with a reason, or approves always — opt-in per host, see [Tool approval](#post-apibaseurlapiendpointsapprove)
+- 🗂️ **Conversation History** — Switch between (and delete) past conversations from a header menu, or from a permanent sidebar in fullscreen mode (collapsible, searchable past 7 entries, rename in place)
 - 🤖 **Multi-Agent Support** — Switch between different AI agents
 - 📎 **File Attachments** — Upload and paste files (PDF, TXT, images)
 - 📥 **Agent-Generated Files** — Renders downloadable file cards from agent output and strips the `[[FILE:id]]` markers from the prose
-- 📝 **Full Markdown** — Tables, code blocks with copy button, lists, blockquotes
+- 📝 **Full Markdown** — Tables (mis-delimited ones repaired), code blocks with copy button, lists, blockquotes, soft line breaks, inline images with a lightbox
+- 🖼️ **Image Previews** — `data:image/*` charts and image attachments render inline, click to expand
+- 📋 **Copy & Rate** — Copy any answer; optional 👍/👎 feedback wired to the host
+- 🧰 **Composer Toolbar** — Prompt library and quota indicator, both driven by whether the host serves the route; plus a slot for the host's own controls
+- 🧠 **Context Gauge** — Ring + percentage showing how full the model's context window is, so a long chat's silent summarising is visible before it happens
+- 🎙️ **Dictation** — Speech-to-text via the browser's own Web Speech API; no endpoint, no key, hidden where unsupported
+- ✍️ **Draft Recovery** — Unsent composer text is kept per conversation and restored when the panel reopens
 - 🎨 **Customizable Theme** — Accent color and logo customization
 - 📱 **3 Display Modes** — Floating, sidebar (resizable), and fullscreen
 - 💾 **Persistence** — Conversation and sidebar width saved to localStorage
@@ -74,6 +81,10 @@ import { ChatPanel } from '@filigran/chatbot';
 | `onWidthChange`     | `(width: number) => void`                 | —            | Called when sidebar width changes during resize                  |
 | `onResizeStart`     | `() => void`                              | —            | Called when resize drag starts                                   |
 | `onResizeEnd`       | `() => void`                              | —            | Called when resize drag ends                                     |
+| `onMessageFeedback` | `(id, feedback, message) => void`         | —            | Enables 👍/👎 on completed assistant answers and receives each rating (`null` clears it). Omit to hide the affordance — the panel stores nothing itself. |
+| `disableImagePreviews` | `boolean`                              | `false`      | Render image attachments as download cards instead of inline previews |
+| `contextUsageEnabled` | `boolean`                               | `true`       | Show how full the model's context window is for the current conversation (ring + percentage in the composer toolbar). Data-driven, so it stays absent until the backend reports occupancy — see [Context usage](#context-usage). |
+| `composerToolbar`   | `React.ReactNode`                         | —            | Extra controls appended to the composer toolbar. The escape hatch for host-specific affordances (XTM One's session-tool picker) — the package never learns what they are. Pass nothing and the toolbar simply has none. |
 
 #### Resizable Sidebar Example
 
@@ -219,6 +230,12 @@ the chat. Set `apiEndpoints.history` to `null` to hide the history menu
 entirely, or point it at a dedicated path if your proxy can't route `GET` on
 the sessions path.
 
+### `PATCH {apiBaseUrl}/chat/sessions/{conversation_id}`
+
+Renames a conversation. Body: `{ "title": "..." }`. Only reached from the
+fullscreen sidebar; a backend without the route simply fails the request and
+the row reverts to its previous title.
+
 ### `DELETE {apiBaseUrl}/chat/sessions/{conversation_id}`
 
 Deletes a conversation from the history menu. Any 2xx response counts as
@@ -378,6 +395,134 @@ data: {"type": "stream", "content": "Follow-up answer to the steering message"}
 data: {"type": "done", "content": "Follow-up answer to the steering message", "conversation_id": "uuid"}
 ```
 
+### `POST {apiBaseUrl}{apiEndpoints.approve}`
+
+Answers a turn that paused because the agent proposed a tool call requiring a
+human's consent. **Opt-in: there is no default path.** The widget advertises
+approval support to the backend only when `apiEndpoints.approve` is set, and
+that flag is a promise — a backend that pauses a turn waits indefinitely for a
+decision, with no timeout. A host that names a path it cannot route would
+receive the pause, POST the decision into a 404, and hang the turn with the
+user watching a spinner. Leave it unset and the backend degrades to an ordinary
+assistant message explaining what it could not run, so an un-updated host keeps
+working untouched.
+
+When set, `supports_tool_approval: true` is sent on every `rest` message body.
+
+**Server → client**, on the existing SSE stream, alongside `stream` / `status` /
+`done`:
+
+```
+data: {"type": "approval_required", "conversation_id": "uuid-here", "proposals": [
+  {
+    "tool_call_id": "call_abc123",
+    "tool_name": "opencti_delete_entity",
+    "tool_description": "Permanently delete an entity from the platform.",
+    "arguments": {"entity_id": "e-123", "cascade": true},
+    "input_schema": {"type": "object", "properties": {
+      "entity_id": {"type": "string", "description": "Entity to delete"},
+      "cascade": {"type": "boolean", "description": "Also delete linked entities"}
+    }},
+    "source": "integration:opencti"
+  }
+]}
+```
+
+The turn is **not** over: no `done` arrives, the stream stays open and silent
+(kept alive by SSE `: keepalive` comment lines, which the reader drops), and the
+rest of the turn continues on it once a decision is sent. The progress bubble is
+replaced by the prompt, which renders each argument next to its description from
+`input_schema` — `cascade: true` is unjudgeable on its own, so a prompt showing
+only names and values would be a rubber stamp.
+
+**Client → server**, one decision per proposed call:
+
+```json
+{
+  "conversation_id": "uuid-here",
+  "decisions": [
+    { "tool_call_id": "call_abc123", "decision": "approve" },
+    { "tool_call_id": "call_ghi789", "decision": "reject", "rejection_reason": "Wrong target environment." },
+    { "tool_call_id": "call_jkl012", "decision": "approve_always" }
+  ]
+}
+```
+
+| `decision`       | Effect                                                              |
+| ---------------- | ------------------------------------------------------------------- |
+| `approve`        | Runs with the arguments exactly as proposed                          |
+| `reject`         | Does not run; the agent receives `rejection_reason` and can adapt    |
+| `approve_always` | Runs, **and** saves a standing approval for this user                |
+
+Every proposed `tool_call_id` must appear exactly once — the backend refuses a
+partial set, because resuming with an undecided call leaves a `tool_use` block
+without its `tool_result`, which the model providers reject outright. The prompt
+therefore submits itself once the last card is decided. A set containing
+`approve_always` waits for an explicit Confirm instead: it is the only verdict
+whose reach outlives the turn (it applies to the user's unattended scheduled
+runs too), so the warning has to be read before it is committed.
+
+A decision carries no arguments. Correcting a wrong proposal is what
+`reject` with a reason is for — rewriting a call under the agent's name would
+leave a transcript crediting it with arguments it never chose.
+
+On a non-2xx the prompt stays on screen with the failure noted and the controls
+re-armed: the turn is still paused either way, so clearing the prompt would
+strand it with nothing able to answer. A `409` means nothing is waiting any more
+(the turn finished, was cancelled, or was answered elsewhere); the stream ending
+then clears the prompt on its own. Stopping the turn also dismisses it — the
+backend waits indefinitely by design, so abandoning the stream is the reviewer's
+only other way out.
+
+**Proxied hosts:** the decision goes through the same fetch path as every other
+endpoint — relative to `apiBaseUrl` and honouring `requestHeaders` — so CSRF
+wrappers and per-request context headers keep working. A proxy in front of the
+chat must forward the request body whole (a proxy rebuilding it from a fixed
+field list silently drops `supports_tool_approval`), never time out the
+streaming turn, and pass SSE keepalives through untouched.
+
+#### Recovering a prompt after a page reload
+
+`approval_required` is a single event on a stream, so a reload loses it —
+including the `tool_call_id`s a decision has to name — while the turn goes on
+waiting for an answer that can no longer be given. To the user that is a chat
+which simply stopped replying.
+
+Set `apiEndpoints.pendingApprovals` (XTM One: `/chat/conversations`) and the
+panel asks once per conversation, on mount and on every conversation switch:
+
+```
+GET {apiBaseUrl}{apiEndpoints.pendingApprovals}/{conversation_id}/pending-approvals
+→ {
+    "conversation_id": "uuid-here",
+    "proposals": [ /* as the event carried */ ],
+    "turn": "running" | "idle"
+  }
+```
+
+An empty `proposals` is the ordinary answer. A non-empty one re-renders the same
+prompt, and the decision is POSTed exactly as before. Like `approve` this has no
+default and is skipped when unset, leaving the live flow untouched.
+
+The recovered turn resumes with the reasoning and tool results it had already
+produced — but **not on a stream**: the one it would have reported on died with
+the old page, so the backend persists the answer and suppresses the live `done`
+frame. So after a decision on a recovered prompt the panel shows its ordinary
+working indicator and polls this route every 5s, using `turn` as the stop
+condition: while it reads `running` it keeps waiting, and the moment it reads
+`idle` it re-reads the conversation once — the answer is there. A resumed turn
+that pauses *again* on a second gated call is picked up by the same poll, which
+is the only way that prompt could reach the user with no stream open.
+
+One bound applies server-side: after 30 minutes with **no sign of a client** and
+no decision, the turn stops waiting and the pause is discarded. Any request about
+the conversation counts as a sign, so while a recovered prompt is displayed the
+panel re-reads this route every 10 minutes purely to say someone is still there —
+a tab left open makes no requests of its own, and the bound is meant to limit
+abandonment, never the person deciding.
+
+REST backend only: `legacy` and `ag-ui` never meet this gate.
+
 ## Customization
 
 ### Custom Logo
@@ -464,6 +609,18 @@ function App() {
 - `'Uses AI. Verify results.'`
 - `'How can I help you, '`
 - `'Suggestions'`
+- `'Waiting for your approval…'`
+- `'The agent needs your approval to run a tool:'` / `'The agent needs your approval to run these tools:'`
+- `'Yes'` / `'No'` / `'Yes, always'` / `'Back'` / `'Confirm'` / `'Sending…'` / `'decided'`
+- `'Approved'` / `'Declined'` / `'Always allowed'`
+- `'Decline this call'`
+- `'Why not? The agent sees this and can adapt (optional)'`
+- `'e.g. wrong environment — use staging instead'`
+- `'Also applies to your scheduled runs, until you revoke it'`
+- `'“Yes, always” saves a preference for you. That tool will then run without asking — including on scheduled runs nobody is watching — until you revoke it.'`
+- `'This turn is no longer waiting for a decision.'`
+- `'Could not send your decision. Please try again.'`
+- `'This decision could not be sent. Reload the chat and try again.'`
 - `'Floating'`
 - `'Sidebar'`
 - `'Full screen'`
@@ -478,11 +635,142 @@ import '@filigran/chatbot/styles.css';
 
 The component uses Tailwind CSS classes and CSS custom properties for theming. The accent color is applied via `--chat-accent` CSS variable.
 
+### Composer toolbar
+
+Two toolbar items are **data-driven rather than mode-driven**: they appear only
+when the host serves the route, so the UI can never advertise something the
+backend cannot answer, and there is no mode flag to keep in step.
+
+| Endpoint | Default path | Response |
+| --- | --- | --- |
+| Prompt library | `GET {apiBaseUrl}/chat/prompts` | `[{ id, title, content, description? }]` (or `{ prompts: [...] }`) |
+| Quota status | `GET {apiBaseUrl}/chat/quota` | `{ used: number, limit: number \| null, period: string }` |
+| Agent suggestions | `GET {apiBaseUrl}/chat/suggestions?agent_slug=<slug>` | `["..."]` (or `{ suggestions: [...] }`, or objects with `prompt`/`label`/`text`) |
+
+Set either to `null` in `apiEndpoints` to hide it. `limit: null` means no
+ceiling — the indicator then shows consumption without a bar. The quota is
+re-read whenever a turn finishes.
+
+The welcome screen names the selected agent and shows its own suggestions —
+which is also how switching agent is confirmed: the thread resets to that
+screen, so without it nothing tells you who the next message will reach. When
+the suggestions route is unavailable the host's `promptSuggestions` prop is used
+instead, so the section is never empty.
+
+Dictation needs no configuration at all: it uses the browser's own Web Speech
+API, so the mic button appears wherever the API exists and is simply absent
+elsewhere. Finalised phrases are appended to the composer (never replacing a
+draft), interim words preview beside the button, and sending stops the mic so
+the next words cannot land in a composer the user just emptied.
+
+### Context usage
+
+The composer also carries a context gauge — a small ring plus percentage
+showing how full the model's context window is for the current conversation,
+the affordance Cursor popularised. It answers one question: *is this
+conversation about to get shorter than I think?* Long chats do not fail at the
+window, they get silently summarised, and a user who cannot see that coming
+reads the summary's gaps as the assistant forgetting.
+
+Clicking it opens a breakdown: one stacked bar over the window plus a colour
+legend, so "why is this chat 84 % full" has an answer the user can act on —
+usually "the tool results", sometimes "the MCP tools you wired up".
+
+Unlike the items above it needs no endpoint of its own. The backend reports the
+occupancy on the frames it already sends:
+
+| Frame | Extra keys | When |
+| --- | --- | --- |
+| `status: "thinking"` | `context_tokens`, `context_window`, `context_breakdown?` | Each agent-loop iteration, so the gauge climbs during a long turn |
+| `done` | same | Closing value for the turn — a turn whose last iteration compacted ends lower than it peaked |
+| Restored message (`POST /chat/sessions`) | same | On the newest assistant message, so a reload or conversation switch restores the gauge |
+
+`context_tokens` and `context_window` are required together and the window must
+be positive: a token count with no window to measure it against is not a ratio.
+Anything else is ignored, so a backend that reports nothing simply has no gauge —
+and a host on an older backend needs no configuration change.
+
+`context_breakdown` is optional and validated independently, so a malformed one
+costs the gauge its detail but never its number. Keys, all optional, in tokens:
+
+| Key | Legend row |
+| --- | --- |
+| `system` | System prompt |
+| `tools` | Tool definitions |
+| `dynamic_tools` | MCP & dynamic tools |
+| `summary` | Summarized conversation |
+| `tool_results` | Tool results |
+| `conversation` | Conversation |
+
+Only positive values are shown, so a chat with no digest yet simply has no
+"Summarized conversation" row. **The values must sum to `context_tokens`** — the
+popover shows the lines and the headline together, and a breakdown whose parts
+do not add up reads as broken numbers rather than as rounding. A producer doing
+per-bucket integer division has to distribute the remainder rather than drop it.
+
+Colours track the backend's own thresholds, not a design choice: neutral below
+80 % (where XTM One's agent loop starts distilling older turns into a summary),
+amber past it, red past 95 % (where it emergency-prunes). `used` is a
+char-derived estimate of what the next call will carry — deliberately a forecast
+rather than a receipt for the turn that just ended, which is why the figures are
+prefixed with `~`.
+
+Only the `rest` backend carries the figures today.
+
+Anything host-specific goes through `composerToolbar`:
+
+```tsx
+<ChatPanel
+  composerToolbar={<MySessionToolPicker />}
+  {...rest}
+/>
+```
+
+## Markdown Helpers
+
+A host that renders assistant prose with its **own** markdown component (its
+design tokens, its icon set) should still normalise the text the same way the
+panel does, rather than maintaining a divergent copy. These pure
+`string → string` helpers ship from the dedicated **`@filigran/chatbot/markdown`**
+entry point — ~2 kB, no React, no CSS. Import them from there and never from the
+package root, which is the full panel bundle:
+
+```tsx
+import {
+  hardenNestedCodeFences,
+  markdownUrlTransform,
+  normalizeImageMarkdown,
+  normalizeMarkdownTables,
+  wrapBareJson,
+} from '@filigran/chatbot/markdown';
+
+const processed = hardenNestedCodeFences(
+  normalizeMarkdownTables(wrapBareJson(normalizeImageMarkdown(content))),
+);
+
+<ReactMarkdown urlTransform={markdownUrlTransform}>{processed}</ReactMarkdown>;
+```
+
+Order matters: alt-text is flattened before anything reads line structure, and
+the JSON wrap must see the raw payload before fences are hardened.
+
+| Helper                    | Fixes                                                                                                          |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `normalizeImageMarkdown`  | Multi-line `![alt](url)` alt text, which breaks the image into literal paragraphs plus a stray link             |
+| `wrapBareJson`            | A whole message that is raw JSON — fenced as ```json so it stays readable and copyable                          |
+| `normalizeMarkdownTables` | A delimiter row whose column count doesn't match the header, including tables nested in blockquotes / list items |
+| `hardenNestedCodeFences`  | A ```markdown block containing its own ``` fences, which shatters the snippet into alternating code and prose   |
+| `markdownUrlTransform`    | react-markdown's default sanitiser stripping `data:image/*` URIs (code-interpreter charts). Still blocks `javascript:` and non-image `data:` |
+
+None of them touch content they don't apply to — an already-valid document is
+returned byte-identical.
+
 ## Peer Dependencies
 
 - `react` >= 18
 - `react-dom` >= 18
 - `react-markdown` >= 10
+- `remark-breaks` >= 4
 - `remark-gfm` >= 4
 
 ---

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { FunctionComponent } from 'react';
 
 type ChatMode = 'sidebar' | 'floating' | 'fullscreen';
 type BackendType = 'legacy' | 'rest' | 'ag-ui';
+/** A user's rating of one assistant answer. */
+type MessageFeedback = 'up' | 'down';
 /**
  * Custom API endpoint configuration.
  * When using single endpoint mode (like OpenCTI's /chatbot), set singleEndpoint to true
@@ -23,6 +25,46 @@ interface ApiEndpoints {
      * disable mid-run steering entirely.
      */
     steer?: string | null;
+    /**
+     * Path for submitting tool-approval decisions when the agent pauses on a
+     * gated tool call. The widget POSTs
+     * `{ conversation_id, decisions: [{ tool_call_id, decision, rejection_reason }] }`
+     * and the paused turn resumes on the same stream with the tool result.
+     *
+     * **No default, unlike every sibling entry, and that is deliberate.** Setting
+     * this is what makes the widget advertise `supports_tool_approval` to the
+     * backend, and advertising it is a promise to answer: a backend that pauses a
+     * turn waits indefinitely for a decision, with no timeout and no safe default
+     * action to take on the reviewer's behalf. If this path defaulted to XTM
+     * One's own route, a host proxying the chat (OpenCTI, OpenAEV, OpenGRC) could
+     * upgrade the widget without adding the matching proxy route, claim support,
+     * receive the pause, POST the decision into a 404 — and hang the turn with
+     * the user watching a spinner.
+     *
+     * While unset the widget never claims support and the backend degrades to a
+     * plain assistant message explaining what it could not run, which is why an
+     * un-updated host keeps working untouched.
+     *
+     * REST backend only: `legacy` and `ag-ui` never meet this gate.
+     */
+    approve?: string | null;
+    /**
+     * Base path for recovering what a paused turn is still waiting on, read as
+     * `GET {apiBaseUrl}{pendingApprovals}/{conversation_id}/pending-approvals`
+     * (the same base-plus-suffix idiom as {@link ApiEndpoints.download}). XTM
+     * One serves it at `/chat/conversations`.
+     *
+     * `approval_required` is a single event on a stream, so a reload loses it —
+     * including the `tool_call_id`s a decision has to name. The turn is left
+     * waiting for an answer nobody can give, which reads as a chat that simply
+     * stopped replying. The panel therefore asks once per conversation on mount;
+     * an empty list is the ordinary answer.
+     *
+     * No default, for the same reason as {@link ApiEndpoints.approve}: a proxied
+     * host has to expose the route before the panel starts calling it. Unset, the
+     * live flow still works and only reload recovery is absent.
+     */
+    pendingApprovals?: string | null;
     /** Path for fetching agents. Default: '/chat/agents'. Set to null to disable. */
     agents?: string | null;
     /** Path for fetching session history. Default: '/chat/sessions'. Set to null to disable. */
@@ -51,6 +93,140 @@ interface ApiEndpoints {
      * unless this path is set explicitly to a proxy route.
      */
     download?: string | null;
+    /**
+     * Path for the prompt library shown in the composer toolbar.
+     * Default: '/chat/prompts'. Set to null to hide the affordance.
+     *
+     * Visibility is data-driven on purpose: a host that does not serve this
+     * route simply has no prompt button, so there is no separate "mode" to keep
+     * in step with what the backend actually implements.
+     */
+    prompts?: string | null;
+    /**
+     * Path for the quota indicator shown in the composer toolbar.
+     * Default: '/chat/quota'. Set to null to hide the affordance.
+     */
+    quota?: string | null;
+    /**
+     * Path for per-agent suggested actions shown on the welcome screen.
+     * Default: '/chat/suggestions'. Set to null to always use the host's
+     * `promptSuggestions` prop instead.
+     *
+     * Called as `GET {suggestions}?agent_slug=<slug>`. A backend that ignores
+     * the parameter still answers with a generic set, so the same route carries
+     * both today's generic suggestions and per-agent (later per-user) ones.
+     */
+    suggestions?: string | null;
+}
+/** A reusable prompt the user can insert into the composer. */
+interface ChatPromptTemplate {
+    id: string;
+    title: string;
+    /** The text inserted into the composer when picked. */
+    content: string;
+    description?: string;
+}
+/**
+ * Agentic quota headroom for the current user, as the composer indicator needs
+ * it — deliberately just the three numbers it renders. Where the limit comes
+ * from (user override, group, platform, licence) is the host platform's own
+ * business and has no place on an embedded surface.
+ */
+interface ChatQuotaStatus {
+    used: number;
+    /** null means unlimited — the indicator then shows usage without a bar. */
+    limit: number | null;
+    /** Human-readable period label, e.g. "monthly". */
+    period: string;
+}
+/**
+ * One tool call the agent wants to make and is waiting on a human to approve.
+ *
+ * `inputSchema` travels alongside `arguments` so each value can be rendered
+ * with the tool's own description of what it means. That pairing is the whole
+ * point: `cascade: true` is unjudgeable on its own, while "cascade — also
+ * delete linked entities" is a decision someone can actually make. A prompt
+ * that shows names and values alone is a rubber stamp wearing the costume of a
+ * safety control.
+ */
+interface ToolApprovalProposal {
+    /**
+     * Identity of the proposed call, and the key every decision is sent back on.
+     * Never the tool name: one turn can propose the same tool twice with
+     * different arguments.
+     */
+    toolCallId: string;
+    toolName: string;
+    toolDescription?: string;
+    arguments: Record<string, unknown>;
+    /** JSON Schema the arguments came from, used to label each one. */
+    inputSchema?: Record<string, unknown>;
+    /** Where the tool comes from, e.g. `integration:opencti`. */
+    source?: string;
+}
+/**
+ * A reviewer's verdict on one proposed call.
+ *
+ * There is deliberately no "edit the arguments" verdict. Rewriting a call under
+ * the agent's name would leave a transcript crediting it with arguments it
+ * never chose, and turn a yes/no judgement into authoring. A wrong proposal is
+ * corrected by rejecting it with a reason the agent can act on.
+ */
+type ToolApprovalVerdict = 'approve' | 'approve_always' | 'reject';
+/** One decision, ready to be sent back to the paused turn. */
+interface ToolApprovalDecision {
+    toolCallId: string;
+    verdict: ToolApprovalVerdict;
+    /**
+     * Why the call was declined. Optional, and the agent's only signal to correct
+     * itself — with argument editing gone, a rejection *is* the correction
+     * channel.
+     */
+    rejectionReason?: string;
+}
+/**
+ * How full the model's context window is for the current conversation, as the
+ * composer gauge needs it — a ratio, so both halves are required.
+ *
+ * `used` is the backend's own estimate of what the next turn will carry, not a
+ * billed token count: it is the figure the agent loop budgets its compaction
+ * against, which is what makes the gauge predictive of the summarising the user
+ * is about to see rather than a receipt for the turn that just ended.
+ */
+interface ChatContextUsage {
+    /** Estimated tokens currently occupying the window. */
+    used: number;
+    /** The model's context window, in tokens. Always > 0. */
+    limit: number;
+    /** Where those tokens went, when the backend reports it. */
+    breakdown?: ChatContextBreakdown;
+}
+/**
+ * What the context is being spent on, in tokens.
+ *
+ * Buckets are grouped by what the user can *do* about each: they can start a new
+ * chat (`conversation`), they cannot shrink the agent's persona (`system`), and
+ * the two the backend manages on their behalf (`summary`, `toolResults`) are
+ * what explain a long chat that seems to have forgotten things.
+ *
+ * Every key is optional and only non-zero ones are reported, so a backend that
+ * measures a different set — or none — still renders. Tool definitions are
+ * included even though some backends may not count them in their compaction
+ * gate; the gauge is meant to reflect what the prompt actually carries.
+ */
+interface ChatContextBreakdown {
+    /** The agent's system prompt and any in-run instructions. */
+    system?: number;
+    /** Schemas of the platform's built-in tools. */
+    tools?: number;
+    /** Schemas of the agent's own integrations, MCP servers and custom tools. */
+    dynamicTools?: number;
+    /** Digests of earlier turns produced by the backend's compaction. */
+    summary?: number;
+    /** The user's and assistant's own messages. */
+    conversation?: number;
+    /** Output of tool calls still held verbatim in the context. */
+    toolResults?: number;
 }
 interface ChatPanelProps {
     mode: ChatMode;
@@ -138,17 +314,53 @@ interface ChatPanelProps {
     /**
      * Notify the user when a long-running turn finishes while they are not
      * watching the chat — away (tab hidden / another window) via a document-title
-     * flash and a browser notification (when already granted), or in-app but
-     * looking elsewhere via the `onTaskComplete` host toast. Default: true.
+     * flash and a browser notification (when already granted), or in-app with the
+     * chat panel closed/hidden via the `onTaskComplete` host toast. Default: true.
      */
     notifyOnComplete?: boolean;
     /**
      * Called when a long turn finishes and the user is not actively watching the
-     * chat (away, or in-app but focused elsewhere) so the host can raise its own
-     * in-app toast (the chatbot has no toast surface of its own). Receives the
-     * already-translated `title` and `body`.
+     * chat (away, or in-app with the chat panel closed/hidden) so the host can
+     * raise its own in-app toast (the chatbot has no toast surface of its own).
+     * Receives the already-translated `title` and `body`.
      */
     onTaskComplete?: (title: string, body: string) => void;
+    /**
+     * Enables the 👍/👎 affordance on completed assistant messages and receives
+     * each rating. `feedback` is `null` when the user clears a previous rating.
+     * Omit to hide the affordance entirely — the chatbot stores nothing itself,
+     * so a host without a feedback endpoint should not show the buttons.
+     */
+    onMessageFeedback?: (messageId: string, feedback: MessageFeedback | null, message: ChatMessage) => void;
+    /**
+     * Disable the inline preview of image attachments (they render as ordinary
+     * download cards instead). Previews fetch the image through the host download
+     * proxy, so hosts that meter or restrict that endpoint can opt out.
+     * Default: false.
+     */
+    disableImagePreviews?: boolean;
+    /**
+     * Show how full the model's context window is for the current conversation
+     * — a small ring plus percentage in the composer toolbar, so the user can
+     * see a long chat approaching the point where the agent starts summarising
+     * older turns and decide to split the work instead. Default: true.
+     *
+     * A host-level master switch, not a mode flag: the gauge is data-driven and
+     * simply absent until the backend reports occupancy (only the XTM One REST
+     * backend does today), so leaving this on costs nothing on a backend that
+     * says nothing.
+     */
+    contextUsageEnabled?: boolean;
+    /**
+     * Rendered into the composer toolbar, after the built-in controls.
+     *
+     * The escape hatch for anything the package has no business knowing about —
+     * XTM One's session-tool picker (integrations, MCP servers, knowledge bases)
+     * being the motivating case. A host that passes nothing gets no extra
+     * controls, so this doubles as the "product" toolbar: there is no mode flag
+     * to keep in step, only the presence or absence of what a host provides.
+     */
+    composerToolbar?: React.ReactNode;
 }
 interface ChatToggleButtonProps {
     isOpen: boolean;
@@ -162,6 +374,16 @@ interface ChatMessage {
     role: 'user' | 'assistant';
     content: string;
     timestamp: Date;
+    /**
+     * The agent that produced *this* message, when the backend says so.
+     *
+     * Takes precedence over the panel-wide name, which is the currently selected
+     * agent and therefore wrong for history: reopening a thread used to relabel
+     * every past answer with whoever happened to be picked in the menu. Optional,
+     * because no backend records per-message attribution yet — the panel falls
+     * back to the conversation's agent, then to the selected one.
+     */
+    agentName?: string;
     files?: ChatFile[];
     /** Agent-generated downloadable files attached to an assistant message. */
     attachments?: ChatAttachment[];
@@ -247,6 +469,13 @@ interface ChatConversationSummary {
     /** ISO timestamp of the last activity, used for the relative-time label. */
     updatedAt?: string;
     messageCount?: number;
+    /**
+     * The agent this conversation belongs to, when the backend reports it — so
+     * the history list can say which agent a thread is with before you open it.
+     * Undefined on backends that do not send it, null-ish for conversations that
+     * genuinely have no agent.
+     */
+    agentName?: string;
 }
 interface XtmAgent {
     id: string;
@@ -266,4 +495,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatAttachment, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatToggleButtonProps, TransferredAgent, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, XtmAgent };