assistant-stream 0.3.14 → 0.3.16

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 (238) hide show
  1. package/README.md +6 -4
  2. package/dist/core/AssistantStream.d.ts +50 -9
  3. package/dist/core/AssistantStream.d.ts.map +1 -1
  4. package/dist/core/AssistantStream.js +39 -15
  5. package/dist/core/AssistantStream.js.map +1 -1
  6. package/dist/core/AssistantStreamChunk.d.ts +84 -61
  7. package/dist/core/AssistantStreamChunk.d.ts.map +1 -1
  8. package/dist/core/AssistantStreamChunk.js +0 -2
  9. package/dist/core/accumulators/AssistantMessageStream.d.ts +15 -11
  10. package/dist/core/accumulators/AssistantMessageStream.d.ts.map +1 -1
  11. package/dist/core/accumulators/AssistantMessageStream.js +52 -48
  12. package/dist/core/accumulators/AssistantMessageStream.js.map +1 -1
  13. package/dist/core/accumulators/TimingTracker.d.ts +15 -11
  14. package/dist/core/accumulators/TimingTracker.d.ts.map +1 -1
  15. package/dist/core/accumulators/TimingTracker.js +36 -43
  16. package/dist/core/accumulators/TimingTracker.js.map +1 -1
  17. package/dist/core/accumulators/assistant-message-accumulator.d.ts +21 -11
  18. package/dist/core/accumulators/assistant-message-accumulator.d.ts.map +1 -1
  19. package/dist/core/accumulators/assistant-message-accumulator.js +349 -390
  20. package/dist/core/accumulators/assistant-message-accumulator.js.map +1 -1
  21. package/dist/core/converters/toGenericMessages.d.ts +49 -47
  22. package/dist/core/converters/toGenericMessages.d.ts.map +1 -1
  23. package/dist/core/converters/toGenericMessages.js +122 -136
  24. package/dist/core/converters/toGenericMessages.js.map +1 -1
  25. package/dist/core/modules/assistant-stream.d.ts +92 -28
  26. package/dist/core/modules/assistant-stream.d.ts.map +1 -1
  27. package/dist/core/modules/assistant-stream.js +177 -162
  28. package/dist/core/modules/assistant-stream.js.map +1 -1
  29. package/dist/core/modules/text.d.ts +11 -7
  30. package/dist/core/modules/text.d.ts.map +1 -1
  31. package/dist/core/modules/text.js +45 -45
  32. package/dist/core/modules/text.js.map +1 -1
  33. package/dist/core/modules/tool-call.d.ts +15 -11
  34. package/dist/core/modules/tool-call.d.ts.map +1 -1
  35. package/dist/core/modules/tool-call.js +81 -96
  36. package/dist/core/modules/tool-call.js.map +1 -1
  37. package/dist/core/object/ObjectStreamAccumulator.d.ts +13 -9
  38. package/dist/core/object/ObjectStreamAccumulator.d.ts.map +1 -1
  39. package/dist/core/object/ObjectStreamAccumulator.js +44 -52
  40. package/dist/core/object/ObjectStreamAccumulator.js.map +1 -1
  41. package/dist/core/object/ObjectStreamResponse.d.ts +12 -8
  42. package/dist/core/object/ObjectStreamResponse.d.ts.map +1 -1
  43. package/dist/core/object/ObjectStreamResponse.js +52 -71
  44. package/dist/core/object/ObjectStreamResponse.js.map +1 -1
  45. package/dist/core/object/createObjectStream.d.ts +14 -8
  46. package/dist/core/object/createObjectStream.d.ts.map +1 -1
  47. package/dist/core/object/createObjectStream.js +50 -47
  48. package/dist/core/object/createObjectStream.js.map +1 -1
  49. package/dist/core/object/types.d.ts +14 -11
  50. package/dist/core/object/types.d.ts.map +1 -1
  51. package/dist/core/object/types.js +0 -2
  52. package/dist/core/serialization/PlainText.d.ts +11 -7
  53. package/dist/core/serialization/PlainText.d.ts.map +1 -1
  54. package/dist/core/serialization/PlainText.js +40 -48
  55. package/dist/core/serialization/PlainText.js.map +1 -1
  56. package/dist/core/serialization/assistant-transport/AssistantTransport.d.ts +11 -7
  57. package/dist/core/serialization/assistant-transport/AssistantTransport.d.ts.map +1 -1
  58. package/dist/core/serialization/assistant-transport/AssistantTransport.js +102 -117
  59. package/dist/core/serialization/assistant-transport/AssistantTransport.js.map +1 -1
  60. package/dist/core/serialization/data-stream/DataStream.d.ts +11 -7
  61. package/dist/core/serialization/data-stream/DataStream.d.ts.map +1 -1
  62. package/dist/core/serialization/data-stream/DataStream.js +320 -371
  63. package/dist/core/serialization/data-stream/DataStream.js.map +1 -1
  64. package/dist/core/serialization/data-stream/chunk-types.d.ts +101 -100
  65. package/dist/core/serialization/data-stream/chunk-types.d.ts.map +1 -1
  66. package/dist/core/serialization/data-stream/chunk-types.js +27 -23
  67. package/dist/core/serialization/data-stream/chunk-types.js.map +1 -1
  68. package/dist/core/serialization/data-stream/serialization.d.ts +9 -5
  69. package/dist/core/serialization/data-stream/serialization.d.ts.map +1 -1
  70. package/dist/core/serialization/data-stream/serialization.js +23 -24
  71. package/dist/core/serialization/data-stream/serialization.js.map +1 -1
  72. package/dist/core/serialization/ui-message-stream/UIMessageStream.d.ts +15 -12
  73. package/dist/core/serialization/ui-message-stream/UIMessageStream.d.ts.map +1 -1
  74. package/dist/core/serialization/ui-message-stream/UIMessageStream.js +205 -228
  75. package/dist/core/serialization/ui-message-stream/UIMessageStream.js.map +1 -1
  76. package/dist/core/serialization/ui-message-stream/chunk-types.d.ts +68 -65
  77. package/dist/core/serialization/ui-message-stream/chunk-types.d.ts.map +1 -1
  78. package/dist/core/serialization/ui-message-stream/chunk-types.js +0 -2
  79. package/dist/core/tool/ToolCallReader.d.ts +34 -30
  80. package/dist/core/tool/ToolCallReader.d.ts.map +1 -1
  81. package/dist/core/tool/ToolCallReader.js +264 -317
  82. package/dist/core/tool/ToolCallReader.js.map +1 -1
  83. package/dist/core/tool/ToolExecutionStream.d.ts +20 -17
  84. package/dist/core/tool/ToolExecutionStream.d.ts.map +1 -1
  85. package/dist/core/tool/ToolExecutionStream.js +123 -146
  86. package/dist/core/tool/ToolExecutionStream.js.map +1 -1
  87. package/dist/core/tool/ToolResponse.d.ts +60 -19
  88. package/dist/core/tool/ToolResponse.d.ts.map +1 -1
  89. package/dist/core/tool/ToolResponse.js +51 -34
  90. package/dist/core/tool/ToolResponse.js.map +1 -1
  91. package/dist/core/tool/schema-utils.d.ts +19 -15
  92. package/dist/core/tool/schema-utils.d.ts.map +1 -1
  93. package/dist/core/tool/schema-utils.js +50 -84
  94. package/dist/core/tool/schema-utils.js.map +1 -1
  95. package/dist/core/tool/tool-types.d.ts +173 -92
  96. package/dist/core/tool/tool-types.d.ts.map +1 -1
  97. package/dist/core/tool/tool-types.js +0 -2
  98. package/dist/core/tool/toolResultStream.d.ts +24 -7
  99. package/dist/core/tool/toolResultStream.d.ts.map +1 -1
  100. package/dist/core/tool/toolResultStream.js +128 -145
  101. package/dist/core/tool/toolResultStream.js.map +1 -1
  102. package/dist/core/tool/type-path-utils.d.ts +8 -19
  103. package/dist/core/tool/type-path-utils.d.ts.map +1 -1
  104. package/dist/core/tool/type-path-utils.js +0 -2
  105. package/dist/core/utils/Counter.d.ts +6 -3
  106. package/dist/core/utils/Counter.d.ts.map +1 -1
  107. package/dist/core/utils/Counter.js +10 -6
  108. package/dist/core/utils/Counter.js.map +1 -1
  109. package/dist/core/utils/generateId.d.ts +4 -1
  110. package/dist/core/utils/generateId.d.ts.map +1 -1
  111. package/dist/core/utils/generateId.js +5 -1
  112. package/dist/core/utils/generateId.js.map +1 -1
  113. package/dist/core/utils/stream/AssistantMetaTransformStream.d.ts +15 -11
  114. package/dist/core/utils/stream/AssistantMetaTransformStream.d.ts.map +1 -1
  115. package/dist/core/utils/stream/AssistantMetaTransformStream.js +38 -42
  116. package/dist/core/utils/stream/AssistantMetaTransformStream.js.map +1 -1
  117. package/dist/core/utils/stream/AssistantTransformStream.d.ts +11 -8
  118. package/dist/core/utils/stream/AssistantTransformStream.d.ts.map +1 -1
  119. package/dist/core/utils/stream/AssistantTransformStream.js +37 -35
  120. package/dist/core/utils/stream/AssistantTransformStream.js.map +1 -1
  121. package/dist/core/utils/stream/LineDecoderStream.d.ts +6 -3
  122. package/dist/core/utils/stream/LineDecoderStream.d.ts.map +1 -1
  123. package/dist/core/utils/stream/LineDecoderStream.js +23 -26
  124. package/dist/core/utils/stream/LineDecoderStream.js.map +1 -1
  125. package/dist/core/utils/stream/PipeableTransformStream.d.ts +5 -2
  126. package/dist/core/utils/stream/PipeableTransformStream.d.ts.map +1 -1
  127. package/dist/core/utils/stream/PipeableTransformStream.js +14 -10
  128. package/dist/core/utils/stream/PipeableTransformStream.js.map +1 -1
  129. package/dist/core/utils/stream/SSE.d.ts +10 -6
  130. package/dist/core/utils/stream/SSE.d.ts.map +1 -1
  131. package/dist/core/utils/stream/SSE.js +79 -91
  132. package/dist/core/utils/stream/SSE.js.map +1 -1
  133. package/dist/core/utils/stream/UnderlyingReadable.d.ts +7 -4
  134. package/dist/core/utils/stream/UnderlyingReadable.d.ts.map +1 -1
  135. package/dist/core/utils/stream/UnderlyingReadable.js +0 -2
  136. package/dist/core/utils/stream/merge.d.ts +11 -7
  137. package/dist/core/utils/stream/merge.d.ts.map +1 -1
  138. package/dist/core/utils/stream/merge.js +68 -170
  139. package/dist/core/utils/stream/merge.js.map +1 -1
  140. package/dist/core/utils/stream/path-utils.d.ts +11 -7
  141. package/dist/core/utils/stream/path-utils.d.ts.map +1 -1
  142. package/dist/core/utils/stream/path-utils.js +46 -52
  143. package/dist/core/utils/stream/path-utils.js.map +1 -1
  144. package/dist/core/utils/types.d.ts +109 -113
  145. package/dist/core/utils/types.d.ts.map +1 -1
  146. package/dist/core/utils/types.js +0 -2
  147. package/dist/core/utils/withPromiseOrValue.d.ts +4 -1
  148. package/dist/core/utils/withPromiseOrValue.d.ts.map +1 -1
  149. package/dist/core/utils/withPromiseOrValue.js +12 -15
  150. package/dist/core/utils/withPromiseOrValue.js.map +1 -1
  151. package/dist/index.d.ts +23 -24
  152. package/dist/index.js +16 -16
  153. package/dist/node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts +141 -0
  154. package/dist/node_modules/.pnpm/@types_json-schema@7.0.15/node_modules/@types/json-schema/index.d.ts.map +1 -0
  155. package/dist/resumable/ResumableStreamContext.d.ts +28 -24
  156. package/dist/resumable/ResumableStreamContext.d.ts.map +1 -1
  157. package/dist/resumable/ResumableStreamContext.js +99 -114
  158. package/dist/resumable/ResumableStreamContext.js.map +1 -1
  159. package/dist/resumable/constants.d.ts +4 -1
  160. package/dist/resumable/constants.d.ts.map +1 -1
  161. package/dist/resumable/constants.js +5 -1
  162. package/dist/resumable/constants.js.map +1 -1
  163. package/dist/resumable/createResumableAssistantStreamResponse.d.ts +22 -21
  164. package/dist/resumable/createResumableAssistantStreamResponse.d.ts.map +1 -1
  165. package/dist/resumable/createResumableAssistantStreamResponse.js +25 -32
  166. package/dist/resumable/createResumableAssistantStreamResponse.js.map +1 -1
  167. package/dist/resumable/errors.d.ts +8 -5
  168. package/dist/resumable/errors.d.ts.map +1 -1
  169. package/dist/resumable/errors.js +14 -12
  170. package/dist/resumable/errors.js.map +1 -1
  171. package/dist/resumable/index.d.ts +7 -7
  172. package/dist/resumable/index.js +5 -5
  173. package/dist/resumable/stores/InMemoryResumableStreamStore.d.ts +14 -10
  174. package/dist/resumable/stores/InMemoryResumableStreamStore.d.ts.map +1 -1
  175. package/dist/resumable/stores/InMemoryResumableStreamStore.js +159 -193
  176. package/dist/resumable/stores/InMemoryResumableStreamStore.js.map +1 -1
  177. package/dist/resumable/stores/ioredis.d.ts +9 -5
  178. package/dist/resumable/stores/ioredis.d.ts.map +1 -1
  179. package/dist/resumable/stores/ioredis.js +70 -82
  180. package/dist/resumable/stores/ioredis.js.map +1 -1
  181. package/dist/resumable/stores/redis-impl.d.ts +51 -48
  182. package/dist/resumable/stores/redis-impl.d.ts.map +1 -1
  183. package/dist/resumable/stores/redis-impl.js +176 -176
  184. package/dist/resumable/stores/redis-impl.js.map +1 -1
  185. package/dist/resumable/stores/redis.d.ts +31 -28
  186. package/dist/resumable/stores/redis.d.ts.map +1 -1
  187. package/dist/resumable/stores/redis.js +87 -95
  188. package/dist/resumable/stores/redis.js.map +1 -1
  189. package/dist/resumable/types.d.ts +29 -26
  190. package/dist/resumable/types.d.ts.map +1 -1
  191. package/dist/resumable/types.js +0 -2
  192. package/dist/utils/AsyncIterableStream.d.ts +5 -2
  193. package/dist/utils/AsyncIterableStream.d.ts.map +1 -1
  194. package/dist/utils/AsyncIterableStream.js +17 -16
  195. package/dist/utils/AsyncIterableStream.js.map +1 -1
  196. package/dist/utils/json/fix-json.d.ts +4 -1
  197. package/dist/utils/json/fix-json.d.ts.map +1 -1
  198. package/dist/utils/json/fix-json.js +286 -380
  199. package/dist/utils/json/fix-json.js.map +1 -1
  200. package/dist/utils/json/is-json.d.ts +8 -4
  201. package/dist/utils/json/is-json.d.ts.map +1 -1
  202. package/dist/utils/json/is-json.js +13 -21
  203. package/dist/utils/json/is-json.js.map +1 -1
  204. package/dist/utils/json/json-value.d.ts +7 -4
  205. package/dist/utils/json/json-value.d.ts.map +1 -1
  206. package/dist/utils/json/json-value.js +0 -2
  207. package/dist/utils/json/parse-partial-json-object.d.ts +11 -8
  208. package/dist/utils/json/parse-partial-json-object.d.ts.map +1 -1
  209. package/dist/utils/json/parse-partial-json-object.js +50 -62
  210. package/dist/utils/json/parse-partial-json-object.js.map +1 -1
  211. package/dist/utils/promiseWithResolvers.d.ts +7 -4
  212. package/dist/utils/promiseWithResolvers.d.ts.map +1 -1
  213. package/dist/utils/promiseWithResolvers.js +17 -10
  214. package/dist/utils/promiseWithResolvers.js.map +1 -1
  215. package/dist/utils.d.ts +6 -6
  216. package/dist/utils.js +5 -5
  217. package/package.json +5 -4
  218. package/src/core/AssistantStream.ts +37 -0
  219. package/src/core/AssistantStreamChunk.ts +30 -0
  220. package/src/core/modules/assistant-stream.ts +68 -0
  221. package/src/core/tool/ToolResponse.ts +45 -1
  222. package/src/core/tool/tool-types.ts +102 -2
  223. package/src/core/tool/toolResultStream.ts +15 -0
  224. package/dist/core/AssistantStreamChunk.js.map +0 -1
  225. package/dist/core/object/types.js.map +0 -1
  226. package/dist/core/serialization/ui-message-stream/chunk-types.js.map +0 -1
  227. package/dist/core/tool/tool-types.js.map +0 -1
  228. package/dist/core/tool/type-path-utils.js.map +0 -1
  229. package/dist/core/utils/stream/UnderlyingReadable.js.map +0 -1
  230. package/dist/core/utils/types.js.map +0 -1
  231. package/dist/index.d.ts.map +0 -1
  232. package/dist/index.js.map +0 -1
  233. package/dist/resumable/index.d.ts.map +0 -1
  234. package/dist/resumable/index.js.map +0 -1
  235. package/dist/resumable/types.js.map +0 -1
  236. package/dist/utils/json/json-value.js.map +0 -1
  237. package/dist/utils.d.ts.map +0 -1
  238. package/dist/utils.js.map +0 -1
@@ -2,6 +2,12 @@ import type { ReadonlyJSONValue } from "../utils/json/json-value";
2
2
  import type { ObjectStreamOperation } from "./object/types";
3
3
  import type { ToolModelContentPart } from "./tool/tool-types";
4
4
 
5
+ /**
6
+ * Initial metadata for a stream part.
7
+ *
8
+ * A part starts with `part-start`, receives zero or more chunks at the same
9
+ * path, and ends with `part-finish`.
10
+ */
5
11
  export type PartInit =
6
12
  | {
7
13
  readonly type: "text" | "reasoning";
@@ -34,34 +40,49 @@ export type PartInit =
34
40
  readonly parentId?: string;
35
41
  };
36
42
 
43
+ /**
44
+ * Normalized assistant-ui streaming protocol chunk.
45
+ *
46
+ * `path` identifies the part or nested position the chunk belongs to. Encoders
47
+ * may translate these chunks into provider-specific wire formats, while
48
+ * accumulators consume them to build assistant messages.
49
+ */
37
50
  export type AssistantStreamChunk = { readonly path: readonly number[] } & (
38
51
  | {
52
+ /** Opens a new content part at `path`. */
39
53
  readonly type: "part-start";
40
54
  readonly part: PartInit;
41
55
  }
42
56
  | {
57
+ /** Closes the current part at `path`. */
43
58
  readonly type: "part-finish";
44
59
  }
45
60
  | {
61
+ /** Marks streamed tool-call argument text as complete. */
46
62
  readonly type: "tool-call-args-text-finish";
47
63
  }
48
64
  | {
65
+ /** Appends text to a text, reasoning, or tool-call argument part. */
49
66
  readonly type: "text-delta";
50
67
  readonly textDelta: string;
51
68
  }
52
69
  | {
70
+ /** Appends provider or application annotations to the current message. */
53
71
  readonly type: "annotations";
54
72
  readonly annotations: ReadonlyJSONValue[];
55
73
  }
56
74
  | {
75
+ /** Emits application data chunks associated with the current message. */
57
76
  readonly type: "data";
58
77
  readonly data: ReadonlyJSONValue[];
59
78
  }
60
79
  | {
80
+ /** Starts a model generation step. */
61
81
  readonly type: "step-start";
62
82
  readonly messageId: string;
63
83
  }
64
84
  | {
85
+ /** Finishes a model generation step and reports usage for that step. */
65
86
  readonly type: "step-finish";
66
87
  readonly finishReason:
67
88
  | "stop"
@@ -78,6 +99,7 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
78
99
  readonly isContinued: boolean;
79
100
  }
80
101
  | {
102
+ /** Finishes the assistant message and reports final usage. */
81
103
  readonly type: "message-finish";
82
104
  readonly finishReason:
83
105
  | "stop"
@@ -93,6 +115,12 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
93
115
  };
94
116
  }
95
117
  | {
118
+ /**
119
+ * Emits the result for a tool-call part.
120
+ *
121
+ * `artifact` is UI-visible metadata, while `modelContent` can override
122
+ * what is sent back to the model.
123
+ */
96
124
  readonly type: "result";
97
125
  readonly artifact?: ReadonlyJSONValue;
98
126
  readonly result: ReadonlyJSONValue;
@@ -101,10 +129,12 @@ export type AssistantStreamChunk = { readonly path: readonly number[] } & (
101
129
  readonly messages?: ReadonlyJSONValue;
102
130
  }
103
131
  | {
132
+ /** Emits a stream-level error message. */
104
133
  readonly type: "error";
105
134
  readonly error: string;
106
135
  }
107
136
  | {
137
+ /** Applies object-stream operations to state carried by this stream. */
108
138
  readonly type: "update-state";
109
139
  readonly operations: ObjectStreamOperation[];
110
140
  }
@@ -29,18 +29,63 @@ type ToolCallPartInit = {
29
29
  response?: ToolResponseLike<ReadonlyJSONValue>;
30
30
  };
31
31
 
32
+ /**
33
+ * Imperative writer for constructing an {@link AssistantStream}.
34
+ *
35
+ * The controller handles part boundaries for common streaming operations. Use
36
+ * `appendText` and `appendReasoning` for simple token streams, or open explicit
37
+ * parts with `addTextPart` and `addToolCallPart` when you need direct control.
38
+ */
32
39
  export type AssistantStreamController = {
40
+ /** Appends text to the current text part, opening one if needed. */
33
41
  appendText(textDelta: string): void;
42
+ /** Appends reasoning text to the current reasoning part, opening one if needed. */
34
43
  appendReasoning(reasoningDelta: string): void;
44
+ /** Appends a source citation part to the stream. */
35
45
  appendSource(options: SourcePart): void;
46
+ /** Appends a file part to the stream. */
36
47
  appendFile(options: FilePart): void;
48
+ /** Appends a named data part to the stream. */
37
49
  appendData(options: DataPart): void;
50
+ /**
51
+ * Opens a text part and returns its writer.
52
+ *
53
+ * Close the returned controller when the text part is complete. Opening a new
54
+ * part through this controller closes any implicit text or reasoning append
55
+ * part first.
56
+ */
38
57
  addTextPart(): TextStreamController;
58
+ /**
59
+ * Opens a tool-call part by tool name and returns its writer.
60
+ *
61
+ * A tool call id is generated automatically. Use the object overload when the
62
+ * caller already has an id, initial args, args text, or response.
63
+ */
39
64
  addToolCallPart(options: string): ToolCallStreamController;
65
+ /**
66
+ * Opens a tool-call part and returns its writer.
67
+ *
68
+ * Use this overload to provide a stable `toolCallId`, initial arguments,
69
+ * streamed argument text, or an immediate {@link ToolResponseLike}.
70
+ */
40
71
  addToolCallPart(options: ToolCallPartInit): ToolCallStreamController;
72
+ /** Enqueues a raw protocol chunk. Prefer higher-level helpers when possible. */
41
73
  enqueue(chunk: AssistantStreamChunk): void;
74
+ /**
75
+ * Merges another assistant stream into this stream.
76
+ *
77
+ * Paths from the merged stream are remapped so its parts appear at the next
78
+ * available position in this controller's output.
79
+ */
42
80
  merge(stream: AssistantStream): void;
81
+ /** Closes any active part and finishes the stream. */
43
82
  close(): void;
83
+ /**
84
+ * Returns a controller that writes child parts with `parentId` attached.
85
+ *
86
+ * Use this for nested or related parts that should be associated with an
87
+ * existing message or part in downstream renderers.
88
+ */
44
89
  withParentId(parentId: string): AssistantStreamController;
45
90
  };
46
91
 
@@ -226,6 +271,15 @@ class AssistantStreamControllerImpl implements AssistantStreamController {
226
271
  }
227
272
  }
228
273
 
274
+ /**
275
+ * Creates an {@link AssistantStream} and writes to it with an
276
+ * {@link AssistantStreamController}.
277
+ *
278
+ * The callback may write synchronously or asynchronously. If it throws, an
279
+ * `error` chunk is emitted before the error is rethrown; when the callback
280
+ * settles, the stream is closed automatically unless the controller was
281
+ * already closed.
282
+ */
229
283
  export function createAssistantStream(
230
284
  callback: (controller: AssistantStreamController) => PromiseLike<void> | void,
231
285
  ): AssistantStream {
@@ -254,6 +308,13 @@ export function createAssistantStream(
254
308
  return controller.__internal_getReadable();
255
309
  }
256
310
 
311
+ /**
312
+ * Creates an {@link AssistantStream} together with the controller used to
313
+ * write into it.
314
+ *
315
+ * Use this when the stream needs to be returned before all writers are known.
316
+ * Closing the returned controller finishes the paired stream.
317
+ */
257
318
  export function createAssistantStreamController() {
258
319
  const { resolve, promise } = promiseWithResolvers<void>();
259
320
  let controller!: AssistantStreamController;
@@ -269,6 +330,13 @@ export function createAssistantStreamController() {
269
330
  return [stream, controller] as const;
270
331
  }
271
332
 
333
+ /**
334
+ * Creates a `Response` whose body is an encoded {@link AssistantStream}.
335
+ *
336
+ * This is the HTTP-route convenience form of {@link createAssistantStream}; it
337
+ * uses {@link DataStreamEncoder} so the response can be consumed by matching
338
+ * assistant-ui data stream decoders.
339
+ */
272
340
  export function createAssistantStreamResponse(
273
341
  callback: (controller: AssistantStreamController) => PromiseLike<void> | void,
274
342
  ) {
@@ -1,16 +1,53 @@
1
1
  import type { ReadonlyJSONValue } from "../../utils/json/json-value";
2
- import type { ToolModelContentPart } from "./tool-types";
2
+ import type {
3
+ ToolModelContentPart,
4
+ ToolModelOutputFunction,
5
+ } from "./tool-types";
3
6
 
4
7
  const TOOL_RESPONSE_SYMBOL = Symbol.for("aui.tool-response");
5
8
 
9
+ /**
10
+ * Shape accepted anywhere a {@link ToolResponse} can be returned.
11
+ */
6
12
  export type ToolResponseLike<TResult> = {
13
+ /** UI-visible tool result value. */
7
14
  result: TResult;
15
+ /**
16
+ * Optional UI-only artifact associated with the result.
17
+ *
18
+ * Artifacts are useful for large or structured data that should be available
19
+ * to renderers without necessarily being sent back to the model.
20
+ */
8
21
  artifact?: ReadonlyJSONValue | undefined;
22
+ /** Marks the tool result as an error result. */
9
23
  isError?: boolean | undefined;
24
+ /**
25
+ * Explicit model-visible content to send back after the tool call.
26
+ *
27
+ * When omitted, assistant-ui derives model output from `result` or a tool's
28
+ * {@link ToolModelOutputFunction}.
29
+ */
10
30
  modelContent?: readonly ToolModelContentPart[] | undefined;
31
+ /** Optional provider-specific message payload associated with the tool result. */
11
32
  messages?: ReadonlyJSONValue | undefined;
12
33
  };
13
34
 
35
+ /**
36
+ * Tool result wrapper for separating UI-visible output from model-visible
37
+ * output.
38
+ *
39
+ * Return `ToolResponse` from a tool when you need to attach an artifact, mark
40
+ * the result as an error, or control the content sent back to the model.
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * return new ToolResponse({
45
+ * result: { title: "Report ready" },
46
+ * artifact: { reportId },
47
+ * modelContent: [{ type: "text", text: "The report is ready." }],
48
+ * });
49
+ * ```
50
+ */
14
51
  export class ToolResponse<TResult> {
15
52
  get [TOOL_RESPONSE_SYMBOL]() {
16
53
  return true;
@@ -44,6 +81,13 @@ export class ToolResponse<TResult> {
44
81
  );
45
82
  }
46
83
 
84
+ /**
85
+ * Converts a plain tool return value into a {@link ToolResponse}.
86
+ *
87
+ * Existing `ToolResponse` instances are returned unchanged. `undefined`
88
+ * becomes the string `"<no result>"` so downstream protocol chunks always
89
+ * carry a concrete result.
90
+ */
47
91
  static toResponse(result: any | ToolResponse<any>): ToolResponse<any> {
48
92
  if (result instanceof ToolResponse) {
49
93
  return result;
@@ -6,19 +6,56 @@ import type { ToolResponse } from "./ToolResponse";
6
6
 
7
7
  export type ToolModelContentPart =
8
8
  | {
9
+ /** A text content part returned to the model after a tool call. */
9
10
  readonly type: "text";
11
+ /** Text that should be included in the model-visible tool result. */
10
12
  readonly text: string;
11
13
  }
12
14
  | {
15
+ /** A file content part returned to the model after a tool call. */
13
16
  readonly type: "file";
17
+ /**
18
+ * File payload encoded as a provider-compatible string, commonly base64
19
+ * for binary data.
20
+ */
14
21
  readonly data: string;
22
+ /** MIME type for the file payload. */
15
23
  readonly mediaType: string;
24
+ /** Optional display filename for the file payload. */
16
25
  readonly filename?: string;
17
26
  };
18
27
 
28
+ /**
29
+ * Converts a tool's runtime result into content that is sent back to the
30
+ * model.
31
+ *
32
+ * Return this when the value shown in the UI or stored as the tool result
33
+ * should differ from the model-visible response. When omitted, the successful
34
+ * tool result is sent back to the model as-is. If a tool returns a
35
+ * `ToolResponse` with `modelContent`, that explicit content is used instead
36
+ * of calling this function.
37
+ *
38
+ * @example
39
+ * ```ts
40
+ * const toModelOutput: ToolModelOutputFunction<
41
+ * { documentId: string },
42
+ * { summary: string; pdfBase64: string }
43
+ * > = ({ output }) => [
44
+ * { type: "text", text: output.summary },
45
+ * {
46
+ * type: "file",
47
+ * data: output.pdfBase64,
48
+ * mediaType: "application/pdf",
49
+ * },
50
+ * ];
51
+ * ```
52
+ */
19
53
  export type ToolModelOutputFunction<TArgs, TResult> = (options: {
54
+ /** Stable identifier for the tool call being converted. */
20
55
  toolCallId: string;
56
+ /** Arguments supplied by the model for this tool call. */
21
57
  input: TArgs;
58
+ /** Value returned by the tool's {@link ToolExecuteFunction}. */
22
59
  output: TResult;
23
60
  }) =>
24
61
  | readonly ToolModelContentPart[]
@@ -90,7 +127,8 @@ export interface ToolCallReader<
90
127
  response: ToolCallResponseReader<TResult>;
91
128
 
92
129
  /**
93
- * @deprecated Deprecated. Use `response.get().result` instead.
130
+ * @deprecated Use {@link ToolCallReader.response} and read
131
+ * `response.get().result` instead.
94
132
  */
95
133
  result: {
96
134
  get: () => Promise<TResult>;
@@ -98,11 +136,20 @@ export interface ToolCallReader<
98
136
  }
99
137
 
100
138
  export type ToolExecutionContext = {
139
+ /** Stable identifier for the tool call being executed. */
101
140
  toolCallId: string;
141
+ /** Signal that is aborted when the current run is cancelled. */
102
142
  abortSignal: AbortSignal;
143
+ /**
144
+ * From inside a frontend tool's execute function, request human input from
145
+ * the UI. Resolves with the payload the UI supplies.
146
+ */
103
147
  human: (payload: unknown) => Promise<unknown>;
104
148
  };
105
149
 
150
+ /**
151
+ * Function called when assistant-ui executes a frontend tool.
152
+ */
106
153
  export type ToolExecuteFunction<TArgs, TResult> = (
107
154
  args: TArgs,
108
155
  context: ToolExecutionContext,
@@ -135,6 +182,7 @@ type BackendTool<
135
182
  TArgs extends Record<string, unknown> = Record<string, unknown>,
136
183
  TResult = unknown,
137
184
  > = ToolBase<TArgs, TResult> & {
185
+ /** Tool that is executed by the backend rather than in the browser. */
138
186
  type: "backend";
139
187
 
140
188
  description?: undefined;
@@ -149,13 +197,20 @@ type FrontendTool<
149
197
  TArgs extends Record<string, unknown> = Record<string, unknown>,
150
198
  TResult = unknown,
151
199
  > = ToolBase<TArgs, TResult> & {
200
+ /** Tool that is executed in the frontend runtime. */
152
201
  type: "frontend";
153
202
 
203
+ /** Natural-language description shown to the model when selecting tools. */
154
204
  description?: string | undefined;
205
+ /** Schema for the arguments the model must provide when calling the tool. */
155
206
  parameters: StandardSchemaV1<TArgs> | JSONSchema7;
207
+ /** Prevents the tool from being exposed to the model while true. */
156
208
  disabled?: boolean;
209
+ /** Executes the tool after the model provides valid arguments. */
157
210
  execute: ToolExecuteFunction<TArgs, TResult>;
211
+ /** Converts the execution result into model-visible output. */
158
212
  toModelOutput?: ToolModelOutputFunction<TArgs, TResult>;
213
+ /** Handles invalid tool arguments when schema validation fails. */
159
214
  experimental_onSchemaValidationError?: OnSchemaValidationErrorFunction<TResult>;
160
215
  };
161
216
 
@@ -163,16 +218,61 @@ type HumanTool<
163
218
  TArgs extends Record<string, unknown> = Record<string, unknown>,
164
219
  TResult = unknown,
165
220
  > = ToolBase<TArgs, TResult> & {
221
+ /** Tool that pauses the run until a user or UI supplies a result. */
166
222
  type: "human";
167
223
 
224
+ /** Natural-language description shown to the model when selecting tools. */
168
225
  description?: string | undefined;
226
+ /** Schema for the arguments the model must provide when requesting input. */
169
227
  parameters: StandardSchemaV1<TArgs> | JSONSchema7;
228
+ /** Prevents the tool from being exposed to the model while true. */
170
229
  disabled?: boolean;
171
230
  execute?: undefined;
172
231
  toModelOutput?: undefined;
173
232
  experimental_onSchemaValidationError?: undefined;
174
233
  };
175
234
 
235
+ /**
236
+ * Definition for a tool that can be exposed to the assistant model.
237
+ *
238
+ * Use `type: "frontend"` for tools executed in the browser, `type: "backend"`
239
+ * for tools handled by your server, and `type: "human"` for flows that pause
240
+ * until the UI supplies a result.
241
+ *
242
+ * @example
243
+ * ```ts
244
+ * const frontendTool: Tool<{ city: string }, string> = {
245
+ * type: "frontend",
246
+ * description: "Get the weather for a city.",
247
+ * parameters: {
248
+ * type: "object",
249
+ * properties: { city: { type: "string" } },
250
+ * required: ["city"],
251
+ * },
252
+ * execute: async ({ city }) => `Sunny in ${city}`,
253
+ * };
254
+ * ```
255
+ *
256
+ * @example
257
+ * ```ts
258
+ * const backendTool: Tool = {
259
+ * type: "backend",
260
+ * };
261
+ * ```
262
+ *
263
+ * @example
264
+ * ```ts
265
+ * const humanTool: Tool<{ question: string }, string> = {
266
+ * type: "human",
267
+ * description: "Ask the user a follow-up question.",
268
+ * parameters: {
269
+ * type: "object",
270
+ * properties: { question: { type: "string" } },
271
+ * required: ["question"],
272
+ * },
273
+ * };
274
+ * ```
275
+ */
176
276
  export type Tool<
177
277
  TArgs extends Record<string, unknown> = Record<string, unknown>,
178
278
  TResult = unknown,
@@ -183,7 +283,7 @@ export type Tool<
183
283
  | ToolWithoutType<TArgs, TResult>;
184
284
 
185
285
  /**
186
- * @deprecated Use `Tool` with an explicit `type` field instead.
286
+ * @deprecated Use {@link Tool} with an explicit `type` field instead.
187
287
  */
188
288
  export type ToolWithoutType<
189
289
  TArgs extends Record<string, unknown> = Record<string, unknown>,
@@ -214,10 +214,25 @@ export async function unstable_runPendingTools(
214
214
  }
215
215
 
216
216
  export type ToolResultStreamOptions = {
217
+ /** Called immediately before a frontend tool's `execute` function runs. */
217
218
  onExecutionStart?: (toolCallId: string, toolName: string) => void;
219
+ /** Called after frontend tool execution finishes or fails. */
218
220
  onExecutionEnd?: (toolCallId: string, toolName: string) => void;
219
221
  };
220
222
 
223
+ /**
224
+ * Transform stream that executes frontend tools and appends tool results.
225
+ *
226
+ * The transform watches streamed tool-call arguments, runs the matching
227
+ * frontend tool once its arguments are complete, and emits a result chunk for
228
+ * the tool call. Backend and human tools pass through according to their tool
229
+ * definition.
230
+ *
231
+ * @param tools Tool registry or function returning the current registry.
232
+ * @param abortSignal Signal, or signal getter, used for the current run.
233
+ * @param human Callback used to resolve human-tool requests from UI input.
234
+ * @param options Optional execution lifecycle callbacks.
235
+ */
221
236
  export function toolResultStream(
222
237
  tools:
223
238
  | Record<string, Tool>
@@ -1 +0,0 @@
1
- {"version":3,"file":"AssistantStreamChunk.js","sourceRoot":"","sources":["../../src/core/AssistantStreamChunk.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/object/types.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"chunk-types.js","sourceRoot":"","sources":["../../../../src/core/serialization/ui-message-stream/chunk-types.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"tool-types.js","sourceRoot":"","sources":["../../../src/core/tool/tool-types.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"type-path-utils.js","sourceRoot":"","sources":["../../../src/core/tool/type-path-utils.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"UnderlyingReadable.js","sourceRoot":"","sources":["../../../../src/core/utils/stream/UnderlyingReadable.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/utils/types.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,+BAA+B,GAChC,2CAAwC;AACzC,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,IAAI,6BAA6B,GACtD,6DAA0D;AAC3D,OAAO,EAAE,eAAe,EAAE,kCAA+B;AACzD,YAAY,EAAE,yBAAyB,EAAE,2CAAwC;AACjF,YAAY,EAAE,oBAAoB,EAAE,uCAAoC;AACxE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,GAClB,uDAAoD;AACrD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,0CAAuC;AACxC,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,uEAAoE;AACrE,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,GACnC,kEAA+D;AAChE,OAAO,EAAE,sBAAsB,EAAE,sDAAmD;AACpF,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,QAAQ,GACT,8BAA2B;AAE5B,YAAY,EACV,IAAI,EACJ,oBAAoB,EACpB,uBAAuB,GACxB,kCAA+B;AAChC,OAAO,EAAE,YAAY,EAAE,KAAK,gBAAgB,EAAE,oCAAiC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,2CAAwC;AACtE,YAAY,EAAE,cAAc,EAAE,kCAA+B;AAC7D,OAAO,EACL,gBAAgB,IAAI,yBAAyB,EAC7C,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,wCAAqC;AACtC,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,wBAAwB,GAC9B,oCAAiC;AAElC,YAAY,EAAE,oBAAoB,EAAE,+BAA4B;AAChE,YAAY,EAAE,wBAAwB,EAAE,oCAAiC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,4CAAyC;AACtE,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,8CAA2C;AAC5C,YAAY,EAAE,iBAAiB,EAAE,+BAA4B;AAE7D,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,+CAA4C"}
package/dist/index.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,+BAA+B,GAChC,2CAAwC;AACzC,OAAO,EACL,2BAA2B,EAC3B,oBAAoB,IAAI,6BAA6B,GACtD,6DAA0D;AAC3D,OAAO,EAAE,eAAe,EAAE,kCAA+B;AAGzD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,GAClB,uDAAoD;AACrD,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,0CAAuC;AACxC,OAAO,EACL,yBAAyB,EACzB,yBAAyB,GAC1B,uEAAoE;AACrE,OAAO,EACL,sBAAsB,GAIvB,kEAA+D;AAChE,OAAO,EAAE,sBAAsB,EAAE,sDAAmD;AAYpF,OAAO,EAAE,YAAY,EAAyB,oCAAiC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,2CAAwC;AAEtE,OAAO,EACL,gBAAgB,IAAI,yBAAyB,EAC7C,wBAAwB,GAEzB,wCAAqC;AACtC,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,GAGlB,oCAAiC;AAKlC,OAAO,EAAE,kBAAkB,EAAE,4CAAyC;AACtE,OAAO,EACL,oBAAoB,EACpB,wBAAwB,GACzB,8CAA2C;AAG5C,OAAO,EACL,iBAAiB,GAUlB,+CAA4C"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resumable/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,GAC9B,mBAAgB;AAEjB,OAAO,EACL,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,oBAAiB;AAElB,OAAO,EACL,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,oCAAiC;AAElC,OAAO,EACL,sCAAsC,EACtC,mCAAmC,EACnC,0BAA0B,EAC1B,KAAK,6CAA6C,EAClD,KAAK,0CAA0C,GAChD,oDAAiD;AAElD,OAAO,EACL,kCAAkC,EAClC,KAAK,mCAAmC,GACzC,iDAA8C;AAE/C,YAAY,EACV,eAAe,EACf,gCAAgC,GACjC,+BAA4B"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resumable/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,oBAAoB,GAErB,oBAAiB;AAElB,OAAO,EACL,4BAA4B,GAG7B,oCAAiC;AAElC,OAAO,EACL,sCAAsC,EACtC,mCAAmC,EACnC,0BAA0B,GAG3B,oDAAiD;AAElD,OAAO,EACL,kCAAkC,GAEnC,iDAA8C"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/resumable/types.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"json-value.js","sourceRoot":"","sources":["../../../src/utils/json/json-value.ts"],"names":[],"mappings":""}
@@ -1 +0,0 @@
1
- {"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,GACzB,kDAA+C;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,qBAAqB,GACtB,uCAAoC;AACrC,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,mCAAgC;AAEjC,OAAO,EAAE,wBAAwB,EAAE,wDAAqD;AACxF,OAAO,EAAE,4BAA4B,EAAE,4DAAyD"}
package/dist/utils.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,8BAA8B,EAC9B,wBAAwB,GACzB,kDAA+C;AAChD,OAAO,EAEL,qBAAqB,GACtB,uCAAoC;AAOrC,OAAO,EAAE,wBAAwB,EAAE,wDAAqD;AACxF,OAAO,EAAE,4BAA4B,EAAE,4DAAyD"}