@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 +73 -17
- package/dist/chat-controller.d.ts +106 -0
- package/dist/chat-controller.js +361 -0
- package/dist/{react/chat-state.d.ts → chat-state.d.ts} +16 -12
- package/dist/{react/chat-state.js → chat-state.js} +13 -12
- package/dist/chat-transport.d.ts +6 -1
- package/dist/chat-transport.js +33 -16
- package/dist/contracts/entities/agents.d.ts +5 -0
- package/dist/contracts/entities/agents.js +36 -0
- package/dist/contracts/entities/sessions.d.ts +1 -0
- package/dist/contracts/entities/tasks.d.ts +8 -4
- package/dist/contracts/entities/tasks.js +9 -28
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/react/index.d.ts +2 -2
- package/dist/react/index.js +1 -1
- package/dist/react/use-blazing-agents-chat.d.ts +14 -71
- package/dist/react/use-blazing-agents-chat.js +26 -239
- package/package.json +4 -10
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
|
|
30
|
-
`
|
|
31
|
-
|
|
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.
|
|
123
|
-
|
|
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
|
|
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
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
`addToolApprovalResponse()
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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)`.
|
|
3
|
-
*
|
|
4
|
-
* and the transport, and runs the effects it
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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 "
|
|
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
|
|
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;
|
|
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;
|
|
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
|
-
/**
|
|
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: "
|
|
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
|
}
|