@langchain/macaw-components 1.7.19 → 1.7.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/catalog.json +798 -775
  2. package/dist/components/ChatThread/ChatThread.d.ts +59 -0
  3. package/dist/components/ChatThread/ChatThread.js +338 -0
  4. package/dist/components/ChatThread/ChatThread.js.map +1 -0
  5. package/dist/components/ChatThread/ChatThread.types.d.ts +284 -0
  6. package/dist/components/ChatThread/ChatThread.types.js +0 -0
  7. package/dist/components/ChatThread/ChatThreadContext.d.ts +34 -0
  8. package/dist/components/ChatThread/ChatThreadContext.js +53 -0
  9. package/dist/components/ChatThread/ChatThreadContext.js.map +1 -0
  10. package/dist/components/ChatThread/ChatThreadRequests.d.ts +1 -0
  11. package/dist/components/ChatThread/ChatThreadRequests.js +233 -0
  12. package/dist/components/ChatThread/ChatThreadRequests.js.map +1 -0
  13. package/dist/components/ChatThread/ChatThreadWork.d.ts +13 -0
  14. package/dist/components/ChatThread/ChatThreadWork.js +174 -0
  15. package/dist/components/ChatThread/ChatThreadWork.js.map +1 -0
  16. package/dist/components/ChatThread/deepAgentTools.d.ts +9 -0
  17. package/dist/components/ChatThread/deepAgentTools.js +215 -0
  18. package/dist/components/ChatThread/deepAgentTools.js.map +1 -0
  19. package/dist/components/ChatThread/index.d.ts +8 -0
  20. package/dist/components/ChatThread/index.js +6 -0
  21. package/dist/components/ChatThread/interrupts.d.ts +43 -0
  22. package/dist/components/ChatThread/interrupts.js +96 -0
  23. package/dist/components/ChatThread/interrupts.js.map +1 -0
  24. package/dist/components/ChatThread/messages.d.ts +29 -0
  25. package/dist/components/ChatThread/messages.js +137 -0
  26. package/dist/components/ChatThread/messages.js.map +1 -0
  27. package/dist/components/ChatThread/toChatThread.d.ts +12 -0
  28. package/dist/components/ChatThread/toChatThread.js +275 -0
  29. package/dist/components/ChatThread/toChatThread.js.map +1 -0
  30. package/dist/components/ChatThread/useLangGraphChatThread.d.ts +36 -0
  31. package/dist/components/ChatThread/useLangGraphChatThread.js +240 -0
  32. package/dist/components/ChatThread/useLangGraphChatThread.js.map +1 -0
  33. package/dist/components/ChatToolCall/ChatToolCallDetails.js +1 -1
  34. package/dist/components/MarkdownDisplay/MarkdownDisplay.js +1 -1
  35. package/dist/docs/phosphor-icon-catalog.js +2 -2
  36. package/dist/icons/LongTailPhosphorIcons.js +1 -1
  37. package/dist/utilities.css +1 -1
  38. package/docs/CHAT.md +109 -3
  39. package/docs/DESIGN.md +4 -1
  40. package/package.json +6 -2
package/docs/CHAT.md CHANGED
@@ -1,9 +1,11 @@
1
1
  # Chat components
2
2
 
3
3
  Macaw chat families provide presentation and local interaction. Applications
4
- own message and event parsing, network requests, streaming, persistence,
5
- authorization, analytics, tool execution, and product-specific tool or logo
6
- mapping.
4
+ own network requests, authentication, persistence, analytics, tool execution,
5
+ and product-specific tool or logo mapping. `ChatThread` composes these parts
6
+ into an agent conversation view. By default it adapts a LangGraph `useStream`
7
+ handle so apps don't each rebuild that mapping, and it also takes your own
8
+ adapter's output; either way the app still owns the stream.
7
9
 
8
10
  ## Conversation scrolling
9
11
 
@@ -123,3 +125,107 @@ it, such as a human-in-the-loop `edit` decision. `edit.content` replaces the
123
125
  body with host-owned fields; `edit.onSubmit` saves them. `ChatMessageActions`
124
126
  shows `cancel` on queued messages, and `ChatComposer` takes
125
127
  `action="stopping"` while a stop is pending.
128
+
129
+ ## Agent threads
130
+
131
+ Import from `@langchain/macaw-components/ChatThread`. A thread is one
132
+ conversation and its state, such as a LangGraph thread: messages,
133
+ checkpoints, interrupts, todos, and queued runs. `ChatThread` is a view, not
134
+ an app: the app chooses which thread to show and keeps the client, auth,
135
+ thread list, and routing. It renders from a `ChatThreadController` (the
136
+ turns, interrupts, queue, plan, and actions) and takes it one of two ways:
137
+
138
+ - **`stream` (default).** Pass a LangGraph `useStream` handle and `ChatThread`
139
+ adapts it with the built-in `useLangGraphChatThread` hook.
140
+ - **`thread` (bring your own adapter).** `useLangGraphChatThread` is
141
+ optional. For your own stream logic, another agent framework, or recorded
142
+ data, build a `ChatThreadController` yourself and pass it as `thread`,
143
+ without committing a one-off case to Macaw. Only `model` and `actions.send` are
144
+ required: leave out `stop`, `cancelQueued`, or `fork` and Stop, cancelling
145
+ queued messages, or edit and retry are hidden. The built-in request cards
146
+ answer through `resume`. Optional hooks add edit/retry fork points
147
+ (`useForkPoint`) and subagent details (`useSubagentTranscript`,
148
+ `useSubagentStep`).
149
+
150
+ Pick one for the life of the component. The pieces of the default adapter
151
+ are public too: call `useLangGraphChatThread(stream, options)` yourself to
152
+ read its state or wrap its actions and pass the result as `thread`, or use
153
+ `toChatThread(snapshot)`, the pure mapping, to build part of your own model.
154
+
155
+ ### The default LangGraph adapter
156
+
157
+ Macaw never imports the LangGraph SDK: it reads the `useStream` handle the app
158
+ passes in, so it works with `@langchain/react` 1.x and 2.0 under any package
159
+ alias, and with the 0.3.x hook.
160
+
161
+ The mapping merges each tool call's status from its result message, the live
162
+ tool stream, pending interrupts, and the run; groups messages into turns;
163
+ matches deep agent `task` calls to subagent handles; anchors human-in-the-loop
164
+ requests, in either casing, to the calls they gate; and reads deep agent todos
165
+ and files. Pass selector hooks from your own `@langchain/react` import to turn
166
+ on queued messages, edit and retry, and subagent details. Keep that object at
167
+ module level so it never changes between renders. If your graph uses a message
168
+ state key other than `messages`, pass the same `messagesKey` to `useStream` and
169
+ `ChatThread` (or `useLangGraphChatThread`) so sends, edit/retry, and queue
170
+ previews use that key. The adapter still reads the transcript from
171
+ `stream.messages`.
172
+
173
+ ```tsx
174
+ import {
175
+ useMessageMetadata,
176
+ useMessages,
177
+ useStream,
178
+ useSubmissionQueue,
179
+ useToolCalls,
180
+ } from '@langchain/react';
181
+ import { ChatThread } from '@langchain/macaw-components/ChatThread';
182
+
183
+ const selectors = {
184
+ useMessageMetadata,
185
+ useMessages,
186
+ useSubmissionQueue,
187
+ useToolCalls,
188
+ };
189
+
190
+ export function AgentChat() {
191
+ const stream = useStream({ assistantId: 'agent', apiUrl: '/api/agent' });
192
+ return <ChatThread stream={stream} selectors={selectors} />;
193
+ }
194
+ ```
195
+
196
+ ### Your own adapter
197
+
198
+ ```tsx
199
+ import {
200
+ ChatThread,
201
+ type ChatThreadController,
202
+ } from '@langchain/macaw-components/ChatThread';
203
+
204
+ function useMyAgentThread(): ChatThreadController {
205
+ const { events, isRunning, sendMessage, cancel } = useMyAgent();
206
+ const model = useMemo(() => toModel(events, isRunning), [events, isRunning]);
207
+ return { model, actions: { send: sendMessage, stop: cancel } };
208
+ }
209
+
210
+ export function AgentChat() {
211
+ return <ChatThread thread={useMyAgentThread()} />;
212
+ }
213
+ ```
214
+
215
+ ### Presentation
216
+
217
+ Tool rows use `deepAgentTools` for the built-in deep agent tools. Pass `tools`
218
+ to present others by name: return row props, your own element, or `null` to
219
+ hide a call. A renderer's second argument holds the original AI message and
220
+ tool result, for fields Macaw doesn't map, such as artifacts or
221
+ provider-specific content; every part in `toChatThread` carries the same
222
+ `source`. `renderInterrupt` takes over requests the app understands, such
223
+ as sign-in; return undefined for the default approval, reply, or response
224
+ card. Requests paused together resume together once each has a decision, and
225
+ sending is paused until they do.
226
+
227
+ `ChatThread` pins the message the reader sends (`pinnedMessageId` on
228
+ `ChatConversation`) so the reply streams in below it. The app owns the
229
+ composer's controls: pass `modelSelector` (such as `ChatComposerModelSelect`),
230
+ `composerTools` (such as `ChatComposerAttachmentMenu`), and `composerActions`
231
+ (such as `ChatContextWindowPopover`, shown before Send/Stop).
package/docs/DESIGN.md CHANGED
@@ -75,7 +75,10 @@ Import the tool-call presentation family from
75
75
  `@langchain/macaw-components/ChatToolCall`, shared lifecycle presentation
76
76
  from `@langchain/macaw-components/ChatState`, and agent task lists from
77
77
  `@langchain/macaw-components/ChatPlan`. They are intentionally omitted from the
78
- root barrel. See [CHAT.md](./CHAT.md) for the host/component boundary.
78
+ root barrel. `@langchain/macaw-components/ChatThread` composes them into an
79
+ agent conversation view that adapts a LangGraph `useStream` handle by default
80
+ or takes your own adapter's output. See [CHAT.md](./CHAT.md) for the
81
+ host/component boundary.
79
82
 
80
83
  ## Breadcrumbs
81
84
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@langchain/macaw-components",
3
- "version": "1.7.19",
3
+ "version": "1.7.20",
4
4
  "description": "React components and usage guidance for the Macaw Design System.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -112,6 +112,10 @@
112
112
  "types": "./dist/components/ChatState/index.d.ts",
113
113
  "import": "./dist/components/ChatState/index.js"
114
114
  },
115
+ "./ChatThread": {
116
+ "types": "./dist/components/ChatThread/index.d.ts",
117
+ "import": "./dist/components/ChatThread/index.js"
118
+ },
115
119
  "./ChatToolCall": {
116
120
  "types": "./dist/components/ChatToolCall/index.d.ts",
117
121
  "import": "./dist/components/ChatToolCall/index.js"
@@ -665,7 +669,7 @@
665
669
  "@fontsource/fira-code": "^5.2.7",
666
670
  "@fontsource/inter": "^5.2.8",
667
671
  "@headlessui/react": "^2.2.10",
668
- "@langchain/macaw-tokens": "1.7.19",
672
+ "@langchain/macaw-tokens": "1.7.20",
669
673
  "@lezer/common": "^1.2.1",
670
674
  "@lezer/highlight": "^1.2.0",
671
675
  "@lezer/yaml": "^1.0.4",