@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 +128 -6
- package/dist/chat-controller.d.ts +106 -0
- package/dist/chat-controller.js +361 -0
- package/dist/chat-relay-wire.d.ts +53 -0
- package/dist/chat-relay-wire.js +60 -0
- package/dist/chat-state.d.ts +201 -0
- package/dist/chat-state.js +426 -0
- package/dist/chat-transport.d.ts +62 -4
- package/dist/chat-transport.js +175 -17
- package/dist/contracts/entities/session-inputs.d.ts +4 -4
- package/dist/contracts/entities/session-inputs.js +1 -1
- package/dist/contracts/entities/session-messages.d.ts +20 -0
- package/dist/contracts/entities/session-messages.js +21 -0
- package/dist/contracts/entities/sessions.d.ts +0 -19
- package/dist/contracts/entities/sessions.js +1 -20
- package/dist/contracts/entities/tasks.d.ts +6 -4
- package/dist/contracts/entities/tasks.js +9 -28
- package/dist/contracts/index.d.ts +3 -2
- package/dist/contracts/index.js +2 -1
- package/dist/http.d.ts +27 -1
- package/dist/http.js +42 -27
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1 -0
- package/dist/react/index.d.ts +5 -0
- package/dist/react/index.js +6 -0
- package/dist/react/use-blazing-agents-chat.d.ts +19 -0
- package/dist/react/use-blazing-agents-chat.js +33 -0
- package/dist/relay.d.ts +10 -4
- package/dist/relay.js +99 -53
- package/package.json +20 -5
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
|
-
- `
|
|
30
|
-
|
|
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`.
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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>;
|