orchajs 0.24.0 → 0.25.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 +50 -3
- package/dist/amarsia/analytics.js +12 -0
- package/dist/amarsia/inference.d.ts +6 -0
- package/dist/amarsia/inference.js +337 -0
- package/dist/browser.js +5 -0
- package/dist/cli-agents-template.d.ts +1 -1
- package/dist/cli-agents-template.js +31 -7
- package/dist/compiler/build-project.js +57 -14
- package/dist/compiler/node-esm-banner.d.ts +2 -0
- package/dist/compiler/node-esm-banner.js +5 -0
- package/dist/orcha.js +5 -0
- package/dist/project-loader.js +4 -2
- package/dist/providers/types.d.ts +4 -0
- package/dist/react-native.js +5 -0
- package/dist/runtime/agent.js +103 -14
- package/dist/runtime/compiler-hook.d.ts +4 -0
- package/dist/runtime/compiler-hook.js +9 -0
- package/dist/runtime/create-orcha.d.ts +19 -0
- package/dist/runtime/create-orcha.js +109 -12
- package/dist/runtime/optional-features.d.ts +19 -0
- package/dist/runtime/optional-features.js +22 -0
- package/dist/runtime/platform-browser.js +16 -3
- package/dist/runtime/platform-node.js +16 -2
- package/dist/runtime/platform-react-native.js +16 -3
- package/dist/storage/browser-indexeddb.d.ts +3 -0
- package/dist/storage/browser-indexeddb.js +72 -8
- package/dist/storage/cloud-outbox.d.ts +30 -0
- package/dist/storage/cloud-outbox.js +628 -0
- package/dist/storage/cloud.d.ts +1 -0
- package/dist/storage/cloud.js +1 -0
- package/dist/storage/node-jsonl.d.ts +3 -0
- package/dist/storage/node-jsonl.js +273 -4
- package/dist/storage/node-sqlite.d.ts +3 -0
- package/dist/storage/node-sqlite.js +66 -17
- package/dist/storage/react-native-jsonl.d.ts +3 -0
- package/dist/storage/react-native-jsonl.js +223 -0
- package/dist/types.d.ts +21 -2
- package/dist-cjs/amarsia/analytics.js +12 -0
- package/dist-cjs/amarsia/inference.js +335 -0
- package/dist-cjs/browser.js +5 -0
- package/dist-cjs/cli-agents-template.js +31 -7
- package/dist-cjs/compiler/build-project.js +68 -4
- package/dist-cjs/compiler/node-esm-banner.js +32 -0
- package/dist-cjs/orcha.js +5 -0
- package/dist-cjs/project-loader.js +7 -5
- package/dist-cjs/react-native.js +5 -0
- package/dist-cjs/runtime/agent.js +137 -30
- package/dist-cjs/runtime/compiler-hook.js +11 -0
- package/dist-cjs/runtime/create-orcha.js +117 -12
- package/dist-cjs/runtime/optional-features.js +58 -0
- package/dist-cjs/runtime/platform-browser.js +16 -3
- package/dist-cjs/runtime/platform-node.js +16 -2
- package/dist-cjs/runtime/platform-react-native.js +18 -3
- package/dist-cjs/storage/browser-indexeddb.js +73 -8
- package/dist-cjs/storage/cloud-outbox.js +646 -0
- package/dist-cjs/storage/cloud.js +29 -0
- package/dist-cjs/storage/node-jsonl.js +246 -3
- package/dist-cjs/storage/node-sqlite.js +70 -19
- package/dist-cjs/storage/react-native-jsonl.js +207 -0
- package/package.json +1 -1
|
@@ -0,0 +1,628 @@
|
|
|
1
|
+
import { resolveAmarsiaEndpoint } from "../amarsia/endpoint.js";
|
|
2
|
+
import { OrchaError } from "../errors.js";
|
|
3
|
+
const MAX_CONCURRENT_SESSIONS = 4;
|
|
4
|
+
const MAX_BATCH_EVENTS = 100;
|
|
5
|
+
const FETCH_TIMEOUT_MS = 10_000;
|
|
6
|
+
const RETRY_BASE_MS = 250;
|
|
7
|
+
const RETRY_MAX_MS = 30_000;
|
|
8
|
+
const RECOVERY_ATTEMPTS = 4;
|
|
9
|
+
class RemoteUnavailableError extends Error {
|
|
10
|
+
}
|
|
11
|
+
class RemoteConflictError extends Error {
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* A durable local-first outbox. Local appends never wait for cloud I/O; the
|
|
15
|
+
* persisted acknowledgement lets a new process recover unsent session tails.
|
|
16
|
+
*/
|
|
17
|
+
export class CloudSessionStore {
|
|
18
|
+
#local;
|
|
19
|
+
#key;
|
|
20
|
+
#endpoint;
|
|
21
|
+
#agentName;
|
|
22
|
+
#targets = new Map();
|
|
23
|
+
#running = new Set();
|
|
24
|
+
#tasks = new Map();
|
|
25
|
+
#parked = new Set();
|
|
26
|
+
#attempts = new Map();
|
|
27
|
+
#retryTimers = new Map();
|
|
28
|
+
#memoryAcknowledgements = new Map();
|
|
29
|
+
#stateWaiters = new Set();
|
|
30
|
+
#fetchControllers = new Set();
|
|
31
|
+
#localMutations = new Map();
|
|
32
|
+
#recoveryFailures = new Set();
|
|
33
|
+
#lastError;
|
|
34
|
+
#recoveryDiscoveryFailed = false;
|
|
35
|
+
#closing = false;
|
|
36
|
+
#closed = false;
|
|
37
|
+
#closePromise;
|
|
38
|
+
#recovery;
|
|
39
|
+
constructor(options) {
|
|
40
|
+
if (!options.key.trim()) {
|
|
41
|
+
throw storageError('Storage strategy "cloud" requires a non-empty amarsia.key.');
|
|
42
|
+
}
|
|
43
|
+
this.#local = options.local;
|
|
44
|
+
this.#key = options.key;
|
|
45
|
+
this.#endpoint = resolveAmarsiaEndpoint(options.endpoint);
|
|
46
|
+
this.#agentName = options.agentName;
|
|
47
|
+
this.#recovery = Promise.resolve()
|
|
48
|
+
.then(() => this.#retryRecovery(() => this.#recover()))
|
|
49
|
+
.catch((error) => {
|
|
50
|
+
this.#recoveryDiscoveryFailed = true;
|
|
51
|
+
this.#recordError(error);
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
get cloudStoragePendingCount() {
|
|
55
|
+
return this.#targets.size;
|
|
56
|
+
}
|
|
57
|
+
get cloudStorageLastError() {
|
|
58
|
+
return this.#lastError;
|
|
59
|
+
}
|
|
60
|
+
async read(sessionId) {
|
|
61
|
+
return this.#local.read(sessionId);
|
|
62
|
+
}
|
|
63
|
+
async append(sessionId, events) {
|
|
64
|
+
if (events.length === 0)
|
|
65
|
+
return;
|
|
66
|
+
if (this.#closing || this.#closed) {
|
|
67
|
+
throw storageError("Cloud session storage is closing or closed.");
|
|
68
|
+
}
|
|
69
|
+
await this.#mutateLocal(sessionId, () => this.#local.append(sessionId, events));
|
|
70
|
+
this.#queue(sessionId, lastSequence(events));
|
|
71
|
+
}
|
|
72
|
+
async refreshCloudSession(sessionId) {
|
|
73
|
+
if (this.#closing || this.#closed) {
|
|
74
|
+
throw storageError("Cloud session storage is closing or closed.");
|
|
75
|
+
}
|
|
76
|
+
const local = await this.#local.read(sessionId);
|
|
77
|
+
if (local.length === 0) {
|
|
78
|
+
const remote = await this.#readRemoteTail(sessionId, 0);
|
|
79
|
+
if (this.#closing || this.#closed || remote.events.length === 0)
|
|
80
|
+
return;
|
|
81
|
+
await this.#mutateLocal(sessionId, async () => {
|
|
82
|
+
if ((await this.#local.read(sessionId)).length > 0)
|
|
83
|
+
return;
|
|
84
|
+
await this.#local.append(sessionId, remote.events);
|
|
85
|
+
await this.#setAcknowledgement(sessionId, remote.latestSequence);
|
|
86
|
+
});
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
await this.#refreshWarmSession(sessionId, lastSequence(local));
|
|
90
|
+
}
|
|
91
|
+
async listSessionIds() {
|
|
92
|
+
return this.#local.listSessionIds();
|
|
93
|
+
}
|
|
94
|
+
subscribe(sessionId, listener) {
|
|
95
|
+
return this.#local.subscribe?.(sessionId, listener) ?? (() => { });
|
|
96
|
+
}
|
|
97
|
+
subscribeAll(listener) {
|
|
98
|
+
return this.#local.subscribeAll?.(listener) ?? (() => { });
|
|
99
|
+
}
|
|
100
|
+
async describeLocation(sessionId) {
|
|
101
|
+
return ((await this.#local.describeLocation?.(sessionId)) ??
|
|
102
|
+
`amarsia://${encodeURIComponent(this.#agentName)}/${sessionId}`);
|
|
103
|
+
}
|
|
104
|
+
async flushCloudStorage(options = {}) {
|
|
105
|
+
if (this.#closed)
|
|
106
|
+
throw storageError("Cloud session storage is closed.");
|
|
107
|
+
const timeoutMs = Math.max(0, options.timeoutMs ?? 2_000);
|
|
108
|
+
const deadline = Date.now() + timeoutMs;
|
|
109
|
+
if (!(await this.#waitWithin(this.#recovery, deadline))) {
|
|
110
|
+
throw incompleteFlushError(this.#targets.size, this.#lastError);
|
|
111
|
+
}
|
|
112
|
+
if (this.#recoveryDiscoveryFailed ||
|
|
113
|
+
this.#recoveryFailures.size > 0) {
|
|
114
|
+
let recovered = false;
|
|
115
|
+
try {
|
|
116
|
+
recovered = await this.#waitWithin(this.#retryRecovery(() => this.#recover()), deadline);
|
|
117
|
+
}
|
|
118
|
+
catch (error) {
|
|
119
|
+
this.#recoveryDiscoveryFailed = true;
|
|
120
|
+
this.#recordError(error);
|
|
121
|
+
}
|
|
122
|
+
if (!recovered ||
|
|
123
|
+
this.#recoveryDiscoveryFailed ||
|
|
124
|
+
this.#recoveryFailures.size > 0) {
|
|
125
|
+
throw incompleteFlushError(this.#targets.size + this.#recoveryFailures.size, this.#lastError);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
this.#retryTimers.forEach((timer, sessionId) => {
|
|
129
|
+
clearTimeout(timer);
|
|
130
|
+
this.#retryTimers.delete(sessionId);
|
|
131
|
+
});
|
|
132
|
+
this.#parked.clear();
|
|
133
|
+
this.#schedule();
|
|
134
|
+
while (this.#targets.size > 0 || this.#running.size > 0) {
|
|
135
|
+
if (this.#running.size === 0 &&
|
|
136
|
+
this.#retryTimers.size === 0 &&
|
|
137
|
+
[...this.#targets.keys()].every((sessionId) => this.#parked.has(sessionId))) {
|
|
138
|
+
throw incompleteFlushError(this.#targets.size, this.#lastError);
|
|
139
|
+
}
|
|
140
|
+
if (Date.now() >= deadline) {
|
|
141
|
+
throw incompleteFlushError(this.#targets.size, this.#lastError);
|
|
142
|
+
}
|
|
143
|
+
await this.#waitForState(deadline);
|
|
144
|
+
this.#schedule();
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
async closeCloudStorage(options = {}) {
|
|
148
|
+
if (this.#closed)
|
|
149
|
+
return;
|
|
150
|
+
if (this.#closePromise)
|
|
151
|
+
return this.#closePromise;
|
|
152
|
+
this.#closing = true;
|
|
153
|
+
const close = this.#performClose(options);
|
|
154
|
+
this.#closePromise = close;
|
|
155
|
+
return close;
|
|
156
|
+
}
|
|
157
|
+
async #performClose(options) {
|
|
158
|
+
let flushError;
|
|
159
|
+
try {
|
|
160
|
+
await this.#awaitLocalMutations();
|
|
161
|
+
try {
|
|
162
|
+
await this.#recover();
|
|
163
|
+
}
|
|
164
|
+
catch (error) {
|
|
165
|
+
this.#recoveryDiscoveryFailed = true;
|
|
166
|
+
this.#recordError(error);
|
|
167
|
+
}
|
|
168
|
+
await this.flushCloudStorage(options);
|
|
169
|
+
}
|
|
170
|
+
catch (error) {
|
|
171
|
+
flushError = error;
|
|
172
|
+
}
|
|
173
|
+
finally {
|
|
174
|
+
this.#closed = true;
|
|
175
|
+
for (const timer of this.#retryTimers.values())
|
|
176
|
+
clearTimeout(timer);
|
|
177
|
+
this.#retryTimers.clear();
|
|
178
|
+
for (const controller of this.#fetchControllers)
|
|
179
|
+
controller.abort();
|
|
180
|
+
this.#signalState();
|
|
181
|
+
await Promise.allSettled([
|
|
182
|
+
...this.#tasks.values(),
|
|
183
|
+
]);
|
|
184
|
+
}
|
|
185
|
+
if (flushError !== undefined)
|
|
186
|
+
throw flushError;
|
|
187
|
+
}
|
|
188
|
+
async #awaitLocalMutations() {
|
|
189
|
+
while (this.#localMutations.size > 0) {
|
|
190
|
+
await Promise.allSettled([...this.#localMutations.values()]);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
async #recover() {
|
|
194
|
+
const sessionIds = await this.#local.listSessionIds();
|
|
195
|
+
this.#recoveryDiscoveryFailed = false;
|
|
196
|
+
let cursor = 0;
|
|
197
|
+
const workers = Array.from({ length: Math.min(MAX_CONCURRENT_SESSIONS, sessionIds.length) }, async () => {
|
|
198
|
+
while (cursor < sessionIds.length) {
|
|
199
|
+
const sessionId = sessionIds[cursor++];
|
|
200
|
+
try {
|
|
201
|
+
await this.#retryRecovery(async () => {
|
|
202
|
+
const acknowledged = await this.#getAcknowledgement(sessionId);
|
|
203
|
+
let localSequence = acknowledged;
|
|
204
|
+
for (;;) {
|
|
205
|
+
const events = await this.#readLocalTail(sessionId, localSequence, MAX_BATCH_EVENTS);
|
|
206
|
+
if (events.length === 0)
|
|
207
|
+
break;
|
|
208
|
+
localSequence = lastSequence(events);
|
|
209
|
+
}
|
|
210
|
+
if (localSequence > acknowledged) {
|
|
211
|
+
this.#queue(sessionId, localSequence);
|
|
212
|
+
}
|
|
213
|
+
});
|
|
214
|
+
this.#recoveryFailures.delete(sessionId);
|
|
215
|
+
}
|
|
216
|
+
catch (error) {
|
|
217
|
+
this.#recoveryFailures.add(sessionId);
|
|
218
|
+
this.#recordError(error);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
});
|
|
222
|
+
await Promise.all(workers);
|
|
223
|
+
}
|
|
224
|
+
#queue(sessionId, target) {
|
|
225
|
+
if (target <= 0 || this.#closed)
|
|
226
|
+
return;
|
|
227
|
+
this.#recoveryFailures.delete(sessionId);
|
|
228
|
+
this.#parked.delete(sessionId);
|
|
229
|
+
this.#attempts.delete(sessionId);
|
|
230
|
+
this.#targets.set(sessionId, Math.max(target, this.#targets.get(sessionId) ?? 0));
|
|
231
|
+
this.#signalState();
|
|
232
|
+
this.#schedule();
|
|
233
|
+
}
|
|
234
|
+
#schedule() {
|
|
235
|
+
if (this.#closed)
|
|
236
|
+
return;
|
|
237
|
+
for (const sessionId of this.#targets.keys()) {
|
|
238
|
+
if (this.#running.size >= MAX_CONCURRENT_SESSIONS)
|
|
239
|
+
break;
|
|
240
|
+
if (this.#running.has(sessionId) ||
|
|
241
|
+
this.#parked.has(sessionId) ||
|
|
242
|
+
this.#retryTimers.has(sessionId)) {
|
|
243
|
+
continue;
|
|
244
|
+
}
|
|
245
|
+
this.#running.add(sessionId);
|
|
246
|
+
const task = this.#deliver(sessionId).finally(() => {
|
|
247
|
+
this.#running.delete(sessionId);
|
|
248
|
+
this.#tasks.delete(sessionId);
|
|
249
|
+
this.#signalState();
|
|
250
|
+
this.#schedule();
|
|
251
|
+
});
|
|
252
|
+
this.#tasks.set(sessionId, task);
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
async #deliver(sessionId) {
|
|
256
|
+
let attemptedTarget = 0;
|
|
257
|
+
try {
|
|
258
|
+
while (!this.#closed) {
|
|
259
|
+
const target = this.#targets.get(sessionId);
|
|
260
|
+
if (target === undefined)
|
|
261
|
+
return;
|
|
262
|
+
attemptedTarget = target;
|
|
263
|
+
const acknowledged = await this.#getAcknowledgement(sessionId);
|
|
264
|
+
const events = await this.#readLocalTail(sessionId, acknowledged, MAX_BATCH_EVENTS);
|
|
265
|
+
if (events.length === 0) {
|
|
266
|
+
if ((this.#targets.get(sessionId) ?? 0) <= acknowledged) {
|
|
267
|
+
this.#targets.delete(sessionId);
|
|
268
|
+
}
|
|
269
|
+
else {
|
|
270
|
+
throw storageError(`Local session "${sessionId}" is missing events after sequence ${acknowledged}.`);
|
|
271
|
+
}
|
|
272
|
+
return;
|
|
273
|
+
}
|
|
274
|
+
assertContiguous(events, acknowledged, sessionId);
|
|
275
|
+
try {
|
|
276
|
+
await this.#appendRemote(sessionId, acknowledged, events);
|
|
277
|
+
await this.#setAcknowledgement(sessionId, lastSequence(events));
|
|
278
|
+
}
|
|
279
|
+
catch (error) {
|
|
280
|
+
if (!(error instanceof RemoteConflictError))
|
|
281
|
+
throw error;
|
|
282
|
+
await this.#reconcileConflict(sessionId, acknowledged);
|
|
283
|
+
}
|
|
284
|
+
this.#attempts.delete(sessionId);
|
|
285
|
+
this.#lastError = undefined;
|
|
286
|
+
const delivered = await this.#getAcknowledgement(sessionId);
|
|
287
|
+
if ((this.#targets.get(sessionId) ?? 0) <= delivered) {
|
|
288
|
+
this.#targets.delete(sessionId);
|
|
289
|
+
this.#signalState();
|
|
290
|
+
return;
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
catch (error) {
|
|
295
|
+
this.#recordError(error);
|
|
296
|
+
if (error instanceof RemoteUnavailableError) {
|
|
297
|
+
this.#scheduleRetry(sessionId);
|
|
298
|
+
}
|
|
299
|
+
else if ((this.#targets.get(sessionId) ?? 0) <= attemptedTarget) {
|
|
300
|
+
this.#parked.add(sessionId);
|
|
301
|
+
}
|
|
302
|
+
this.#signalState();
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
async #reconcileConflict(sessionId, acknowledged) {
|
|
306
|
+
const remote = await this.#readRemoteTail(sessionId, acknowledged);
|
|
307
|
+
if (remote.latestSequence < acknowledged) {
|
|
308
|
+
throw divergenceError(sessionId, remote.latestSequence + 1);
|
|
309
|
+
}
|
|
310
|
+
if (remote.events.length === 0) {
|
|
311
|
+
throw storageError(`Cloud session "${sessionId}" returned no events for a conflicting append.`);
|
|
312
|
+
}
|
|
313
|
+
await this.#mutateLocal(sessionId, async () => {
|
|
314
|
+
const local = await this.#readLocalTail(sessionId, acknowledged, remote.events.length + 1);
|
|
315
|
+
const sharedLength = Math.min(local.length, remote.events.length);
|
|
316
|
+
for (let index = 0; index < sharedLength; index += 1) {
|
|
317
|
+
const localEvent = local[index];
|
|
318
|
+
const remoteEvent = remote.events[index];
|
|
319
|
+
if (!localEvent || !remoteEvent || !eventsEqual(localEvent, remoteEvent)) {
|
|
320
|
+
throw divergenceError(sessionId, remoteEvent?.sequence ?? localEvent?.sequence ?? acknowledged + index + 1);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
if (remote.events.length > local.length) {
|
|
324
|
+
await this.#local.append(sessionId, remote.events.slice(local.length));
|
|
325
|
+
}
|
|
326
|
+
await this.#setAcknowledgement(sessionId, remote.latestSequence);
|
|
327
|
+
});
|
|
328
|
+
}
|
|
329
|
+
#scheduleRetry(sessionId) {
|
|
330
|
+
if (this.#closed ||
|
|
331
|
+
this.#parked.has(sessionId) ||
|
|
332
|
+
this.#retryTimers.has(sessionId)) {
|
|
333
|
+
return;
|
|
334
|
+
}
|
|
335
|
+
const attempt = (this.#attempts.get(sessionId) ?? 0) + 1;
|
|
336
|
+
this.#attempts.set(sessionId, attempt);
|
|
337
|
+
const ceiling = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** (attempt - 1));
|
|
338
|
+
const delay = Math.floor(Math.random() * ceiling);
|
|
339
|
+
const timer = setTimeout(() => {
|
|
340
|
+
this.#retryTimers.delete(sessionId);
|
|
341
|
+
this.#signalState();
|
|
342
|
+
this.#schedule();
|
|
343
|
+
}, delay);
|
|
344
|
+
timer.unref?.();
|
|
345
|
+
this.#retryTimers.set(sessionId, timer);
|
|
346
|
+
}
|
|
347
|
+
async #refreshWarmSession(sessionId, localSequence) {
|
|
348
|
+
const acknowledged = await this.#getAcknowledgement(sessionId);
|
|
349
|
+
if (acknowledged !== localSequence ||
|
|
350
|
+
this.#closing ||
|
|
351
|
+
this.#closed) {
|
|
352
|
+
return;
|
|
353
|
+
}
|
|
354
|
+
const remote = await this.#readRemoteTail(sessionId, localSequence);
|
|
355
|
+
if (remote.events.length === 0 ||
|
|
356
|
+
this.#closing ||
|
|
357
|
+
this.#closed) {
|
|
358
|
+
return;
|
|
359
|
+
}
|
|
360
|
+
await this.#mutateLocal(sessionId, async () => {
|
|
361
|
+
const appended = await this.#readLocalTail(sessionId, localSequence, 1);
|
|
362
|
+
const currentAcknowledgement = await this.#getAcknowledgement(sessionId);
|
|
363
|
+
if (appended.length > 0 || currentAcknowledgement !== localSequence) {
|
|
364
|
+
return;
|
|
365
|
+
}
|
|
366
|
+
await this.#local.append(sessionId, remote.events);
|
|
367
|
+
await this.#setAcknowledgement(sessionId, remote.latestSequence);
|
|
368
|
+
});
|
|
369
|
+
}
|
|
370
|
+
async #readLocalTail(sessionId, afterSequence, limit) {
|
|
371
|
+
if (this.#local.readAfterSequence) {
|
|
372
|
+
return this.#local.readAfterSequence(sessionId, afterSequence, limit);
|
|
373
|
+
}
|
|
374
|
+
return (await this.#local.read(sessionId))
|
|
375
|
+
.filter((event) => event.sequence > afterSequence)
|
|
376
|
+
.slice(0, limit);
|
|
377
|
+
}
|
|
378
|
+
async #mutateLocal(sessionId, operation) {
|
|
379
|
+
const previous = this.#localMutations.get(sessionId) ?? Promise.resolve();
|
|
380
|
+
const mutation = previous.then(operation);
|
|
381
|
+
this.#localMutations.set(sessionId, mutation);
|
|
382
|
+
try {
|
|
383
|
+
await mutation;
|
|
384
|
+
}
|
|
385
|
+
finally {
|
|
386
|
+
if (this.#localMutations.get(sessionId) === mutation) {
|
|
387
|
+
this.#localMutations.delete(sessionId);
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
async #retryRecovery(operation) {
|
|
392
|
+
let lastError;
|
|
393
|
+
for (let attempt = 0; attempt < RECOVERY_ATTEMPTS; attempt += 1) {
|
|
394
|
+
try {
|
|
395
|
+
await operation();
|
|
396
|
+
return;
|
|
397
|
+
}
|
|
398
|
+
catch (error) {
|
|
399
|
+
lastError = error;
|
|
400
|
+
if (attempt + 1 < RECOVERY_ATTEMPTS) {
|
|
401
|
+
const ceiling = RETRY_BASE_MS * 2 ** attempt;
|
|
402
|
+
await delay(Math.floor(Math.random() * ceiling));
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
throw lastError;
|
|
407
|
+
}
|
|
408
|
+
async #getAcknowledgement(sessionId) {
|
|
409
|
+
return ((await this.#local.getCloudAcknowledgement?.(sessionId)) ??
|
|
410
|
+
this.#memoryAcknowledgements.get(sessionId) ??
|
|
411
|
+
0);
|
|
412
|
+
}
|
|
413
|
+
async #setAcknowledgement(sessionId, sequence) {
|
|
414
|
+
if (this.#local.setCloudAcknowledgement) {
|
|
415
|
+
await this.#local.setCloudAcknowledgement(sessionId, sequence);
|
|
416
|
+
}
|
|
417
|
+
else {
|
|
418
|
+
this.#memoryAcknowledgements.set(sessionId, Math.max(sequence, this.#memoryAcknowledgements.get(sessionId) ?? 0));
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
async #readRemoteTail(sessionId, afterSequence) {
|
|
422
|
+
const first = await this.#readRemoteEvents(sessionId, afterSequence);
|
|
423
|
+
const events = [...first.events];
|
|
424
|
+
let receivedThrough = events.at(-1)?.sequence ?? afterSequence;
|
|
425
|
+
while (receivedThrough < first.latestSequence) {
|
|
426
|
+
const next = await this.#readRemoteEvents(sessionId, receivedThrough);
|
|
427
|
+
if (next.latestSequence < receivedThrough || next.events.length === 0) {
|
|
428
|
+
throw storageError(`Cloud session "${sessionId}" returned an incomplete remote tail.`);
|
|
429
|
+
}
|
|
430
|
+
events.push(...next.events);
|
|
431
|
+
receivedThrough = events.at(-1)?.sequence ?? receivedThrough;
|
|
432
|
+
}
|
|
433
|
+
return { events, latestSequence: Math.max(first.latestSequence, receivedThrough) };
|
|
434
|
+
}
|
|
435
|
+
async #readRemoteEvents(sessionId, afterSequence) {
|
|
436
|
+
const url = new URL(`${this.#endpoint}/v3/session-storage/sessions/${encodeURIComponent(sessionId)}/events`);
|
|
437
|
+
url.searchParams.set("agent_name", this.#agentName);
|
|
438
|
+
url.searchParams.set("after_sequence", String(afterSequence));
|
|
439
|
+
url.searchParams.set("limit", String(MAX_BATCH_EVENTS));
|
|
440
|
+
const body = await this.#request(url);
|
|
441
|
+
if (!isRecord(body) ||
|
|
442
|
+
!Array.isArray(body.events) ||
|
|
443
|
+
!Number.isInteger(body.latest_sequence) ||
|
|
444
|
+
body.latest_sequence < 0) {
|
|
445
|
+
throw storageError("Amarsia returned an invalid session event response.");
|
|
446
|
+
}
|
|
447
|
+
const events = body.events.map((event) => validateEvent(event, sessionId));
|
|
448
|
+
let expected = afterSequence + 1;
|
|
449
|
+
for (const event of events) {
|
|
450
|
+
if (event.sequence !== expected)
|
|
451
|
+
throw divergenceError(sessionId, expected);
|
|
452
|
+
expected += 1;
|
|
453
|
+
}
|
|
454
|
+
if (events.length > MAX_BATCH_EVENTS) {
|
|
455
|
+
throw storageError("Amarsia returned an oversized session event page.");
|
|
456
|
+
}
|
|
457
|
+
if (lastSequence(events) > body.latest_sequence) {
|
|
458
|
+
throw storageError("Amarsia returned an invalid latest session sequence.");
|
|
459
|
+
}
|
|
460
|
+
return { events, latestSequence: body.latest_sequence };
|
|
461
|
+
}
|
|
462
|
+
async #appendRemote(sessionId, expectedSequence, events) {
|
|
463
|
+
if (events.length === 0 || events.length > MAX_BATCH_EVENTS) {
|
|
464
|
+
throw storageError(`Cloud session upload batches must contain 1-${MAX_BATCH_EVENTS} events.`);
|
|
465
|
+
}
|
|
466
|
+
const url = new URL(`${this.#endpoint}/v3/session-storage/sessions/${encodeURIComponent(sessionId)}/events`);
|
|
467
|
+
const response = await this.#fetch(url, {
|
|
468
|
+
method: "POST",
|
|
469
|
+
headers: {
|
|
470
|
+
"content-type": "application/json",
|
|
471
|
+
"x-amarsia-project-key": this.#key,
|
|
472
|
+
},
|
|
473
|
+
body: JSON.stringify({
|
|
474
|
+
agent_name: this.#agentName,
|
|
475
|
+
expected_sequence: expectedSequence,
|
|
476
|
+
events,
|
|
477
|
+
}),
|
|
478
|
+
});
|
|
479
|
+
await assertSuccessfulResponse(response);
|
|
480
|
+
}
|
|
481
|
+
async #request(url) {
|
|
482
|
+
const response = await this.#fetch(url, {
|
|
483
|
+
headers: { "x-amarsia-project-key": this.#key },
|
|
484
|
+
});
|
|
485
|
+
await assertSuccessfulResponse(response);
|
|
486
|
+
try {
|
|
487
|
+
return await response.json();
|
|
488
|
+
}
|
|
489
|
+
catch (error) {
|
|
490
|
+
throw storageError("Amarsia returned invalid session storage JSON.", undefined, error);
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
async #fetch(input, init) {
|
|
494
|
+
const controller = new AbortController();
|
|
495
|
+
this.#fetchControllers.add(controller);
|
|
496
|
+
const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
|
|
497
|
+
try {
|
|
498
|
+
return await fetch(input, { ...init, signal: controller.signal });
|
|
499
|
+
}
|
|
500
|
+
catch (error) {
|
|
501
|
+
throw new RemoteUnavailableError(`Amarsia session storage is unavailable: ${String(error)}`);
|
|
502
|
+
}
|
|
503
|
+
finally {
|
|
504
|
+
clearTimeout(timer);
|
|
505
|
+
this.#fetchControllers.delete(controller);
|
|
506
|
+
}
|
|
507
|
+
}
|
|
508
|
+
#recordError(error) {
|
|
509
|
+
this.#lastError =
|
|
510
|
+
error instanceof Error ? error : new Error(String(error));
|
|
511
|
+
this.#signalState();
|
|
512
|
+
}
|
|
513
|
+
#signalState() {
|
|
514
|
+
for (const resolve of this.#stateWaiters)
|
|
515
|
+
resolve();
|
|
516
|
+
this.#stateWaiters.clear();
|
|
517
|
+
}
|
|
518
|
+
async #waitForState(deadline) {
|
|
519
|
+
const remaining = Math.max(0, deadline - Date.now());
|
|
520
|
+
await new Promise((resolve) => {
|
|
521
|
+
const timer = setTimeout(() => {
|
|
522
|
+
this.#stateWaiters.delete(done);
|
|
523
|
+
resolve();
|
|
524
|
+
}, remaining);
|
|
525
|
+
const done = () => {
|
|
526
|
+
clearTimeout(timer);
|
|
527
|
+
resolve();
|
|
528
|
+
};
|
|
529
|
+
this.#stateWaiters.add(done);
|
|
530
|
+
});
|
|
531
|
+
}
|
|
532
|
+
async #waitWithin(operation, deadline) {
|
|
533
|
+
const remaining = Math.max(0, deadline - Date.now());
|
|
534
|
+
return Promise.race([
|
|
535
|
+
operation.then(() => true),
|
|
536
|
+
new Promise((resolve) => setTimeout(() => resolve(false), remaining)),
|
|
537
|
+
]);
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
function validateEvent(event, sessionId) {
|
|
541
|
+
if (!isRecord(event) ||
|
|
542
|
+
!Number.isInteger(event.sequence) ||
|
|
543
|
+
typeof event.type !== "string" ||
|
|
544
|
+
typeof event.timestamp !== "string" ||
|
|
545
|
+
!isRecord(event.data)) {
|
|
546
|
+
throw storageError(`Amarsia returned an invalid event for session "${sessionId}".`);
|
|
547
|
+
}
|
|
548
|
+
return event;
|
|
549
|
+
}
|
|
550
|
+
function lastSequence(events) {
|
|
551
|
+
return events.at(-1)?.sequence ?? 0;
|
|
552
|
+
}
|
|
553
|
+
function assertContiguous(events, afterSequence, sessionId) {
|
|
554
|
+
let expected = afterSequence + 1;
|
|
555
|
+
for (const event of events) {
|
|
556
|
+
if (event.sequence !== expected) {
|
|
557
|
+
throw storageError(`Local session "${sessionId}" is missing event sequence ${expected}.`);
|
|
558
|
+
}
|
|
559
|
+
expected += 1;
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
function eventsEqual(left, right) {
|
|
563
|
+
return canonicalJson(left) === canonicalJson(right);
|
|
564
|
+
}
|
|
565
|
+
function canonicalJson(value) {
|
|
566
|
+
return JSON.stringify(sortJson(value));
|
|
567
|
+
}
|
|
568
|
+
function sortJson(value) {
|
|
569
|
+
if (Array.isArray(value))
|
|
570
|
+
return value.map(sortJson);
|
|
571
|
+
if (isRecord(value)) {
|
|
572
|
+
return Object.fromEntries(Object.keys(value)
|
|
573
|
+
.sort()
|
|
574
|
+
.map((key) => [key, sortJson(value[key])]));
|
|
575
|
+
}
|
|
576
|
+
return value;
|
|
577
|
+
}
|
|
578
|
+
function divergenceError(sessionId, sequence) {
|
|
579
|
+
return new OrchaError("storage_error", `Cloud session "${sessionId}" diverged at sequence ${sequence}; local events were preserved and remote events were not overwritten.`, { details: { sessionId, sequence, conflict: "immutable_prefix" } });
|
|
580
|
+
}
|
|
581
|
+
async function assertSuccessfulResponse(response) {
|
|
582
|
+
if (response.ok)
|
|
583
|
+
return;
|
|
584
|
+
if (response.status === 409)
|
|
585
|
+
throw new RemoteConflictError();
|
|
586
|
+
if (response.status === 408 ||
|
|
587
|
+
response.status === 429 ||
|
|
588
|
+
response.status >= 500) {
|
|
589
|
+
throw new RemoteUnavailableError(`Amarsia session storage is temporarily unavailable (HTTP ${response.status}).`);
|
|
590
|
+
}
|
|
591
|
+
const serverMessage = await readSafeServerMessage(response);
|
|
592
|
+
throw storageError(`Amarsia session storage request failed with HTTP ${response.status}${serverMessage ? `: ${serverMessage}` : "."}`, { status: response.status });
|
|
593
|
+
}
|
|
594
|
+
async function readSafeServerMessage(response) {
|
|
595
|
+
try {
|
|
596
|
+
const body = await response.json();
|
|
597
|
+
const value = isRecord(body) && isRecord(body.error)
|
|
598
|
+
? body.error.message
|
|
599
|
+
: isRecord(body)
|
|
600
|
+
? body.message
|
|
601
|
+
: undefined;
|
|
602
|
+
if (typeof value !== "string")
|
|
603
|
+
return undefined;
|
|
604
|
+
const sanitized = value
|
|
605
|
+
.replace(/[\u0000-\u001f\u007f]/g, " ")
|
|
606
|
+
.replace(/\s+/g, " ")
|
|
607
|
+
.trim();
|
|
608
|
+
return sanitized ? sanitized.slice(0, 500) : undefined;
|
|
609
|
+
}
|
|
610
|
+
catch {
|
|
611
|
+
return undefined;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
function storageError(message, details, cause) {
|
|
615
|
+
return new OrchaError("storage_error", message, {
|
|
616
|
+
...(details ? { details } : {}),
|
|
617
|
+
...(cause === undefined ? {} : { cause }),
|
|
618
|
+
});
|
|
619
|
+
}
|
|
620
|
+
function incompleteFlushError(pendingCount, cause) {
|
|
621
|
+
return storageError(`Cloud storage flush incomplete; ${pendingCount} session(s) remain pending.`, { pendingCount }, cause);
|
|
622
|
+
}
|
|
623
|
+
function delay(milliseconds) {
|
|
624
|
+
return new Promise((resolve) => setTimeout(resolve, milliseconds));
|
|
625
|
+
}
|
|
626
|
+
function isRecord(value) {
|
|
627
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
628
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { CloudSessionStore, type CloudSessionStoreOptions, } from "./cloud-outbox.js";
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { CloudSessionStore, } from "./cloud-outbox.js";
|
|
@@ -4,8 +4,11 @@ export declare class NodeJsonlSessionStore implements SessionStore {
|
|
|
4
4
|
readonly directory: string;
|
|
5
5
|
constructor(directory?: string, projectRoot?: string, agent?: string);
|
|
6
6
|
read(sessionId: string): Promise<SessionEvent[]>;
|
|
7
|
+
readAfterSequence(sessionId: string, afterSequence: number, limit: number): Promise<SessionEvent[]>;
|
|
7
8
|
append(sessionId: string, events: SessionEvent[]): Promise<void>;
|
|
8
9
|
listSessionIds(): Promise<string[]>;
|
|
10
|
+
getCloudAcknowledgement(sessionId: string): Promise<number>;
|
|
11
|
+
setCloudAcknowledgement(sessionId: string, sequence: number): Promise<void>;
|
|
9
12
|
describeLocation(sessionId: string): Promise<string>;
|
|
10
13
|
subscribe(sessionId: string, listener: (events: SessionEvent[]) => void): () => void;
|
|
11
14
|
subscribeAll(listener: (sessionId: string, events: SessionEvent[]) => void): () => void;
|