@blazingagents/sdk 0.52.0 → 0.54.0

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.
package/README.md CHANGED
@@ -26,9 +26,10 @@ Node.js 24 or newer.
26
26
  - End-user scoped clients through `forUser`.
27
27
  - Cursor pagination, uploads, and downloads.
28
28
  - Request IDs and typed errors.
29
- - `createChatRelay` serves browser chat from your backend, and
30
- `useBlazingAgentsChat` from `@blazingagents/sdk/react` drives it from React:
31
- history restore, steering, and rollback included.
29
+ - `createChatRelay` serves browser chat from your backend.
30
+ `BlazingAgentsChat` drives it from any UI framework, and
31
+ `useBlazingAgentsChat` from `@blazingagents/sdk/react` drives it from React,
32
+ with history restore, steering, and rollback.
32
33
 
33
34
  ## Installation
34
35
 
@@ -119,11 +120,64 @@ export const relayChat = createChatRelay({
119
120
  app.post("/api/chat", (c) => relayChat(c.req.raw));
120
121
  ```
121
122
 
122
- `signedInUser` stands for your own session lookup. In React, install the
123
- optional peers and call `useBlazingAgentsChat`:
123
+ `signedInUser` stands for your own session lookup.
124
+
125
+ In the browser, `BlazingAgentsChat` runs the chat in any UI framework. It
126
+ keeps the Session ID in `localStorage`, restores the stored transcript after a
127
+ reload, steers the running Turn when you send while a reply streams, and rolls
128
+ back to the stored transcript on an error, Stop, or New Session. Render
129
+ `getSnapshot()` and read it again each time a `subscribe` listener runs. The
130
+ snapshot is a new object only when something in it changed. Call `start()`
131
+ once the component is in the page and `dispose()` when it leaves. In Vue:
132
+
133
+ ```ts
134
+ import { BlazingAgentsChat } from "@blazingagents/sdk";
135
+ import { onMounted, onUnmounted, shallowRef } from "vue";
136
+
137
+ export function useChat(headers: Record<string, string>) {
138
+ const chat = new BlazingAgentsChat({ headers });
139
+ const snapshot = shallowRef(chat.getSnapshot());
140
+ const unsubscribe = chat.subscribe(() => {
141
+ snapshot.value = chat.getSnapshot();
142
+ });
143
+ onMounted(chat.start);
144
+ onUnmounted(() => {
145
+ unsubscribe();
146
+ chat.dispose();
147
+ });
148
+ return { chat, snapshot };
149
+ }
150
+ ```
151
+
152
+ In Angular, keep the snapshot in a signal and render `snapshot().messages`:
153
+
154
+ ```ts
155
+ import { afterNextRender, Component, DestroyRef, inject, signal } from "@angular/core";
156
+ import { BlazingAgentsChat } from "@blazingagents/sdk";
157
+
158
+ @Component({ selector: "app-chat", templateUrl: "./chat.component.html" })
159
+ export class ChatComponent {
160
+ readonly chat = new BlazingAgentsChat({ api: "/api/chat" });
161
+ readonly snapshot = signal(this.chat.getSnapshot());
162
+
163
+ constructor() {
164
+ const unsubscribe = this.chat.subscribe(() =>
165
+ this.snapshot.set(this.chat.getSnapshot())
166
+ );
167
+ afterNextRender(this.chat.start);
168
+ inject(DestroyRef).onDestroy(() => {
169
+ unsubscribe();
170
+ this.chat.dispose();
171
+ });
172
+ }
173
+ }
174
+ ```
175
+
176
+ In React, install the optional `react` peer and call `useBlazingAgentsChat`,
177
+ which runs one `BlazingAgentsChat` per component:
124
178
 
125
179
  ```console
126
- npm install react @ai-sdk/react
180
+ npm install react
127
181
  ```
128
182
 
129
183
  ```tsx
@@ -155,17 +209,19 @@ export function Chat({ token }: { token: string }) {
155
209
  }
156
210
  ```
157
211
 
158
- The hook posts to `/api/chat` unless you pass `api`. It keeps the Session ID
159
- in `localStorage` and restores the stored transcript after a reload. `send()`
160
- starts a Turn when the chat is idle and steers the running Turn otherwise. It
161
- resolves `true` once the message is stored, and `false` when an error, Stop,
162
- or New Session rolled it back, so you can put the text back in the input. The
163
- hook also returns `status`, `stop()`, `regenerate()`, `newSession()`,
164
- `addToolApprovalResponse()`, `pendingIds`, and `error`.
165
-
166
- `BlazingAgentsChatTransport` is the same browser side without React, for an
167
- AI SDK `Chat` in another framework. A relay written in another language
168
- follows the [browser relay contract](docs/relay-contract.md).
212
+ The chat posts to `/api/chat` unless you pass `api`. `send()` starts a Turn
213
+ when the chat is idle and steers the running Turn otherwise. It resolves
214
+ `true` once the message is stored, and `false` when an error, Stop, or New
215
+ Session rolled it back, so you can put the text back in the input. The
216
+ snapshot also holds `status`, `pendingIds`, `sessionId`, `canRegenerate`, and
217
+ `error`, and the chat has `stop()`, `regenerate()`, `newSession()`, and
218
+ `addToolApprovalResponse()`. To send a new token, call `setHeaders()`, pass
219
+ `headers` as a function that returns the current ones, or pass new `headers`
220
+ to the hook.
221
+
222
+ `BlazingAgentsChatTransport` is the transport alone, for an AI SDK `Chat` that
223
+ you run yourself. A relay written in another language follows the
224
+ [browser relay contract](docs/relay-contract.md).
169
225
 
170
226
  ## Examples
171
227
 
@@ -0,0 +1,106 @@
1
+ import { type FileUIPart, type UIMessage } from "ai";
2
+ import type { BlazingAgentsUIMessage } from "./types.ts";
3
+ export interface BlazingAgentsChatOptions {
4
+ /** The app's relay endpoint: `createChatRelay`, or a relay in another language. Default `/api/chat`. */
5
+ api?: string;
6
+ credentials?: RequestCredentials;
7
+ fetch?: typeof globalThis.fetch;
8
+ /** Request headers, or a function that returns them, read at each request. Replace them with `setHeaders`. */
9
+ headers?: Record<string, string> | Headers | (() => Record<string, string> | Headers);
10
+ /**
11
+ * localStorage key for the Session ID. Default `blazing-agents-session`;
12
+ * `null` keeps the Session in memory only, as does storage that throws.
13
+ * Read by `start()`, never by the constructor, so server rendering never
14
+ * touches storage.
15
+ */
16
+ storageKey?: string | null;
17
+ }
18
+ /**
19
+ * What to render. `getSnapshot()` returns the same object until a field
20
+ * changes, so `useSyncExternalStore` and signals can compare by identity.
21
+ */
22
+ export interface BlazingAgentsChatSnapshot<M extends UIMessage = BlazingAgentsUIMessage> {
23
+ /** True when idle with a stored assistant reply to replace. */
24
+ readonly canRegenerate: boolean;
25
+ /** The last failure: a failed Turn, steer, or history read. Cleared by the next send. */
26
+ readonly error: Error | undefined;
27
+ /** Oldest first: the stored transcript, the streaming reply, and sent messages not stored yet. */
28
+ readonly messages: readonly M[];
29
+ /** IDs in `messages` that are sent but not stored yet. */
30
+ readonly pendingIds: ReadonlySet<string>;
31
+ /** The Session, once restored or minted by the first reply. */
32
+ readonly sessionId: string | undefined;
33
+ /**
34
+ * `restoring`: reading the stored transcript, or, after that read failed
35
+ * (see `error`), waiting for new headers, a `send`, or `clearError` to read
36
+ * it again. `running`: a Turn is starting, streaming, or being placed in
37
+ * stored history. `send` works in every status.
38
+ */
39
+ readonly status: "restoring" | "idle" | "running";
40
+ }
41
+ /**
42
+ * A Blazing Agents chat through the app's relay, for any UI framework: the
43
+ * Session kept in localStorage, history restored after a reload, steering
44
+ * while a reply streams, and rollback on failure. Render `getSnapshot()` and
45
+ * re-read it whenever a `subscribe` listener runs. Call `start()` once the
46
+ * chat is mounted in a browser and `dispose()` when it unmounts; `start()`
47
+ * may follow `dispose()` again. Every method is bound, so it can be passed as
48
+ * a callback.
49
+ */
50
+ export declare class BlazingAgentsChat<M extends UIMessage = BlazingAgentsUIMessage> {
51
+ #private;
52
+ /**
53
+ * Creates the chat without touching storage or the network.
54
+ * @param options - Relay endpoint, request options, and storage key.
55
+ */
56
+ constructor(options?: BlazingAgentsChatOptions);
57
+ /**
58
+ * Runs `listener` after each change to the snapshot.
59
+ * @param listener - Re-reads `getSnapshot()`.
60
+ * @returns Removes the listener.
61
+ */
62
+ readonly subscribe: (listener: () => void) => (() => void);
63
+ /** @returns What to render now. */
64
+ readonly getSnapshot: () => BlazingAgentsChatSnapshot<M>;
65
+ /** Reads the stored Session from localStorage and restores its transcript. Does nothing when already started. */
66
+ readonly start: () => void;
67
+ /** Cancels the running Turn and resolves every pending `send()` with false. Answers still in flight change nothing. */
68
+ readonly dispose: () => void;
69
+ /**
70
+ * Replaces the request headers, so a new token applies to the next request.
71
+ * When their values differ from the last ones given, even inside the same
72
+ * `Headers` object, and history could not be read, reads it again, as the
73
+ * next `send` or `clearError` does.
74
+ * @param headers - The headers every later request carries, or a function that returns them.
75
+ */
76
+ readonly setHeaders: (headers: BlazingAgentsChatOptions["headers"]) => void;
77
+ /**
78
+ * Sends a user message. Idle: starts a Turn. While a Turn runs: steers into
79
+ * it, or sends it as the next Turn when this one cannot take it. Never sends
80
+ * a message twice.
81
+ * @param input - Text, or text with files.
82
+ * @returns Resolves true once the message is stored in the Session, and false when it was rolled back by an error, Stop, New Session, or `dispose()`. Never rejects.
83
+ */
84
+ readonly send: (input: string | {
85
+ files?: FileUIPart[];
86
+ text: string;
87
+ }) => Promise<boolean>;
88
+ /** Replaces the last assistant reply. Does nothing unless `canRegenerate`. */
89
+ readonly regenerate: () => void;
90
+ /** Cancels the running Turn and rolls back to the stored transcript. */
91
+ readonly stop: () => void;
92
+ /** Cancels any running Turn, forgets the stored Session, and clears the transcript. */
93
+ readonly newSession: () => void;
94
+ /** Clears `error`. When history could not be read, also reads it again. */
95
+ readonly clearError: () => void;
96
+ /**
97
+ * Answers a pending Tool approval. Once every approval of the round is
98
+ * answered, the continuation streams like any Turn.
99
+ * @param response - The approval ID, the decision, and an optional reason.
100
+ */
101
+ readonly addToolApprovalResponse: (response: {
102
+ approved: boolean;
103
+ id: string;
104
+ reason?: string;
105
+ }) => void;
106
+ }
@@ -0,0 +1,361 @@
1
+ import { AbstractChat, generateId, lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
2
+ import { canRegenerate, initialChatState, pendingIds, step, } from "./chat-state.js";
3
+ import { BlazingAgentsChatTransport } from "./chat-transport.js";
4
+ import { sessionIdSchema } from "./contracts/ids.js";
5
+ import { BlazingAgentsError } from "./errors.js";
6
+ const DEFAULT_STORAGE_KEY = "blazing-agents-session";
7
+ /** The AI SDK's framework-neutral chat, run over `chatMessages` state. */
8
+ class ConversationChat extends AbstractChat {
9
+ }
10
+ /**
11
+ * A Blazing Agents chat through the app's relay, for any UI framework: the
12
+ * Session kept in localStorage, history restored after a reload, steering
13
+ * while a reply streams, and rollback on failure. Render `getSnapshot()` and
14
+ * re-read it whenever a `subscribe` listener runs. Call `start()` once the
15
+ * chat is mounted in a browser and `dispose()` when it unmounts; `start()`
16
+ * may follow `dispose()` again. Every method is bound, so it can be passed as
17
+ * a callback.
18
+ */
19
+ export class BlazingAgentsChat {
20
+ #listeners = new Set();
21
+ #options;
22
+ /** Events to step, oldest first; the head is the one stepping now. */
23
+ #queue = [];
24
+ #settlers = new Map();
25
+ #storageKey;
26
+ #conversation;
27
+ #epoch = 0;
28
+ #headers;
29
+ /** The values of the headers last given, so `setHeaders` sees a change made inside the same `Headers` object. */
30
+ #headersKey;
31
+ #snapshot = {
32
+ canRegenerate: false,
33
+ error: undefined,
34
+ messages: [],
35
+ pendingIds: new Set(),
36
+ sessionId: undefined,
37
+ status: "restoring",
38
+ };
39
+ #started = false;
40
+ #state = initialChatState;
41
+ /**
42
+ * Creates the chat without touching storage or the network.
43
+ * @param options - Relay endpoint, request options, and storage key.
44
+ */
45
+ constructor(options = {}) {
46
+ this.#options = options;
47
+ this.#headers = options.headers;
48
+ this.#headersKey = headersKey(options.headers);
49
+ this.#storageKey =
50
+ options.storageKey === undefined
51
+ ? DEFAULT_STORAGE_KEY
52
+ : options.storageKey;
53
+ this.#conversation = this.#open(undefined);
54
+ }
55
+ /**
56
+ * Runs `listener` after each change to the snapshot.
57
+ * @param listener - Re-reads `getSnapshot()`.
58
+ * @returns Removes the listener.
59
+ */
60
+ subscribe = (listener) => {
61
+ this.#listeners.add(listener);
62
+ return () => {
63
+ this.#listeners.delete(listener);
64
+ };
65
+ };
66
+ /** @returns What to render now. */
67
+ getSnapshot = () => this.#snapshot;
68
+ /** Reads the stored Session from localStorage and restores its transcript. Does nothing when already started. */
69
+ start = () => {
70
+ if (this.#started) {
71
+ return;
72
+ }
73
+ this.#started = true;
74
+ const key = this.#storageKey;
75
+ const stored = sessionIdSchema.safeParse(key === null ? null : tryStorage((storage) => storage.getItem(key)));
76
+ // A restart keeps the Session in memory when storage holds none.
77
+ this.#conversation = this.#open(stored.success ? stored.data : this.#conversation.transport.sessionId);
78
+ this.#dispatch({ type: "restore" });
79
+ };
80
+ /** Cancels the running Turn and resolves every pending `send()` with false. Answers still in flight change nothing. */
81
+ dispose = () => {
82
+ this.#started = false;
83
+ this.#dispatch({ type: "dispose" });
84
+ this.#epoch += 1;
85
+ };
86
+ /**
87
+ * Replaces the request headers, so a new token applies to the next request.
88
+ * When their values differ from the last ones given, even inside the same
89
+ * `Headers` object, and history could not be read, reads it again, as the
90
+ * next `send` or `clearError` does.
91
+ * @param headers - The headers every later request carries, or a function that returns them.
92
+ */
93
+ setHeaders = (headers) => {
94
+ this.#headers = headers;
95
+ const key = headersKey(headers);
96
+ if (key !== this.#headersKey) {
97
+ this.#headersKey = key;
98
+ this.#dispatch({ type: "credentialsChanged" });
99
+ }
100
+ };
101
+ /**
102
+ * Sends a user message. Idle: starts a Turn. While a Turn runs: steers into
103
+ * it, or sends it as the next Turn when this one cannot take it. Never sends
104
+ * a message twice.
105
+ * @param input - Text, or text with files.
106
+ * @returns Resolves true once the message is stored in the Session, and false when it was rolled back by an error, Stop, New Session, or `dispose()`. Never rejects.
107
+ */
108
+ send = (input) => {
109
+ const { files = [], text } = typeof input === "string" ? { text: input } : input;
110
+ const message = {
111
+ id: generateId(),
112
+ role: "user",
113
+ parts: [...files, { type: "text", text }],
114
+ };
115
+ return new Promise((resolve) => {
116
+ this.#settlers.set(message.id, resolve);
117
+ this.#dispatch({ type: "send", sent: { key: message.id, message } });
118
+ });
119
+ };
120
+ /** Replaces the last assistant reply. Does nothing unless `canRegenerate`. */
121
+ regenerate = () => this.#dispatch({ type: "regenerate" });
122
+ /** Cancels the running Turn and rolls back to the stored transcript. */
123
+ stop = () => this.#dispatch({ type: "stop" });
124
+ /** Cancels any running Turn, forgets the stored Session, and clears the transcript. */
125
+ newSession = () => this.#dispatch({ type: "newSession" });
126
+ /** Clears `error`. When history could not be read, also reads it again. */
127
+ clearError = () => this.#dispatch({ type: "clearError" });
128
+ /**
129
+ * Answers a pending Tool approval. Once every approval of the round is
130
+ * answered, the continuation streams like any Turn.
131
+ * @param response - The approval ID, the decision, and an optional reason.
132
+ */
133
+ addToolApprovalResponse = (response) => {
134
+ const { chat, epoch: at } = this.#conversation;
135
+ Promise.resolve(chat.addToolApprovalResponse(response)).then(() => {
136
+ if (lastAssistantMessageIsCompleteWithApprovalResponses({
137
+ messages: chat.messages,
138
+ })) {
139
+ this.#dispatch({ type: "approvalAnswered" }, at);
140
+ }
141
+ });
142
+ };
143
+ #open(sessionId) {
144
+ this.#epoch += 1;
145
+ const opened = this.#epoch;
146
+ const transport = new BlazingAgentsChatTransport({
147
+ api: this.#options.api,
148
+ credentials: this.#options.credentials,
149
+ fetch: this.#options.fetch,
150
+ headers: () => readHeaders(this.#headers) ?? {},
151
+ onSessionId: (id) => {
152
+ const key = this.#storageKey;
153
+ if (key !== null) {
154
+ tryStorage((storage) => storage.setItem(key, id));
155
+ }
156
+ this.#publish();
157
+ },
158
+ onSteerConsumed: (requestId) => this.#dispatch({ type: "steerConsumed", requestId }, opened),
159
+ onTurnFinish: () => this.#dispatch({ type: "turnFinished" }, opened),
160
+ onTurnStart: () => this.#dispatch({ type: "turnStarted" }, opened),
161
+ sessionId,
162
+ });
163
+ const chat = new ConversationChat({
164
+ id: `blazing-agents-${opened}`,
165
+ onFinish: (event) => this.#dispatch({ type: "turnEnded", result: turnResult(event, chat) }, opened),
166
+ sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
167
+ state: chatMessages(() => this.#publish()),
168
+ transport,
169
+ });
170
+ return { chat, epoch: opened, transport };
171
+ }
172
+ /**
173
+ * Steps `event` synchronously, so two sends in one tick see different
174
+ * states, runs its effects, then publishes once. An event dispatched
175
+ * meanwhile, such as a `send()` from a listener, waits until then, so no
176
+ * listener sees a state whose effects have not run and no effect overwrites
177
+ * a later event's.
178
+ */
179
+ #dispatch(event, from = this.#epoch) {
180
+ if (from !== this.#epoch) {
181
+ return;
182
+ }
183
+ this.#queue.push(event);
184
+ if (this.#queue.length > 1) {
185
+ return;
186
+ }
187
+ try {
188
+ for (let next = this.#queue[0]; next; next = this.#queue[0]) {
189
+ const stepped = step(this.#state, next, generateId);
190
+ this.#state = stepped.state;
191
+ for (const effect of stepped.effects) {
192
+ this.#run(effect);
193
+ }
194
+ this.#notify();
195
+ this.#queue.shift();
196
+ }
197
+ }
198
+ finally {
199
+ // A listener that throws must not leave the queue blocked.
200
+ this.#queue.length = 0;
201
+ }
202
+ }
203
+ #run(effect) {
204
+ const { chat, transport, epoch: at } = this.#conversation;
205
+ switch (effect.type) {
206
+ case "startTurn":
207
+ chat.sendMessage(effect.message);
208
+ return;
209
+ case "regenerate":
210
+ chat.regenerate();
211
+ return;
212
+ case "submitSteer":
213
+ transport
214
+ .steer({ message: effect.message, requestId: effect.requestId })
215
+ .then((outcome) => this.#dispatch({ type: "steerAnswered", requestId: effect.requestId, outcome }, at), (error) => this.#dispatch({
216
+ type: "steerFailed",
217
+ requestId: effect.requestId,
218
+ error,
219
+ answerLost: BlazingAgentsError.isInstance(error) &&
220
+ error.code === "network_error",
221
+ }, at));
222
+ return;
223
+ case "show":
224
+ chat.messages = effect.messages;
225
+ return;
226
+ case "loadHistory":
227
+ transport.loadHistory({ known: effect.known }).then((messages) => this.#dispatch({ type: "historyLoaded", messages }, at), (error) => this.#dispatch({ type: "historyFailed", error, sessionGone: sessionGone(error) }, at));
228
+ return;
229
+ case "abort":
230
+ chat.stop();
231
+ return;
232
+ case "forgetSession": {
233
+ const key = this.#storageKey;
234
+ if (key !== null) {
235
+ tryStorage((storage) => storage.removeItem(key));
236
+ }
237
+ this.#conversation = this.#open(undefined);
238
+ return;
239
+ }
240
+ case "settle":
241
+ this.#settlers.get(effect.key)?.(effect.landed);
242
+ this.#settlers.delete(effect.key);
243
+ return;
244
+ }
245
+ }
246
+ /** Publishes a change made outside a dispatch, such as a streamed chunk; a dispatch publishes once its effects ran. */
247
+ #publish() {
248
+ if (this.#queue.length === 0) {
249
+ this.#notify();
250
+ }
251
+ }
252
+ #notify() {
253
+ const previous = this.#snapshot;
254
+ const next = nextSnapshot(previous, this.#state, this.#conversation);
255
+ if (next === previous) {
256
+ return;
257
+ }
258
+ this.#snapshot = next;
259
+ for (const listener of this.#listeners) {
260
+ listener();
261
+ }
262
+ }
263
+ }
264
+ /** The previous snapshot when nothing a renderer reads changed, else a new one. */
265
+ function nextSnapshot(previous, state, { chat, transport }) {
266
+ const shown = new Set(chat.messages.map((message) => message.id));
267
+ const messages = [
268
+ ...chat.messages,
269
+ ...state.outbox
270
+ .map((entry) => entry.message)
271
+ .filter((message) => !shown.has(message.id)),
272
+ ];
273
+ const pending = pendingIds(state);
274
+ const next = {
275
+ canRegenerate: canRegenerate(state),
276
+ error: state.error,
277
+ messages: sameItems(previous.messages, messages)
278
+ ? previous.messages
279
+ : messages,
280
+ pendingIds: sameItems(previous.pendingIds, pending)
281
+ ? previous.pendingIds
282
+ : pending,
283
+ sessionId: transport.sessionId,
284
+ status: state.phase.kind === "restoring" || state.phase.kind === "idle"
285
+ ? state.phase.kind
286
+ : "running",
287
+ };
288
+ const unchanged = next.canRegenerate === previous.canRegenerate &&
289
+ next.error === previous.error &&
290
+ next.messages === previous.messages &&
291
+ next.pendingIds === previous.pendingIds &&
292
+ next.sessionId === previous.sessionId &&
293
+ next.status === previous.status;
294
+ return unchanged ? previous : next;
295
+ }
296
+ function sameItems(left, right) {
297
+ const a = [...left];
298
+ const b = [...right];
299
+ return a.length === b.length && a.every((item, index) => item === b[index]);
300
+ }
301
+ /**
302
+ * The AI SDK chat's state. Each change replaces the array, so a snapshot
303
+ * that holds the old one never sees it change, then runs `onChange`.
304
+ */
305
+ function chatMessages(onChange) {
306
+ let messages = [];
307
+ const replace = (next) => {
308
+ messages = next;
309
+ onChange();
310
+ };
311
+ return {
312
+ error: undefined,
313
+ status: "ready",
314
+ get messages() {
315
+ return messages;
316
+ },
317
+ set messages(next) {
318
+ replace([...next]);
319
+ },
320
+ pushMessage: (message) => replace([...messages, copyMessage(message)]),
321
+ popMessage: () => replace(messages.slice(0, -1)),
322
+ replaceMessage: (index, message) => replace(messages.with(index, copyMessage(message))),
323
+ // Once per request: the message a reply continues, which the stream then
324
+ // mutates. Browsers throw "Illegal invocation" when structuredClone is called as a method.
325
+ snapshot: (value) => structuredClone(value),
326
+ };
327
+ }
328
+ /** Copies a message and its parts, which the AI SDK's streaming state mutates in place. */
329
+ function copyMessage(message) {
330
+ return { ...message, parts: message.parts.map((part) => ({ ...part })) };
331
+ }
332
+ /** Runs one localStorage call. Where storage throws, as when the browser blocks it or it is full, the Session lives in memory only. */
333
+ function tryStorage(use) {
334
+ try {
335
+ return use(localStorage);
336
+ }
337
+ catch {
338
+ return undefined;
339
+ }
340
+ }
341
+ function readHeaders(headers) {
342
+ return typeof headers === "function" ? headers() : headers;
343
+ }
344
+ /** Header values as one comparable string, so a re-created but equal object is no change. */
345
+ function headersKey(headers) {
346
+ return JSON.stringify([...new Headers(readHeaders(headers))]);
347
+ }
348
+ function turnResult({ finishReason, isAbort, isError, messages, }, chat) {
349
+ if (isAbort) {
350
+ return { outcome: "stopped" };
351
+ }
352
+ if (isError || finishReason === "error") {
353
+ const error = chat.error ?? new Error("The reply failed.");
354
+ return { outcome: "failed", error, sessionGone: sessionGone(error) };
355
+ }
356
+ return { outcome: "closed", messages };
357
+ }
358
+ /** The relay answers 404 for a deleted Session or another End-user's. */
359
+ function sessionGone(error) {
360
+ return BlazingAgentsError.isInstance(error) && error.status === 404;
361
+ }
@@ -1,12 +1,13 @@
1
1
  /**
2
- * The browser chat's policy as one pure function, `step(state, event)`. The
3
- * hook owns the only mutable copy of `ChatState`, feeds it events from `Chat`
4
- * and the transport, and runs the effects it returns. `Chat` owns the rendered
5
- * transcript and the transport owns the Session ID; this module owns what the
6
- * server is known to store, the phase, and the user messages not stored yet.
2
+ * The browser chat's policy as one pure function, `step(state, event)`.
3
+ * `BlazingAgentsChat` owns the only mutable copy of `ChatState`, feeds it
4
+ * events from its AI SDK chat and the transport, and runs the effects it
5
+ * returns. The AI SDK chat owns the rendered transcript and the transport owns
6
+ * the Session ID; this module owns what the server is known to store, the
7
+ * phase, and the user messages not stored yet.
7
8
  */
8
9
  import { type UIMessage } from "ai";
9
- import type { SteerOutcome } from "../chat-transport.ts";
10
+ import type { SteerOutcome } from "./chat-transport.ts";
10
11
  export type UserMessage<M extends UIMessage> = M & {
11
12
  role: "user";
12
13
  };
@@ -76,7 +77,7 @@ export interface ChatState<M extends UIMessage> {
76
77
  phase: Phase<M>;
77
78
  }
78
79
  /**
79
- * How `Chat`'s request ended. `closed`: without an error or a Stop; the Turn
80
+ * How the AI SDK chat's request ended. `closed`: without an error or a Stop; the Turn
80
81
  * completed only if its stream carried `finish`. `sessionGone`: the relay
81
82
  * answered 404, so the Session is deleted or another End-user's.
82
83
  */
@@ -91,7 +92,7 @@ export type TurnResult<M extends UIMessage> = {
91
92
  sessionGone: boolean;
92
93
  };
93
94
  export type ChatEvent<M extends UIMessage> =
94
- /** Read the stored transcript; the hook sends it once per mount. */
95
+ /** Read the stored transcript; sent by each `start()`. */
95
96
  {
96
97
  type: "restore";
97
98
  } | {
@@ -111,7 +112,7 @@ export type ChatEvent<M extends UIMessage> =
111
112
  } | {
112
113
  type: "regenerate";
113
114
  }
114
- /** The user completed an approval round; `Chat` sends the continuation itself. */
115
+ /** The user completed an approval round; the AI SDK chat sends the continuation itself. */
115
116
  | {
116
117
  type: "approvalAnswered";
117
118
  } | {
@@ -121,7 +122,7 @@ export type ChatEvent<M extends UIMessage> =
121
122
  | {
122
123
  type: "turnFinished";
123
124
  }
124
- /** `Chat`'s request ended, however it ended. */
125
+ /** The AI SDK chat's request ended, however it ended. */
125
126
  | {
126
127
  type: "turnEnded";
127
128
  result: TurnResult<M>;
@@ -144,7 +145,7 @@ export type ChatEvent<M extends UIMessage> =
144
145
  } | {
145
146
  type: "newSession";
146
147
  } | {
147
- type: "unmount";
148
+ type: "dispose";
148
149
  } | {
149
150
  type: "clearError";
150
151
  };
@@ -160,8 +161,11 @@ export type ChatEffect<M extends UIMessage> = {
160
161
  } | {
161
162
  type: "show";
162
163
  messages: M[];
163
- } | {
164
+ }
165
+ /** `known`: messages already known to be stored, so the read can stop at the newest page that reaches them; empty reads every page. */
166
+ | {
164
167
  type: "loadHistory";
168
+ known: M[];
165
169
  } | {
166
170
  type: "abort";
167
171
  }