@filigran/chatbot 3.12.2 → 3.14.0

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+Notable changes to `@filigran/chatbot`, so a host can see what an upgrade brings
+before taking it.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+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.14.0 — 2026-10-19
+
+### Added
+
+- A deck, report or video the assistant made shows as a card where its
+  `[[PRESENTATION:…]]`, `[[REPORT:…]]` or `[[VIDEO:…]]` marker stands (#450):
+  its title, its slides, sections or scenes and length, a video's render
+  progress, and `Open in XTM One`. The marker never shows as text, mid-stream
+  or after a reload, and copy and read aloud skip it. The panel tells XTM One
+  it renders them (`supports_artifacts`); XTM One describes each one in the
+  answer's `artifacts`.
+- The fullscreen history can be grouped by workspace (#276): one foldable group
+  per workspace the user can file into, then `Not in a workspace` and
+  `Other workspaces`. A workspace is created, renamed and deleted from the
+  list, and a conversation is started in one, or moved to one from its row menu
+  or by dragging it onto a group.
+
+### Host opt-in
+
+- `apiEndpoints.artifacts` (no default; XTM One serves `/chat/artifacts`) lets
+  the deck, report and video cards download them (PDF and PowerPoint for a
+  deck, PDF for a report, MP4 for a rendered video) and follow a video while
+  it renders, through the host's proxy. Without it the cards show and link to
+  XTM One, with no download. A failed download goes to `onDownloadError`, with
+  the name of the file asked for.
+- `apiEndpoints.workspaces` (no default, like `approve`) turns the workspace
+  groups on, once the host's proxy forwards the workspace routes. A backend
+  that refuses the list leaves the history flat, as before.
+
+## 3.13.0 — 2026-10-16
+
+### Added
+
+- The assistant can act on the page the panel is mounted in (#441). The agent
+  asks for one step at a time — take a snapshot, click, open a menu, type, or
+  navigate — and the panel answers each with a fresh reading of the page.
+- The reading lists one line per control a user could act on, with its role,
+  accessible name, state and in-app destination, so the agent can name the one
+  it means.
+- `Acting on the page…` shows on the status line while a step runs.
+
+### Host opt-in
+
+- The panel offers the capability only when the host sets `apiEndpoints.approve`
+  **and** passes `onRelativeLinkClick`, because its proxy has to forward the
+  answer whole. A host that offers neither is unaffected, and a step arriving
+  without that opt-in is refused without the page being read or touched.
+
+### Security
+
+- A reading never carries a secret: a password, a one-time code or a card field
+  is masked by `type` and by `autocomplete`, and its contents cannot surface
+  through an enclosing control's name or value, nor through a heading above it.
+  Hidden, `aria-hidden`, `inert` and closed `<details>` content stays out, as
+  does the panel's own.
+- A step that would leave the page is refused rather than performed: another
+  origin, a link that opens a tab, a path that resolves off-site. A click or a
+  form submission that would load a page is cancelled while the host's own
+  handlers still run.
+- A step is refused on a control the user could not use either: disabled,
+  read-only, a masked field, a file chooser, or one no longer visible when the
+  step runs.
+- A step ends with the turn that asked for it. Stop, New chat, switching
+  conversation and closing the panel all end it, and one arriving afterwards is
+  answered rather than left to time out.
+
+## 3.12.2 — 2026-10-02
+
+### Fixed
+
+- The panel keeps its own styles inside a host that ships its Tailwind utilities
+  outside any cascade layer: the message action icons were invisible and the
+  header hover backgrounds round instead of square (#431).
+
+## 3.12.1 — 2026-10-01
+
+### Fixed
+
+- The reader can scroll up while the agent reasons or streams. The transcript
+  follows the end only while the reader is there; scrolling up stops the follow,
+  and returning to the bottom or sending a message resumes it (#429).
+
+## 3.12.0 — 2026-09-30
+
+### Added
+
+- Every message ends with a footer: an answer shows its time, reasoning details,
+  Copy response, thumbs up / down and Read aloud; a user message shows Copy and
+  its time.
+- Message times follow the new `locale` prop, and an answer is dated when it
+  completes, so the live time matches the time after a reload.
+- Persisted feedback through the new `apiEndpoints.feedback`, optimistic and
+  rolled back on error; a rating restored with the conversation is locked (#419).
+
+## 3.11.1 — 2026-09-29
+
+### Changed
+
+- The dictation button sits inside the composer, before Send, so its toolbar row
+  no longer appears alone in hosts with nothing else to put there.
+- Listening is visible on the field itself, and the composer height no longer
+  shifts.
+- Every send cancels dictation and drops the phrase still being recognised, so
+  no words land in a composer that was just emptied.
+
+## 3.11.0 — 2026-09-29
+
+### Changed
+
+- A streamed answer is rendered block by block: a chunk re-parses only the blocks
+  it can still change.
+- Streamed text and reasoning are applied once per animation frame rather than
+  once per network read.
+- The markdown renderers keep their identity, so the live answer's DOM, a
+  selection in it and its images are no longer rebuilt per chunk.
+
+## 3.10.0 — 2026-09-26
+
+### Changed
+
+- The waiting game is a link to the XTM One arcade rather than an embedded game
+  (#411).
+
+### Fixed
+
+- The agent's reasoning stays on screen instead of being replaced by the waiting
+  game (#409).

package/README.md

@@ -9,6 +9,7 @@ Filigran chat panel — a standalone React + Tailwind chatbot component with SSE
 - ✋ **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
+- 🔗 **Conversation References** — Type `@` in the composer to point the agent at another conversation; opt-in per host, see [Conversation references](#conversation-references)
 - 📎 **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 (mis-delimited ones repaired), code blocks with copy button, lists, blockquotes, soft line breaks, inline images with a lightbox
@@ -258,6 +259,78 @@ 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.
 
+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.
+
+### Workspaces
+
+The fullscreen conversation list can be grouped by workspace, the way a
+desktop assistant groups its projects: one collapsible group per workspace
+(the collapsed ones are remembered per browser), a conversation started
+inside a workspace with its group's compose button, a workspace created,
+renamed or deleted from the list, and a conversation moved between groups
+from its row menu or by dragging it onto a group.
+
+The feature is off until the host names the route:
+`apiEndpoints.workspaces` has **no default**, for the same reason as
+`apiEndpoints.approve` - a proxied host must expose every route below before
+the panel offers them. A backend that refuses the list (not licensed, an
+older proxy) also leaves the list flat.
+
+| Request | Purpose |
+| --- | --- |
+| `GET {apiBaseUrl}{workspaces}` | The caller's workspaces: a bare array or `{ "workspaces": [...] }` of `{ id, name, is_default, is_own, can_manage, is_archived }`. Archived ones are left out. |
+| `POST {apiBaseUrl}{workspaces}` | Create one: `{ "name": "..." }`. |
+| `PATCH {apiBaseUrl}{workspaces}/{id}` | Rename one: `{ "name": "..." }`. |
+| `DELETE {apiBaseUrl}{workspaces}/{id}` | Delete one (never offered for the default). Its conversations are expected back in no workspace (`workspace_id: null`), never moved to a default; the history is reloaded after the delete. |
+| `PATCH {apiBaseUrl}{history}/{conversation_id}` | File a conversation: `{ "workspace_id": "uuid" \| null }`. |
+| `POST {apiBaseUrl}{sessions}` | Carries `workspace_id` when the conversation is started inside a workspace. |
+
+`GET {history}` entries carry `workspace_id` (`null` for none). A conversation
+in no workspace is a normal state, listed under "Not in a workspace": a new
+conversation starts there unless it is started inside a workspace. A workspace the
+caller may only read (`can_manage: false`) gets a group only while it holds
+one of their conversations, and conversations filed in a workspace the list
+does not return are grouped under "Other workspaces". XTM One serves all of it
+at `/chat/workspaces` and `/chat/sessions`.
+
+### Conversation references
+
+Typing `@` in the composer - at the start of the text or after a space, never
+inside a word or an email (`a@b`) - opens a menu of the user's other
+conversations, searched by title or key as they type. A pick inserts `@<key> `, and the
+message goes out with the conversations it still references, so the agent reads
+them; a `@word` typed by hand stays plain text, and so does a pick whose `@key`
+is edited out before sending. The arrows move in the menu, Enter or Tab insert,
+Escape closes it.
+
+The feature is off until the host names the route:
+`apiEndpoints.conversationReferences` has **no default**, for the same reason
+as `apiEndpoints.approve` - a proxied host must expose the route, and forward
+the new body field, before the composer offers the menu. Unset, `@` is plain
+text and the message body is unchanged.
+
+| Request | Purpose |
+| --- | --- |
+| `GET {apiBaseUrl}{conversationReferences}?q=<text>&limit=8&exclude=<conversation_id>` | The menu: `{ "conversations": [{ id, title, key, updated_at, is_own }] }` (or a bare array), the conversations the user can open, most recent first, that `q` matches (case-insensitive): every word of `q` (split on spaces, `-` and `_`) is in the title, or the key starts with `q` - so a key typed back (`@hi-bob` for "Hi Bob"), or a key that is not made of the title's words (an accent folded, a title without Latin letters), still finds its conversation. `q` is omitted for a bare `@`, `exclude` while the conversation is not created yet. `key` is what the pick inserts after `@`, always the backend's own. `is_own: false` marks a conversation shared with the user ("Shared with you"). |
+| `POST {apiBaseUrl}{messages}` | Carries `referenced_conversation_ids: string[]`: the picks the text still holds, in the order they appear, each once, at most 5. Omitted when there is none. |
+| `POST {apiBaseUrl}{sessions}` | A restored user message may carry `conversation_refs: [{ conversation_id, title, key }]`. |
+
+The references of a sent message show as chips above it, also after a reload.
+A chip opens its conversation in the panel when the conversation list holds it
+(the list is read as soon as the thread shows a reference), and is a plain label
+otherwise - a conversation shared with the user, say. While an answer streams,
+a message with a reference waits for it instead of steering the running turn:
+a steer reaches the agent as text alone, so it would never read what the
+message references. Once the text references five conversations the menu says
+so instead of offering more. The picks of an unsent draft are kept with its text, so a
+draft restored when the panel reopens still references what it did.
+
+XTM One serves it at `/chat/conversation-references`; a host behind its own
+proxy names its route, relative to its `apiBaseUrl` (e.g.
+`conversationReferences: '/conversation-references'`).
+
 ### `DELETE {apiBaseUrl}/chat/sessions/{conversation_id}`
 
 Deletes a conversation from the history menu. Any 2xx response counts as
@@ -279,6 +352,9 @@ Sends a message and streams the response via SSE.
 }
 ```
 
+With [conversation references](#conversation-references) on, a message that
+references another conversation also carries `referenced_conversation_ids`.
+
 The optional `context` object is forwarded verbatim from the `pageContext`
 prop (REST backend only) and is omitted entirely when empty. Use it to make
 the agent aware of the user's current location/page; the shape is up to the
@@ -507,6 +583,58 @@ 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.
 
+#### Acting on the host page
+
+The same path answers `act_on_page` (XTM One #5559): with `apiEndpoints.approve`
+set **and** `onRelativeLinkClick` passed — the host's opt-in, since it hands the
+panel its navigation — the panel also sends `supports_page_actions: true`, and the
+agent may act on the page the panel is mounted in. The host's proxy must forward
+the approve route's body whole (a `page_action` answer carries no `decisions`).
+Without that opt-in a frame is answered `page_actions_not_supported`, with the
+page neither read nor acted on. Each step arrives on the stream as a
+`status` frame with `event: "page_action_required"`; the panel performs it
+(`click`, `open` — a hover, or a click when hovering opens nothing —, `type`, then
+Enter only in a field that says it is a search - `type="search"`,
+`role="searchbox"`, inside `role="search"`, or named like one (a `name`, `id`,
+`placeholder`, `aria-label` or `title` whose whole words include "search",
+"query", "filter" or "find", and only when it is the form's sole field) - never
+in a form of one unnamed field, which is as likely a create or
+rename dialog,
+or `navigate` through `onRelativeLinkClick` — never
+a page load, which would end the turn) and POSTs
+`{ conversation_id, page_action: { action_id, ok, error, url, title, snapshot } }`.
+`ok` is the action's own outcome, so a step is never retried because reading the
+page back failed; when that read throws, `ok` stands and `error` carries
+`snapshot_failed: …` with an empty snapshot. A stopped turn (Stop, New chat,
+switching conversation) abandons the action instead of acting on the page.
+
+The snapshot (`utils/pageSnapshot.ts`) lists one line per element a user could
+act on — `[e1] link "Reports" -> /dashboard/analyses/reports`, with states such as
+`(selected)`, `(pressed)`, `(menu)` for a closed menu or `(collapsed)` for a closed
+group
+— and leaves out the panel itself, hidden and inert content, and every secret
+value: a `type="password"` field, and anything whose `autocomplete` marks it as a
+password, a one-time code or a card field, so a revealed password is masked too.
+A list cut off at the size cap ends with `[truncated]`. A state the host shows by
+styling alone is invisible to it: mark toggles
+with `aria-pressed`, the current item with `aria-current`, and a clickable card
+with `role="button"`. A `409` means the
+turn no longer waits for that action, and the panel drops it.
+
+Actions that would leave the page are refused rather than performed, each
+answered with `ok: false` and a reason: a `navigate` off-site, a `click` on a
+link to another origin or one opening a new tab, a `type` on anything that is
+not a text field, a read-only field, a masked one (a password, one-time code
+or card field), a file input (whose chooser is an operating-system window), a
+target that is disabled - including one disabled by its `<fieldset>` - and one
+no longer visible when the action runs. A click never completes a native default that
+would leave the page: an anchor's navigation and a form's submission are
+cancelled while the host's own handlers still run. Clicking an in-host link is
+routed through `onRelativeLinkClick` rather than clicked, for the same reason a
+`navigate` is. An action this version does not know is answered as
+`unsupported_action` instead of being dropped, so a backend running ahead of the
+panel is not left waiting out its timeout.
+
 #### Recovering a prompt after a page reload
 
 `approval_required` is a single event on a stream, so a reload loses it —
@@ -549,6 +677,38 @@ abandonment, never the person deciding.
 
 REST backend only: `legacy` and `ag-ui` never meet this gate.
 
+### Decks, reports and videos
+
+An answer that made a deck, a report or a video carries a marker where it shows
+it: `[[PRESENTATION:<id>]]` (`[[PRESENTATION:<id>#/<slide id>]]` for one
+slide), `[[REPORT:<id>]]`, `[[VIDEO:<id>]]`. The panel sends
+`supports_artifacts: true` with every message and session restore of the REST
+backend, and XTM One then describes each one in the answer's `artifacts`; the
+panel draws a card where its marker stands. A marker is never shown as text, a
+descriptor whose marker is missing renders after the prose, and a marker with
+no descriptor renders nothing.
+
+| Field | Meaning |
+| --- | --- |
+| `kind`, `id`, `title` | `presentation`, `report` or `video`, and what it is called. |
+| `url` | Its page in XTM One: the card's `Open in XTM One` (http(s) only, new tab). |
+| `slide_count`, `slide_ref` | A deck's slides, and the slide its marker named. |
+| `section_count` | A report's sections. |
+| `scene_count`, `duration_ms`, `status`, `progress` | A video's scenes and length, and its newest render (`pending`, `running`, `ready`, `failed`, `cancelled`; progress 0-100). |
+| `downloads` | The formats it downloads in: `pdf`, `pptx`, `pptx_native`, `mp4`. Empty until a video has a finished render. |
+
+The downloads go through the host, like file downloads, once it names the
+route: `apiEndpoints.artifacts` has **no default**, for the same reason as
+`apiEndpoints.approve`. Unset, the cards show and link to XTM One, with no
+download buttons.
+
+| Request | Purpose |
+| --- | --- |
+| `POST {apiBaseUrl}{artifacts}/{kind}/{id}/download` | `{ "format": "pdf" }`: the file, saved under its `Content-Disposition` name. A failure goes to `onDownloadError` with the name of the file asked for. |
+| `GET {apiBaseUrl}{artifacts}/{kind}/{id}` | The descriptor as of now: a card asks again 10 seconds after each answer, one request at a time, for 15 minutes at most, while its video renders. |
+
+XTM One serves both at `/chat/artifacts`.
+
 ### Message feedback
 
 Every message ends with a footer. An assistant answer (once it has finished
@@ -736,6 +896,7 @@ Every key the package can ask for, grouped by where it appears:
 
 **Composer**
 
+- `'A message references at most {count} conversations'`
 - `'Ask a question...'`
 - `'Attachments wait for the current response'`
 - `'Dictate a message'`
@@ -743,11 +904,16 @@ Every key the package can ask for, grouped by where it appears:
 - `'Files uploading...'`
 - `'Insert prompt template'`
 - `'Listening...'`
+- `'No conversation matches'`
 - `'No prompt matches'`
+- `'Reference a conversation'`
+- `'Referenced conversations wait for the current response'`
 - `'Search prompts...'`
 - `'Send now'`
+- `'Shared with you'`
 - `'Stop dictation'`
 - `'Stop generating'`
+- `'Untitled conversation'`
 - `'Uses AI. Verify results.'`
 
 **Messages, markdown and files**
@@ -769,6 +935,7 @@ Every key the package can ask for, grouped by where it appears:
 - `'Image preview'`
 - `'Load earlier messages'`
 - `'Loading image…'`
+- `'Open conversation'`
 - `'Read aloud'`
 - `'Reasoning details'`
 - `'Reasoning details — turn limit reached'`
@@ -778,6 +945,23 @@ Every key the package can ask for, grouped by where it appears:
 - `'Tell us what went wrong (optional)'`
 - `'What could be improved?'`
 
+**Decks, reports and videos**
+
+- `'Download {format}'`
+- `'Not rendered yet'`
+- `'Open in XTM One'`
+- `'PowerPoint'`
+- `'PowerPoint (editable)'`
+- `'Presentation'`
+- `'Rendering {progress}%'`
+- `'Report'`
+- `'The render did not finish'`
+- `'Video'`
+- `'Waiting to render'`
+- `'{count} scenes'`
+- `'{count} sections'`
+- `'{count} slides'`
+
 **Agent status**
 
 - `'Analyzing results…'`

package/dist/index.d.ts

@@ -140,6 +140,55 @@ interface ApiEndpoints {
      * REST backend only, and not in `singleEndpoint` mode.
      */
     feedback?: string | null;
+    /**
+     * Path of the caller's workspaces, which the conversation list is grouped
+     * by (XTM One serves it at `/chat/workspaces`). The panel lists them with
+     * `GET {workspaces}`, creates one with `POST`, renames one with
+     * `PATCH {workspaces}/{id}` and deletes one with `DELETE {workspaces}/{id}`;
+     * it files a conversation with `PATCH {history}/{conversation_id}` and
+     * `{ workspace_id }`, and starts one inside a workspace by sending
+     * `workspace_id` with the session `POST`.
+     *
+     * No default, for the same reason as {@link ApiEndpoints.approve}: a
+     * proxied host has to expose all of those routes before the panel offers
+     * the feature. Unset (or a backend that refuses the list), the history is
+     * the flat list it always was.
+     *
+     * REST backend only, and not in `singleEndpoint` mode.
+     */
+    workspaces?: string | null;
+    /**
+     * Path of the conversations a message can reference with `@` in the
+     * composer (XTM One serves it at `/chat/conversation-references`). Typing
+     * `@` opens a menu searched with
+     * `GET {conversationReferences}?q=<typed text>&limit=8&exclude=<current conversation id>`,
+     * answered with `{ conversations: [{ id, title, key, updated_at, is_own }] }`:
+     * the conversations the user can open, most recent first. A pick inserts
+     * `@<key>`, and the message is sent with the ids of the picks it still
+     * holds as `referenced_conversation_ids` (at most 5); a restored user
+     * message lists them under `conversation_refs`.
+     *
+     * No default, for the same reason as {@link ApiEndpoints.approve}: a proxied
+     * host has to expose the route, and forward the field, before the composer
+     * offers the menu. Unset, `@` is plain text and the message body is
+     * unchanged.
+     *
+     * REST backend only, and not in `singleEndpoint` mode.
+     */
+    conversationReferences?: string | null;
+    /**
+     * Base path of the decks, reports and videos an answer made (XTM One serves
+     * it at `/chat/artifacts`). Their cards download one through
+     * `POST {apiBaseUrl}{artifacts}/{kind}/{id}/download` with `{ format }`, and
+     * follow a video still rendering through `GET {apiBaseUrl}{artifacts}/{kind}/{id}`.
+     *
+     * No default, for the same reason as {@link ApiEndpoints.approve}: a proxied
+     * host has to forward both routes before the cards offer them. Unset, the
+     * cards still render, with `Open in XTM One` and no download.
+     *
+     * REST backend only.
+     */
+    artifacts?: string | null;
 }
 /** A reusable prompt the user can insert into the composer. */
 interface ChatPromptTemplate {
@@ -460,8 +509,15 @@ interface ChatMessage {
      */
     agentName?: string;
     files?: ChatFile[];
+    /**
+     * The conversations a user message references with `@` (see
+     * {@link ApiEndpoints.conversationReferences}), shown as chips.
+     */
+    conversationRefs?: ChatConversationRef[];
     /** Agent-generated downloadable files attached to an assistant message. */
     attachments?: ChatAttachment[];
+    /** The decks, reports and videos an assistant message made, in marker order. */
+    artifacts?: ChatArtifact[];
     toolNames?: string[];
     toolCallCount?: number;
     iterations?: number;
@@ -526,6 +582,33 @@ interface ChatAttachment {
      */
     fileTag?: 'download_file' | 'working_file';
 }
+/** What an answer can make besides a file. */
+type ChatArtifactKind = 'presentation' | 'report' | 'video';
+/**
+ * A deck, report or video an answer made, as the backend describes it: the
+ * `artifacts` of a `done` event or of a restored answer, sent because the panel
+ * says it renders them (`supports_artifacts`). Rendered as a card where its
+ * `[[PRESENTATION:<id>]]`, `[[REPORT:<id>]]` or `[[VIDEO:<id>]]` marker stands.
+ */
+interface ChatArtifact {
+    kind: ChatArtifactKind;
+    id: string;
+    title: string;
+    /** The page that shows it in XTM One; linked only when it is http(s). */
+    url?: string;
+    /** The slide a deck's marker points at. */
+    slideRef?: string;
+    slideCount?: number;
+    sectionCount?: number;
+    sceneCount?: number;
+    durationMs?: number;
+    /** A video's newest render: `pending`, `running`, `ready`, `failed` or `cancelled`. */
+    status?: string;
+    /** That render's progress, 0-100. */
+    progress?: number;
+    /** The formats it downloads in: `pdf`, `pptx`, `pptx_native`, `mp4`. Empty until a video is rendered. */
+    downloads: string[];
+}
 interface ChatFile {
     name: string;
     type: string;
@@ -556,6 +639,42 @@ interface ChatConversationSummary {
      * genuinely have no agent.
      */
     agentName?: string;
+    /**
+     * The workspace the conversation is filed in (`null`: none), when the
+     * backend reports it. Undefined on backends that do not.
+     */
+    workspaceId?: string | null;
+}
+/**
+ * A conversation the composer's `@` menu offers (see
+ * {@link ApiEndpoints.conversationReferences}).
+ */
+interface ChatConversationReferenceCandidate {
+    id: string;
+    title: string;
+    /** What the pick inserts after `@`: the backend's own, never one computed here. */
+    key: string;
+    updatedAt?: string;
+    /** False for a conversation shared with the user. */
+    isOwn: boolean;
+}
+/** A conversation a message references with `@<key>`. */
+interface ChatConversationRef {
+    conversationId: string;
+    title: string;
+    key: string;
+    /** As the menu offered it: `false` keeps the "Shared with you" hint. Absent reads as the user's own. */
+    isOwn?: boolean;
+}
+/** A workspace the conversation list is grouped by. */
+interface ChatWorkspace {
+    id: string;
+    name: string;
+    /** The caller owns it: a colleague's default shared with them is not theirs. */
+    isOwn: boolean;
+    isDefault: boolean;
+    /** Whether the caller may file conversations into it, rename or delete it. */
+    canManage: boolean;
 }
 interface XtmAgent {
     id: string;
@@ -575,4 +694,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMessagePersistedFeedback, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatMessage, ChatMessagePersistedFeedback, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, ChatWorkspace, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };