@runtypelabs/persona 1.36.1 → 1.37.0

package/README.md

@@ -137,6 +137,97 @@ const chat = initAgentWidget({
 chat.clearChat()
 ```
 
+#### Message Injection
+
+Inject messages programmatically from external sources like tool call responses, system events, or third-party integrations. This is useful when local tools need to push results back into the conversation.
+
+```ts
+const chat = initAgentWidget({
+  target: '#launcher-root',
+  config: { /* ... */ }
+})
+
+// Simple message injection
+chat.injectAssistantMessage({
+  content: 'Here are your search results...'
+});
+
+// User message injection
+chat.injectUserMessage({
+  content: 'Add to cart'
+});
+
+// System context injection
+chat.injectSystemMessage({
+  content: '[Context updated]',
+  llmContent: 'User is viewing product page for iPhone 15 Pro'
+});
+```
+
+**Dual-Content Messages (llmContent)**
+
+Use `llmContent` to show different content to the user versus what gets sent to the LLM. This is useful for:
+- **Token efficiency**: Show rich content to users while sending concise summaries to the LLM
+- **Sensitive data redaction**: Display PII to users while hiding it from the LLM
+- **Context injection**: Provide detailed LLM context with minimal UI footprint
+
+```ts
+// Example: Tool callback that injects search results
+async function handleProductSearch(query: string) {
+  const results = await searchProducts(query);
+
+  // User sees full product details with images and prices
+  // LLM receives a concise summary to save tokens
+  chat.injectAssistantMessage({
+    content: `**Found ${results.length} products:**
+${results.map(p => `- ${p.name} - $${p.price} (SKU: ${p.sku})`).join('\n')}`,
+
+    llmContent: `[Search results: ${results.length} products found, price range $${results.minPrice}-$${results.maxPrice}]`
+  });
+}
+
+// Example: Redacting sensitive information
+chat.injectAssistantMessage({
+  // User sees their order confirmation with details
+  content: `Your order #12345 has been placed!
+- Card ending in 4242
+- Shipping to: 123 Main St, Anytown, USA`,
+
+  // LLM only knows an order was placed (no PII)
+  llmContent: '[Order confirmation displayed to user]'
+});
+```
+
+**Content Priority**
+
+When messages are sent to the API, content is resolved in this priority order:
+1. `contentParts` - Multi-modal content (images, files)
+2. `llmContent` - Explicit LLM-specific content
+3. `content` - Display content as fallback
+
+**Streaming Updates**
+
+For long-running operations, use the same message ID to update content:
+
+```ts
+const messageId = 'search-123';
+
+// Show loading state
+chat.injectAssistantMessage({
+  id: messageId,
+  content: 'Searching...',
+  streaming: true
+});
+
+// Update with results
+chat.injectAssistantMessage({
+  id: messageId,
+  content: 'Found 5 results...',
+  llmContent: '[5 search results]',
+  streaming: false
+});
+```
+
 #### Accessing from window
 
 To access the controller globally (e.g., from browser console or external scripts), use the `windowKey` option:
@@ -305,17 +396,17 @@ type AgentWidgetMessageActionsConfig = {
 - **Copy button**: Shows a checkmark briefly after successful copy
 - **Vote buttons**: Toggle active state and are mutually exclusive (upvoting clears downvote and vice versa)
 
-### Travrse adapter
+### Runtype adapter
 
-This package ships with a Travrse adapter by default. The proxy handles all flow configuration, keeping the client lightweight and flexible.
+This package ships with a Runtype adapter by default. The proxy handles all flow configuration, keeping the client lightweight and flexible.
 
 **Flow configuration happens server-side** - you have three options:
 
 1. **Use default flow** - The proxy includes a basic streaming chat flow out of the box
-2. **Reference a Travrse flow ID** - Configure flows in your Travrse dashboard and reference them by ID
+2. **Reference a Runtype flow ID** - Configure flows in your Runtype dashboard and reference them by ID
 3. **Define custom flows** - Build flow configurations directly in the proxy
 
-The client simply sends messages to the proxy, which constructs the full Travrse payload. This architecture allows you to:
+The client simply sends messages to the proxy, which constructs the full Runtype payload. This architecture allows you to:
 - Change models/prompts without redeploying the widget
 - A/B test different flows server-side
 - Enforce security and cost controls centrally
@@ -777,8 +868,8 @@ This ensures all configuration values are set to sensible defaults while allowin
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `apiUrl` | `string` | Proxy endpoint for your chat backend (defaults to Travrse's cloud API). |
-| `flowId` | `string` | Optional Travrse flow ID. If provided, the client sends it to the proxy which can use it to select a specific flow. |
+| `apiUrl` | `string` | Proxy endpoint for your chat backend (defaults to Runtype's cloud API). |
+| `flowId` | `string` | Optional Runtype flow ID. If provided, the client sends it to the proxy which can use it to select a specific flow. |
 | `headers` | `Record<string, string>` | Extra headers forwarded to your proxy. |
 | `copy` | `{ welcomeTitle?, welcomeSubtitle?, inputPlaceholder?, sendButtonLabel? }` | Customize user-facing text. |
 | `theme` | `{ primary?, secondary?, surface?, muted?, accent?, radiusSm?, radiusMd?, radiusLg?, radiusFull? }` | Override CSS variables for the widget. Colors: `primary` (text/UI), `secondary` (unused), `surface` (backgrounds), `muted` (secondary text), `accent` (buttons/links). Border radius: `radiusSm` (0.75rem, inputs), `radiusMd` (1rem, cards), `radiusLg` (1.5rem, panels/bubbles), `radiusFull` (9999px, pills/buttons). |
@@ -1000,7 +1091,7 @@ The parser's `processChunk` method is called for each chunk. If the content matc
 
 ### Optional proxy server
 
-The proxy server handles flow configuration and forwards requests to Travrse. You can configure it in three ways:
+The proxy server handles flow configuration and forwards requests to Runtype. You can configure it in three ways:
 
 **Option 1: Use default flow (recommended for getting started)**
 
@@ -1014,7 +1105,7 @@ export default createChatProxyApp({
 });
 ```
 
-**Option 2: Reference a Travrse flow ID**
+**Option 2: Reference a Runtype flow ID**
 
 ```ts
 import { createChatProxyApp } from '@runtypelabs/persona-proxy';
@@ -1022,7 +1113,7 @@ import { createChatProxyApp } from '@runtypelabs/persona-proxy';
 export default createChatProxyApp({
   path: '/api/chat/dispatch',
   allowedOrigins: ['https://www.example.com'],
-  flowId: 'flow_abc123' // Flow created in Travrse dashboard or API
+  flowId: 'flow_abc123' // Flow created in Runtype dashboard or API
 });
 ```
 
@@ -1070,7 +1161,7 @@ export default createVercelHandler({
 
 **Environment setup:**
 
-Add `TRAVRSE_API_KEY` to your environment. The proxy constructs the Travrse payload (including flow configuration) and streams the response back to the client.
+Add `RUNTYPE_API_KEY` to your environment. The proxy constructs the Runtype payload (including flow configuration) and streams the response back to the client.
 
 ### Development notes