@multiplayer-app/ai-agent-react 0.1.0-beta.83 → 0.1.0-beta.85

package/README.md

@@ -83,7 +83,8 @@ If you set `containsPII: true` with `redactionsApplied: []`, you are explicitly
 ### What the React library does
 
 - **UI**: renders attachment chips under messages.
-- **Composer**: includes a built-in “Attach selection” button that captures the current text selection as a `webSnippet` context attachment (when running in the browser).
+- **Composer**: includes built-in attach controls (files, selection, page context) behind `config.features` toggles.
+- **Composer (custom actions)**: optional `config.composerAttachmentActions` slot for host-defined toolbar buttons that add custom attachments.
 - **Composer (page context)**: auto-attaches a `pageContext` chip (URL + metadata) by default. Users can remove it; if removed, the composer shows an “Attach page context” button.
 - **Runtime**: forwards `attachments` in `SendMessagePayload` to your transport (proxy or direct).
 
@@ -262,6 +263,62 @@ const att = createContextAttachment({
 
 This produces a valid `AgentAttachment` with defaults filled in.
 
+#### Custom composer attachment actions (`config.composerAttachmentActions`)
+
+To add toolbar buttons in the composer (next to file/selection attach), pass a React component. It receives the current draft attachments and helpers to add or remove attachments:
+
+```tsx
+import {
+  AgentProvider,
+  AgentChatWindow,
+  createContextAttachment,
+  type ComposerAttachmentActionsProps,
+  type AgentFrontendConfig
+} from '@multiplayer-app/ai-agent-react'
+import { Bookmark } from 'lucide-react'
+
+function RecordAttachmentActions({ addAttachments }: ComposerAttachmentActionsProps) {
+  return (
+    <button
+      type="button"
+      className="mp-agent-composer-button mp-agent-composer-tool-button"
+      aria-label="Attach current record"
+      onClick={() => {
+        addAttachments([
+          createContextAttachment({
+            kind: 'record',
+            title: 'Current record',
+            selectedText: JSON.stringify({ id: 'rec_123' })
+          })
+        ])
+      }}
+    >
+      <Bookmark size={16} />
+    </button>
+  )
+}
+
+const config: AgentFrontendConfig = {
+  appId: 'your-app',
+  contextKeys: [{ key: 'default', label: 'Default', tools: [] }],
+  transport: { mode: 'proxy', baseUrl: '/api' },
+  features: {
+    fileAttachments: true,
+    selectionAttachments: true,
+    pageContextAttachments: true
+  },
+  composerAttachmentActions: RecordAttachmentActions
+}
+
+export const YourAppAgent = () => (
+  <AgentProvider config={config}>
+    <AgentChatWindow />
+  </AgentProvider>
+)
+```
+
+Use `mp-agent-composer-button` and `mp-agent-composer-tool-button` on buttons so they match the built-in composer controls. For attach UI outside the composer toolbar, use `useComposerDraft()` or `AttachContextButton` instead.
+
 #### Example: create a custom context attachment
 
 ```ts
@@ -426,6 +483,8 @@ User selects tool chip / runtime.tools.invoke(...)
 | `features`          | Fine-grained toggles: reasoning panel location, artifact visibility, multi-agent controls, sandbox switches, etc.                                          |
 | `theme`             | Partial overrides for the default theme tokens (background, accent, font, radius, etc.).                                                                   |
 | `toolRenderers`     | Map tool names to React components when tool output needs rich visuals (tables, charts, custom viewers).                                                   |
+| `composerAttachmentActions` | React component in the composer toolbar for host-defined attachment buttons (`addAttachments`, `removeAttachment`, current `attachments`). |
+| `pageContext`       | Options and `getData` hook for the built-in page-context attachment chip.                                                                                  |
 | `user`              | Optional `{ id, displayName, email, avatarUrl }` shape. If provided, user metadata is attached to tool calls/history.                                      |
 
 All configs are validated through `zod` at runtime, so invalid configurations fail fast.