@filigran/chatbot 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -8,7 +8,36 @@ 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.13.0 — unreleased
+## 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
 

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
@@ -601,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
@@ -788,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'`
@@ -795,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**
@@ -821,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'`
@@ -830,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 };