@blazingagents/sdk 0.51.0 → 0.53.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,8 +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
- - `BlazingAgentsChatTransport` and `createChatRelay` connect AI SDK `useChat`
30
- to your backend.
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.
31
33
 
32
34
  ## Installation
33
35
 
@@ -96,10 +98,130 @@ export async function chatAsUser(
96
98
 
97
99
  Call `createAgentForUser` once per user and store the Agent ID with the user.
98
100
  A scoped chat with an Agent created without the scope fails with `404`.
99
- `chatAsUser` returns the chat as a streaming `Response`. To chat from the
100
- browser with `useChat`, serve `createChatRelay` from your backend and use
101
- `BlazingAgentsChatTransport`. The relay scopes each request to the user that
102
- your `resolveContext` returns.
101
+ `chatAsUser` returns the chat as a streaming `Response`.
102
+
103
+ ## Chat from a browser
104
+
105
+ The browser holds no API key, so it chats through your backend. Serve
106
+ `createChatRelay` on one route. It answers chat, history, and steer requests
107
+ as the End-user that your `resolveContext` returns:
108
+
109
+ ```ts
110
+ import { createChatRelay } from "@blazingagents/sdk";
111
+
112
+ export const relayChat = createChatRelay({
113
+ client,
114
+ resolveContext: async (request) => {
115
+ const user = await signedInUser(request);
116
+ return user ? { agentId: user.agentId, userId: user.id } : null;
117
+ },
118
+ });
119
+
120
+ app.post("/api/chat", (c) => relayChat(c.req.raw));
121
+ ```
122
+
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:
178
+
179
+ ```console
180
+ npm install react
181
+ ```
182
+
183
+ ```tsx
184
+ import { useBlazingAgentsChat } from "@blazingagents/sdk/react";
185
+ import { useState } from "react";
186
+
187
+ export function Chat({ token }: { token: string }) {
188
+ const [text, setText] = useState("");
189
+ const chat = useBlazingAgentsChat({
190
+ headers: { authorization: `Bearer ${token}` },
191
+ });
192
+ return (
193
+ <form
194
+ onSubmit={(event) => {
195
+ event.preventDefault();
196
+ chat.send(text);
197
+ setText("");
198
+ }}
199
+ >
200
+ {chat.messages.map((message) => (
201
+ <p key={message.id}>
202
+ {message.role}:{" "}
203
+ {message.parts.map((part) => (part.type === "text" ? part.text : ""))}
204
+ </p>
205
+ ))}
206
+ <input value={text} onChange={(event) => setText(event.target.value)} />
207
+ </form>
208
+ );
209
+ }
210
+ ```
211
+
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).
103
225
 
104
226
  ## Examples
105
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
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The browser-to-relay wire: one POST endpoint whose JSON body names its
3
+ * `op`. `relay.ts` parses requests with these schemas and builds responses
4
+ * that satisfy them; `chat-transport.ts` builds requests from the same types
5
+ * and parses the responses. No public entry exports this module.
6
+ * `docs/relay-contract.md` states the same contract for relays written in
7
+ * other languages; change both together.
8
+ */
9
+ import { z } from "zod";
10
+ /** The relay asks the API for this many messages per history page, the API's maximum. */
11
+ export declare const RELAY_HISTORY_PAGE_SIZE = 200;
12
+ /**
13
+ * Inbound relay body. Unknown keys are stripped, so an app's own `body`
14
+ * extras, read by its `resolveContext`, never reach the API.
15
+ */
16
+ export declare const relayRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
17
+ op: z.ZodLiteral<"chat">;
18
+ message: z.ZodUnknown;
19
+ messageId: z.ZodOptional<z.ZodString>;
20
+ sessionId: z.ZodOptional<z.ZodString>;
21
+ trigger: z.ZodDefault<z.ZodEnum<{
22
+ "regenerate-message": "regenerate-message";
23
+ "submit-message": "submit-message";
24
+ }>>;
25
+ }, z.core.$strip>, z.ZodObject<{
26
+ op: z.ZodLiteral<"history">;
27
+ sessionId: z.ZodString;
28
+ cursor: z.ZodOptional<z.ZodString>;
29
+ }, z.core.$strip>, z.ZodObject<{
30
+ op: z.ZodLiteral<"steer">;
31
+ sessionId: z.ZodString;
32
+ requestId: z.ZodString;
33
+ message: z.ZodUnknown;
34
+ }, z.core.$strip>], "op">;
35
+ export type RelayRequest = z.output<typeof relayRequestSchema>;
36
+ export type RelayRequestBody = z.input<typeof relayRequestSchema>;
37
+ /**
38
+ * `history` 200 body: one API page, newest page first and chronological
39
+ * within it. The relay passes stored messages through unvalidated; the
40
+ * browser validates them.
41
+ */
42
+ export declare const relayHistoryPageSchema: z.ZodObject<{
43
+ data: z.ZodArray<z.ZodUnknown>;
44
+ nextCursor: z.ZodNullable<z.ZodString>;
45
+ }, z.core.$strip>;
46
+ /** `steer` 202 body: the receipt's state when the relay answered. */
47
+ export declare const relaySteerReceiptSchema: z.ZodObject<{
48
+ state: z.ZodEnum<{
49
+ accepted: "accepted";
50
+ committed: "committed";
51
+ not_placed: "not_placed";
52
+ }>;
53
+ }, z.core.$strip>;