@filigran/chatbot 3.9.0 → 3.10.0

package/README.md

@@ -71,7 +71,9 @@ import { ChatPanel } from '@filigran/chatbot';
 | `apiBaseUrl`        | `string`                                  | **required** | Base URL for chat API endpoints                                  |
 | `user`              | `{ firstName: string }`                   | **required** | Current user info                                                |
 | `topOffset`         | `number`                                  | `0`          | Top offset in pixels (for sidebar/fullscreen with fixed headers) |
-| `agentDashboardUrl` | `string`                                  | —            | URL for "Browse agents" / "Create agent" links                   |
+| `agentDashboardUrl` | `string`                                  | —            | XTM One URL for the "Browse agents" / "Create agent" links and the waiting panel's "Play Space Invaders in XTM One" link (`{url}/chat?arcade=play`, http(s) only) |
+| `miniGameEnabled`   | `boolean`                                 | `true`       | Show the waiting panel during longer waits: rotating messages and the invitation to play XTM One's arcade (the package ships no game of its own) |
+| `onPlayWaitingGame` | `() => void`                              | —            | Open the arcade in place instead of linking to XTM One, for a host that runs it itself (the XTM One floating assistant) |
 | `t`                 | `(key: string) => string`                 | identity     | Translation function for i18n                                    |
 | `accentColor`       | `string`                                  | `'#7b5cff'`  | Primary accent color (hex)                                       |
 | `logoIcon`          | `React.ReactNode`                         | default icon | Custom logo/icon for the assistant                               |
@@ -121,13 +123,14 @@ import { ChatToggleButton } from '@filigran/chatbot';
 
 #### Props
 
-| Prop          | Type              | Default      | Description                    |
-| ------------- | ----------------- | ------------ | ------------------------------ |
-| `isOpen`      | `boolean`         | **required** | Whether the chat panel is open |
-| `onToggle`    | `() => void`      | **required** | Called when button is clicked  |
-| `label`       | `string`          | `'Chat'`     | Tooltip/aria label             |
-| `accentColor` | `string`          | `'#7b5cff'`  | Button background color        |
-| `icon`        | `React.ReactNode` | default icon | Custom icon                    |
+| Prop          | Type                      | Default      | Description                                                                |
+| ------------- | ------------------------- | ------------ | -------------------------------------------------------------------------- |
+| `isOpen`      | `boolean`                 | **required** | Whether the chat panel is open                                             |
+| `onToggle`    | `() => void`              | **required** | Called when button is clicked                                              |
+| `label`       | `string`                  | built-in     | Button text, already translated by the host; omit for `t('Ask Assistant')` |
+| `t`           | `(key: string) => string` | identity     | Translation function, used for the default label                           |
+| `accentColor` | `string`                  | `'#7b5cff'`  | Button background color                                                    |
+| `icon`        | `React.ReactNode`         | default icon | Custom icon                                                                |
 
 ## API Contract
 
@@ -571,59 +574,230 @@ function App() {
 }
 ```
 
-**Translation keys used:**
+`t` is only ever asked for a lookup — key in, translated string out — so any
+i18n library works and the package never carries a dictionary of its own.
+Untranslated hosts can omit it: the default is the identity function, so every
+key is its own English text.
 
-- `'Thinking...'`
-- `'Using tools…'`
-- `'Analyzing results…'`
-- `'Composing answer…'`
-- `'Incorporating your message…'`
-- `'Ask a question...'`
-- `'Stop generating'`
-- `'Send now'`
-- `'Enter to send now · Esc to stop'`
-- `'Attachments wait for the current response'`
-- `'New chat'`
+#### Values inside sentences
+
+A key is always a **whole sentence**, with `{placeholder}` slots for the values.
+The panel fills the slots in _after_ the lookup, so a locale is free to move the
+value, and a translator sees the sentence rather than a fragment of one:
+
+| Key | Renders as |
+| --- | --- |
+| `'Waiting for {count} background tasks…'` | Waiting for 3 background tasks… |
+| `'Transferred from {agent}'` | Transferred from Threat Analyst |
+| `'{percent}% full'` | 84% full |
+| `'How can {agent} help you, {name}?'` | How can **Threat Analyst** help you, John? |
+
+Two consequences worth knowing when writing the locale files:
+
+- **Plurals are separate keys** — `'1 tool call'` and `'{count} tool calls'`,
+  `'Delegating one task…'` and `'Delegating {count} tasks…'`. A lookup cannot
+  select a plural form, so the panel picks the sentence and the locale
+  translates it whole; a language with more plural forms than English can route
+  the plural key through its own rules.
+- **A missing slot is not fatal** — a translation that drops a `{placeholder}`
+  renders the rest of the sentence as it is, and the value is simply absent.
+  That includes the greeting, where the agent's name is markup: a locale that
+  rewords the sentence without `{agent}` gets the sentence, not a name dangling
+  off the end of it.
+
+`promptSuggestions` (and any suggestions the backend serves) also go through
+`t`, so a host may pass either keys or final text.
+
+#### Translation keys used
+
+Every key the package can ask for, grouped by where it appears:
+
+**Toggle button**
+
+- `'Ask Assistant'`
+
+**Header, agent menu and history**
+
+- `'Agent switching is not available here'`
+- `'Browse agents'`
+- `'Close'`
 - `'Conversation history'`
-- `'No conversations yet'`
-- `'Untitled conversation'`
-- `'New conversation'`
+- `'Could not reach the assistant service. Check the connection and try again.'`
+- `'Create agent'`
 - `'Delete conversation'`
-- `'just now'` / `'m ago'` / `'h ago'` / `'d ago'`
-- `'Switch view'`
-- `'Close'`
+- `'Floating'`
+- `'Full screen'`
+- `'New chat'`
+- `'New conversation'`
+- `'No agent matches'`
+- `'No conversations yet'`
+- `'Search agents...'`
+- `'Sidebar'`
+- `'Switch to'`
 - `'Switch to another agent'`
-- `'Browse agents'`
-- `'Create agent'`
+- `'Switch view'`
+- `'Transferred from {agent}'`
+- `'Untitled conversation'`
+
+**Conversation sidebar**
+
+- `'Conversation title'`
+- `'Hide conversations'`
+- `'No conversation matches'`
+- `'Rename conversation'`
+- `'Search conversations...'`
+- `'Show conversations'`
+
+**Welcome screen**
+
+- `'Assistant'`
+- `'Help me create a new simulation scenario'`
+- `'How can I help you, {name}?'`
+- `'How can {agent} help you, {name}?'`
+- `'How do I configure detection rules?'`
+- `'Suggestions'`
+- `'Summarize my recent findings'`
+- `'What are the latest attack patterns?'`
+
+**Composer**
+
+- `'Ask a question...'`
+- `'Attachments wait for the current response'`
+- `'Dictate a message'`
+- `'Enter to send now · Esc to stop'`
+- `'Files uploading...'`
+- `'Insert prompt template'`
+- `'No prompt matches'`
+- `'Search prompts...'`
+- `'Send now'`
+- `'Stop dictation'`
+- `'Stop generating'`
+- `'Uses AI. Verify results.'`
+
+**Messages, markdown and files**
+
+- `'Bad response'`
+- `'Copied'`
+- `'Copied!'`
+- `'Copy code'`
+- `'Copy response'`
+- `'Download'`
+- `'Expand image'`
+- `'Good response'`
+- `'Image could not be loaded'`
+- `'Image preview'`
+- `'Load earlier messages'`
+- `'Loading image…'`
 - `'Reasoning details'`
 - `'Reasoning details — turn limit reached'`
+
+**Agent status**
+
+- `'Analyzing results…'`
+- `'Collecting results from one task…'`
+- `'Collecting results from {count} tasks…'`
+- `'Composing answer…'`
+- `'Consulting {agent}…'`
+- `'Delegating one task…'`
+- `'Delegating {count} tasks…'`
+- `'Incorporating your message…'`
+- `'Thinking...'`
+- `'Transferring to {agent}…'`
+- `'Using tools…'`
+- `'Waiting for one background task…'`
+- `'Waiting for your approval…'`
+- `'Waiting for {count} background tasks…'`
+- `'the agent'`
+- `'{tool} (+{count} more)…'`
+
+**Waiting panel**
+
+- `'Almost there'`
+- `'Analyzing the details'`
+- `'Connecting the dots'`
+- `'Consulting the sources'`
+- `'Crunching the data'`
+- `'Play Space Invaders'`
+- `'Play Space Invaders in XTM One'`
+- `'Polishing the answer'`
+- `'Putting it together'`
+- `'Reticulating splines'`
+- `'Thinking it through'`
+- `'Wrapping things up'`
+
+**Reasoning details**
+
+- `'(no output)'`
+- `'1 tool call'`
+- `'1 transfer'`
+- `'Input'`
 - `'Model reasoning'`
-- `'iterations'`
-- `'transfer'` / `'transfers'`
+- `'Output'`
+- `"The agent's iteration budget was exhausted - execution stopped before completing all planned steps. The final response is a best-effort summary of work done so far."`
 - `'Transfer chain'`
 - `'Turn limit reached.'`
-- `"The agent's iteration budget was exhausted - execution stopped before completing all planned steps. The final response is a best-effort summary of work done so far."`
-- `'Input'` / `'Output'` / `'(no output)'`
-- `'Download'`
-- `'tool call'` / `'tool calls'`
-- `'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'`
+- `'{count} iterations'`
+- `'{count} tool calls'`
+- `'{count} transfers'`
+
+**Tool approval**
+
+- `'Also applies to your scheduled runs, until you revoke it'`
+- `'Always allowed'`
+- `'Approved'`
+- `'Back'`
+- `'Confirm'`
 - `'Decline this call'`
+- `'Declined'`
+- `'No'`
+- `'Sending…'`
+- `'The agent needs your approval to run a tool:'`
+- `'The agent needs your approval to run these tools:'`
 - `'Why not? The agent sees this and can adapt (optional)'`
+- `'Yes'`
+- `'Yes, always'`
 - `'e.g. wrong environment — use staging instead'`
-- `'Also applies to your scheduled runs, until you revoke it'`
+- `'unknown tool'`
+- `'{decided}/{total} decided'`
 - `'“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.'`
+
+**Context gauge**
+
+- `'Context full — older turns are being dropped'`
+- `'Context nearly full — older turns are being summarized'`
+- `'Context used'`
+- `'Conversation'`
+- `'MCP & dynamic tools'`
+- `'Summarized conversation'`
+- `'System prompt'`
+- `'Tool definitions'`
+- `'Tool results'`
+- `'{counts} tokens'`
+- `'{percent}% full'`
+- `'{summary} — click for details'`
+
+**Quota**
+
+- `'Quota'`
+- `'Quota reached'`
+- `'Usage'`
+- `'Usage · {period}'`
+
+**Notices, errors and timestamps**
+
 - `'Could not send your decision. Please try again.'`
+- `'No response.'`
+- `'Response ready'`
+- `'Sorry, an error occurred. Please try again.'`
 - `'This decision could not be sent. Reload the chat and try again.'`
-- `'Floating'`
-- `'Sidebar'`
-- `'Full screen'`
+- `'This turn is no longer waiting for a decision.'`
+- `'Unable to connect. Please check the configuration.'`
+- `'Your answer is ready'`
+- `'just now'`
+- `'{agent} has finished'`
+- `'{count}d ago'`
+- `'{count}h ago'`
+- `'{count}m ago'`
 
 ## Styling
 

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 import { FunctionComponent } from 'react';
 
 type ChatMode = 'sidebar' | 'floating' | 'fullscreen';
+/**
+ * The host's translation lookup, passed down to every component that renders
+ * text. Key in, translated string out — the package never owns a dictionary of
+ * its own, and never asks the host's `t` for more than a lookup: values are
+ * spliced into the *translated* sentence by `translate()` in `utils`, so a key
+ * is always a whole sentence and a locale stays free to reorder it.
+ */
+type Translate = (key: string) => string;
 type BackendType = 'legacy' | 'rest' | 'ag-ui';
 /** A user's rating of one assistant answer. */
 type MessageFeedback = 'up' | 'down';
@@ -156,6 +164,7 @@ interface ToolApprovalProposal {
      * different arguments.
      */
     toolCallId: string;
+    /** Empty when the backend named no tool; the UI labels that case itself. */
     toolName: string;
     toolDescription?: string;
     arguments: Record<string, unknown>;
@@ -236,11 +245,16 @@ interface ChatPanelProps {
     apiBaseUrl: string;
     /** Custom API endpoint configuration. */
     apiEndpoints?: ApiEndpoints;
+    /**
+     * The XTM One URL: the header's "Browse agents" / "Create agent" links, and
+     * the waiting panel's invitation to play the arcade there
+     * (`{agentDashboardUrl}/chat?arcade=play`). Only an http(s) URL is linked.
+     */
     agentDashboardUrl?: string;
     user: {
         firstName: string;
     };
-    t?: (key: string) => string;
+    t?: Translate;
     accentColor?: string;
     logoIcon?: React.ReactNode;
     promptSuggestions?: string[];
@@ -305,12 +319,17 @@ interface ChatPanelProps {
      */
     backendType?: BackendType;
     /**
-     * Show the waiting experience during longer waits: dynamic rotating status
-     * messages plus an optional Space Invader mini-game that shoots the message
-     * letters away one by one. Users can still toggle the game off per browser
-     * from the panel; this prop is a host-level master switch. Default: true.
+     * Show the waiting panel during longer waits: rotating status messages and
+     * an invitation to play XTM One's Space Invaders arcade, in a new tab
+     * through `agentDashboardUrl` or in place through `onPlayWaitingGame`. The
+     * package ships no game of its own. Host-level master switch. Default: true.
      */
     miniGameEnabled?: boolean;
+    /**
+     * Opens the arcade in place instead of linking to XTM One, for a host that
+     * runs it itself (the XTM One floating assistant). Wins over the link.
+     */
+    onPlayWaitingGame?: () => void;
     /**
      * 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
@@ -365,7 +384,9 @@ interface ChatPanelProps {
 interface ChatToggleButtonProps {
     isOpen: boolean;
     onToggle: () => void;
+    /** Overrides the built-in label; already translated by the host. */
     label?: string;
+    t?: Translate;
     accentColor?: string;
     icon?: React.ReactNode;
 }
@@ -495,4 +516,4 @@ interface TransferredAgent {
 }
 
 export { ChatPanel, ChatToggleButton };
-export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, XtmAgent };
+export type { ApiEndpoints, BackendType, ChatAttachment, ChatContextBreakdown, ChatContextUsage, ChatConversationSummary, ChatFile, ChatMessage, ChatMode, ChatPanelProps, ChatPromptTemplate, ChatQuotaStatus, ChatToggleButtonProps, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };