orchajs 0.24.0 → 0.26.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.
Files changed (78) hide show
  1. package/README.md +50 -3
  2. package/dist/amarsia/analytics.js +12 -0
  3. package/dist/amarsia/inference.d.ts +6 -0
  4. package/dist/amarsia/inference.js +377 -0
  5. package/dist/browser.js +5 -0
  6. package/dist/cli-agents-template.d.ts +1 -1
  7. package/dist/cli-agents-template.js +44 -11
  8. package/dist/cli.js +22 -9
  9. package/dist/compiler/build-project.js +57 -14
  10. package/dist/compiler/node-esm-banner.d.ts +2 -0
  11. package/dist/compiler/node-esm-banner.js +5 -0
  12. package/dist/orcha.js +5 -0
  13. package/dist/playground/server.js +3 -0
  14. package/dist/project-loader.js +4 -2
  15. package/dist/providers/anthropic.js +67 -58
  16. package/dist/providers/bedrock.js +14 -8
  17. package/dist/providers/deepseek.js +9 -2
  18. package/dist/providers/google-gemini.js +20 -15
  19. package/dist/providers/openai.js +6 -0
  20. package/dist/providers/types.d.ts +5 -0
  21. package/dist/react-native.js +5 -0
  22. package/dist/runtime/agent.d.ts +3 -3
  23. package/dist/runtime/agent.js +278 -45
  24. package/dist/runtime/compiler-hook.d.ts +4 -0
  25. package/dist/runtime/compiler-hook.js +9 -0
  26. package/dist/runtime/create-orcha.d.ts +19 -0
  27. package/dist/runtime/create-orcha.js +109 -12
  28. package/dist/runtime/optional-features.d.ts +19 -0
  29. package/dist/runtime/optional-features.js +22 -0
  30. package/dist/runtime/platform-browser.js +16 -3
  31. package/dist/runtime/platform-node.js +16 -2
  32. package/dist/runtime/platform-react-native.js +16 -3
  33. package/dist/runtime/session-events.js +19 -0
  34. package/dist/storage/browser-indexeddb.d.ts +3 -0
  35. package/dist/storage/browser-indexeddb.js +72 -8
  36. package/dist/storage/cloud-outbox.d.ts +30 -0
  37. package/dist/storage/cloud-outbox.js +628 -0
  38. package/dist/storage/cloud.d.ts +1 -0
  39. package/dist/storage/cloud.js +1 -0
  40. package/dist/storage/node-jsonl.d.ts +3 -0
  41. package/dist/storage/node-jsonl.js +273 -4
  42. package/dist/storage/node-sqlite.d.ts +3 -0
  43. package/dist/storage/node-sqlite.js +66 -17
  44. package/dist/storage/react-native-jsonl.d.ts +3 -0
  45. package/dist/storage/react-native-jsonl.js +223 -0
  46. package/dist/testing.js +3 -0
  47. package/dist/types.d.ts +25 -4
  48. package/dist-cjs/amarsia/analytics.js +12 -0
  49. package/dist-cjs/amarsia/inference.js +372 -0
  50. package/dist-cjs/browser.js +5 -0
  51. package/dist-cjs/cli-agents-template.js +44 -11
  52. package/dist-cjs/compiler/build-project.js +68 -4
  53. package/dist-cjs/compiler/node-esm-banner.js +32 -0
  54. package/dist-cjs/orcha.js +5 -0
  55. package/dist-cjs/playground/server.js +1 -0
  56. package/dist-cjs/project-loader.js +7 -5
  57. package/dist-cjs/providers/anthropic.js +65 -60
  58. package/dist-cjs/providers/bedrock.js +17 -9
  59. package/dist-cjs/providers/deepseek.js +10 -2
  60. package/dist-cjs/providers/google-gemini.js +27 -20
  61. package/dist-cjs/providers/openai.js +8 -0
  62. package/dist-cjs/react-native.js +5 -0
  63. package/dist-cjs/runtime/agent.js +311 -61
  64. package/dist-cjs/runtime/compiler-hook.js +11 -0
  65. package/dist-cjs/runtime/create-orcha.js +117 -12
  66. package/dist-cjs/runtime/optional-features.js +58 -0
  67. package/dist-cjs/runtime/platform-browser.js +16 -3
  68. package/dist-cjs/runtime/platform-node.js +16 -2
  69. package/dist-cjs/runtime/platform-react-native.js +18 -3
  70. package/dist-cjs/runtime/session-events.js +14 -0
  71. package/dist-cjs/storage/browser-indexeddb.js +73 -8
  72. package/dist-cjs/storage/cloud-outbox.js +646 -0
  73. package/dist-cjs/storage/cloud.js +29 -0
  74. package/dist-cjs/storage/node-jsonl.js +246 -3
  75. package/dist-cjs/storage/node-sqlite.js +70 -19
  76. package/dist-cjs/storage/react-native-jsonl.js +207 -0
  77. package/dist-cjs/testing.js +1 -0
  78. package/package.json +1 -1
@@ -1,6 +1,9 @@
1
- import { mkdirSync, watch } from "node:fs";
2
- import { access, appendFile, mkdir, readFile, readdir } from "node:fs/promises";
1
+ import { createReadStream, mkdirSync, watch, } from "node:fs";
2
+ import { access, appendFile, mkdir, readFile, readdir, rename, stat, writeFile, } from "node:fs/promises";
3
3
  import { dirname, resolve } from "node:path";
4
+ import { createInterface } from "node:readline";
5
+ const acknowledgementWrites = new Map();
6
+ const TAIL_INDEX_STRIDE = 100;
4
7
  export class NodeJsonlSessionStore {
5
8
  directory;
6
9
  #legacyDirectory;
@@ -10,6 +13,8 @@ export class NodeJsonlSessionStore {
10
13
  #watchers = [];
11
14
  #watchTimers = new Map();
12
15
  #observedSequences = new Map();
16
+ #tailIndexes = new Map();
17
+ #tailIndexLoads = new Map();
13
18
  constructor(directory = ".orcha/sessions", projectRoot = process.cwd(), agent) {
14
19
  this.#legacyDirectory = resolve(projectRoot, directory);
15
20
  this.directory = resolve(this.#legacyDirectory, agent ? sessionAgentDirectoryName(agent) : "");
@@ -39,6 +44,47 @@ export class NodeJsonlSessionStore {
39
44
  }
40
45
  });
41
46
  }
47
+ async readAfterSequence(sessionId, afterSequence, limit) {
48
+ validateTailArguments(afterSequence, limit);
49
+ const path = await this.#readSessionPath(sessionId);
50
+ if (!path)
51
+ return [];
52
+ const index = await this.#getTailIndex(path, sessionId);
53
+ const start = checkpointOffset(index.checkpoints, afterSequence + 1);
54
+ const events = [];
55
+ const lines = createInterface({
56
+ input: createReadStream(path, { encoding: "utf8", start }),
57
+ crlfDelay: Infinity,
58
+ });
59
+ let lineNumber = 0;
60
+ try {
61
+ for await (const line of lines) {
62
+ lineNumber += 1;
63
+ if (!line)
64
+ continue;
65
+ let event;
66
+ try {
67
+ event = JSON.parse(line);
68
+ }
69
+ catch (error) {
70
+ throw new Error(`Corrupt JSONL event in session "${sessionId}" at line ${lineNumber}.`, { cause: error });
71
+ }
72
+ if (event.sequence > afterSequence)
73
+ events.push(event);
74
+ if (events.length >= limit)
75
+ break;
76
+ }
77
+ return events;
78
+ }
79
+ catch (error) {
80
+ if (isMissingFileError(error))
81
+ return [];
82
+ throw error;
83
+ }
84
+ finally {
85
+ lines.close();
86
+ }
87
+ }
42
88
  async append(sessionId, events) {
43
89
  if (events.length === 0) {
44
90
  return;
@@ -47,8 +93,18 @@ export class NodeJsonlSessionStore {
47
93
  const write = previous.then(async () => {
48
94
  const path = await this.#writeSessionPath(sessionId);
49
95
  await mkdir(dirname(path), { recursive: true });
50
- const lines = `${events.map((event) => JSON.stringify(event)).join("\n")}\n`;
51
- await appendFile(path, lines, "utf8");
96
+ const startOffset = await fileSize(path);
97
+ const serialized = events.map((event) => `${JSON.stringify(event)}\n`);
98
+ await appendFile(path, serialized.join(""), "utf8");
99
+ const checkpoints = [];
100
+ let offset = startOffset;
101
+ for (const [index, event] of events.entries()) {
102
+ if ((event.sequence - 1) % TAIL_INDEX_STRIDE === 0) {
103
+ checkpoints.push({ sequence: event.sequence, offset });
104
+ }
105
+ offset += Buffer.byteLength(serialized[index], "utf8");
106
+ }
107
+ await this.#recordTailIndex(path, startOffset, offset, checkpoints);
52
108
  this.#notify(sessionId, events);
53
109
  });
54
110
  this.#queues.set(sessionId, write);
@@ -83,6 +139,46 @@ export class NodeJsonlSessionStore {
83
139
  }
84
140
  return [...sessionIds].sort();
85
141
  }
142
+ async getCloudAcknowledgement(sessionId) {
143
+ const path = await this.#cloudAcknowledgementPath(sessionId);
144
+ if (!path)
145
+ return 0;
146
+ try {
147
+ const value = Number(await readFile(path, "utf8"));
148
+ return Number.isInteger(value) && value >= 0 ? value : 0;
149
+ }
150
+ catch (error) {
151
+ if (isMissingFileError(error))
152
+ return 0;
153
+ throw error;
154
+ }
155
+ }
156
+ async setCloudAcknowledgement(sessionId, sequence) {
157
+ if (!Number.isInteger(sequence) || sequence < 0) {
158
+ throw new Error("Invalid cloud acknowledgement sequence.");
159
+ }
160
+ const sessionPath = await this.#writeSessionPath(sessionId);
161
+ const path = `${sessionPath}.cloud-ack`;
162
+ const previous = acknowledgementWrites.get(path) ?? Promise.resolve();
163
+ const write = previous.then(async () => {
164
+ const current = await this.getCloudAcknowledgement(sessionId);
165
+ if (sequence <= current)
166
+ return;
167
+ const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
168
+ await mkdir(dirname(path), { recursive: true });
169
+ await writeFile(temporary, String(sequence), "utf8");
170
+ await rename(temporary, path);
171
+ });
172
+ acknowledgementWrites.set(path, write);
173
+ try {
174
+ await write;
175
+ }
176
+ finally {
177
+ if (acknowledgementWrites.get(path) === write) {
178
+ acknowledgementWrites.delete(path);
179
+ }
180
+ }
181
+ }
86
182
  async describeLocation(sessionId) {
87
183
  return ((await this.#readSessionPath(sessionId)) ??
88
184
  this.#sessionPath(this.directory, sessionId));
@@ -201,6 +297,98 @@ export class NodeJsonlSessionStore {
201
297
  return ((await this.#readSessionPath(sessionId)) ??
202
298
  this.#sessionPath(this.directory, sessionId));
203
299
  }
300
+ async #cloudAcknowledgementPath(sessionId) {
301
+ const current = `${this.#sessionPath(this.directory, sessionId)}.cloud-ack`;
302
+ if (await pathExists(current))
303
+ return current;
304
+ const legacy = `${this.#sessionPath(this.#legacyDirectory, sessionId)}.cloud-ack`;
305
+ return await pathExists(legacy) ? legacy : undefined;
306
+ }
307
+ async #getTailIndex(path, sessionId) {
308
+ const size = await fileSize(path);
309
+ const cached = this.#tailIndexes.get(path);
310
+ if (cached?.indexedSize === size)
311
+ return cached;
312
+ const loading = this.#tailIndexLoads.get(path);
313
+ if (loading)
314
+ return loading;
315
+ const load = this.#loadTailIndex(path, sessionId, size);
316
+ this.#tailIndexLoads.set(path, load);
317
+ try {
318
+ const index = await load;
319
+ this.#tailIndexes.set(path, index);
320
+ return index;
321
+ }
322
+ finally {
323
+ if (this.#tailIndexLoads.get(path) === load) {
324
+ this.#tailIndexLoads.delete(path);
325
+ }
326
+ }
327
+ }
328
+ async #loadTailIndex(path, sessionId, size) {
329
+ try {
330
+ const source = await readFile(tailIndexPath(path), "utf8");
331
+ const parsed = parseTailIndex(source);
332
+ if (parsed.indexedSize === size &&
333
+ (size === 0 || parsed.checkpoints[0]?.sequence === 1)) {
334
+ return parsed;
335
+ }
336
+ }
337
+ catch (error) {
338
+ if (!isMissingFileError(error)) {
339
+ this.#tailIndexes.delete(path);
340
+ }
341
+ }
342
+ return this.#rebuildTailIndex(path, sessionId);
343
+ }
344
+ async #rebuildTailIndex(path, sessionId) {
345
+ const source = await readFile(path);
346
+ const checkpoints = [];
347
+ let lineStart = 0;
348
+ let lineNumber = 0;
349
+ for (let cursor = 0; cursor <= source.length; cursor += 1) {
350
+ if (cursor < source.length && source[cursor] !== 0x0a)
351
+ continue;
352
+ const end = cursor > lineStart && source[cursor - 1] === 0x0d
353
+ ? cursor - 1
354
+ : cursor;
355
+ if (end > lineStart) {
356
+ lineNumber += 1;
357
+ let event;
358
+ try {
359
+ event = JSON.parse(source.subarray(lineStart, end).toString("utf8"));
360
+ }
361
+ catch (error) {
362
+ throw new Error(`Corrupt JSONL event in session "${sessionId}" at line ${lineNumber}.`, { cause: error });
363
+ }
364
+ if ((event.sequence - 1) % TAIL_INDEX_STRIDE === 0) {
365
+ checkpoints.push({ sequence: event.sequence, offset: lineStart });
366
+ }
367
+ }
368
+ lineStart = cursor + 1;
369
+ }
370
+ const index = { checkpoints, indexedSize: source.length };
371
+ await persistTailIndex(path, index);
372
+ return index;
373
+ }
374
+ async #recordTailIndex(path, previousSize, indexedSize, checkpoints) {
375
+ const cached = this.#tailIndexes.get(path);
376
+ if (cached?.indexedSize === previousSize) {
377
+ cached.checkpoints.push(...checkpoints);
378
+ cached.indexedSize = indexedSize;
379
+ }
380
+ else {
381
+ this.#tailIndexes.delete(path);
382
+ }
383
+ try {
384
+ await appendFile(tailIndexPath(path), `${checkpoints
385
+ .map(({ sequence, offset }) => `${sequence}\t${offset}\n`)
386
+ .join("")}size\t${indexedSize}\n`, "utf8");
387
+ }
388
+ catch {
389
+ this.#tailIndexes.delete(path);
390
+ }
391
+ }
204
392
  #sessionPath(directory, sessionId) {
205
393
  if (!/^[A-Za-z0-9_:-]+$/.test(sessionId)) {
206
394
  throw new Error("Invalid session ID.");
@@ -234,8 +422,89 @@ async function pathExists(path) {
234
422
  throw error;
235
423
  }
236
424
  }
425
+ async function fileSize(path) {
426
+ try {
427
+ return (await stat(path)).size;
428
+ }
429
+ catch (error) {
430
+ if (isMissingFileError(error))
431
+ return 0;
432
+ throw error;
433
+ }
434
+ }
435
+ function tailIndexPath(path) {
436
+ return `${path}.tail-index`;
437
+ }
438
+ function parseTailIndex(source) {
439
+ const checkpoints = [];
440
+ let indexedSize = -1;
441
+ for (const line of source.split("\n")) {
442
+ if (!line)
443
+ continue;
444
+ const [left, right] = line.split("\t");
445
+ const value = Number(right);
446
+ if (!Number.isSafeInteger(value) || value < 0) {
447
+ throw new Error("Invalid JSONL tail index.");
448
+ }
449
+ if (left === "size") {
450
+ indexedSize = value;
451
+ continue;
452
+ }
453
+ const sequence = Number(left);
454
+ const previous = checkpoints.at(-1);
455
+ if (!Number.isSafeInteger(sequence) ||
456
+ sequence <= 0 ||
457
+ (previous !== undefined &&
458
+ (sequence <= previous.sequence || value <= previous.offset))) {
459
+ throw new Error("Invalid JSONL tail index.");
460
+ }
461
+ checkpoints.push({ sequence, offset: value });
462
+ }
463
+ if (indexedSize < 0)
464
+ throw new Error("Incomplete JSONL tail index.");
465
+ return { checkpoints, indexedSize };
466
+ }
467
+ async function persistTailIndex(path, index) {
468
+ const destination = tailIndexPath(path);
469
+ const temporary = `${destination}.${process.pid}.${Date.now()}.tmp`;
470
+ const source = `${index.checkpoints
471
+ .map(({ sequence, offset }) => `${sequence}\t${offset}\n`)
472
+ .join("")}size\t${index.indexedSize}\n`;
473
+ try {
474
+ await writeFile(temporary, source, "utf8");
475
+ await rename(temporary, destination);
476
+ }
477
+ catch {
478
+ // The index is an optimization and is rebuilt from the canonical JSONL.
479
+ }
480
+ }
481
+ function checkpointOffset(checkpoints, targetSequence) {
482
+ let low = 0;
483
+ let high = checkpoints.length - 1;
484
+ let offset = 0;
485
+ while (low <= high) {
486
+ const middle = Math.floor((low + high) / 2);
487
+ const checkpoint = checkpoints[middle];
488
+ if (checkpoint.sequence <= targetSequence) {
489
+ offset = checkpoint.offset;
490
+ low = middle + 1;
491
+ }
492
+ else {
493
+ high = middle - 1;
494
+ }
495
+ }
496
+ return offset;
497
+ }
237
498
  function isMissingFileError(error) {
238
499
  return (error instanceof Error &&
239
500
  "code" in error &&
240
501
  error.code === "ENOENT");
241
502
  }
503
+ function validateTailArguments(afterSequence, limit) {
504
+ if (!Number.isInteger(afterSequence) ||
505
+ afterSequence < 0 ||
506
+ !Number.isInteger(limit) ||
507
+ limit <= 0) {
508
+ throw new Error("Invalid session event tail range.");
509
+ }
510
+ }
@@ -5,8 +5,11 @@ export declare class NodeSqliteSessionStore implements SessionStore {
5
5
  readonly agentName: string;
6
6
  constructor(directory?: string, projectRoot?: string, agentName?: string);
7
7
  read(sessionId: string): Promise<SessionEvent[]>;
8
+ readAfterSequence(sessionId: string, afterSequence: number, limit: number): Promise<SessionEvent[]>;
8
9
  append(sessionId: string, events: SessionEvent[]): Promise<void>;
9
10
  listSessionIds(): Promise<string[]>;
11
+ getCloudAcknowledgement(sessionId: string): Promise<number>;
12
+ setCloudAcknowledgement(sessionId: string, sequence: number): Promise<void>;
10
13
  subscribe(sessionId: string, listener: (events: SessionEvent[]) => void): () => void;
11
14
  subscribeAll(listener: (sessionId: string, events: SessionEvent[]) => void): () => void;
12
15
  describeLocation(_sessionId: string): Promise<string>;
@@ -25,22 +25,19 @@ export class NodeSqliteSessionStore {
25
25
  where agent_name = ? and session_id = ?
26
26
  order by sequence asc
27
27
  `).all(this.agentName, sessionId);
28
- return rows.map((row) => {
29
- let data;
30
- try {
31
- data = JSON.parse(row.data);
32
- }
33
- catch (error) {
34
- throw new Error(`Corrupt SQLite event in session "${sessionId}" at sequence ${row.sequence}.`, { cause: error });
35
- }
36
- return {
37
- sequence: row.sequence,
38
- type: row.type,
39
- timestamp: row.timestamp,
40
- ...(row.run === null ? {} : { run: row.run }),
41
- data,
42
- };
43
- });
28
+ return rows.map((row) => eventFromRow(row, sessionId));
29
+ }
30
+ async readAfterSequence(sessionId, afterSequence, limit) {
31
+ validateSessionId(sessionId);
32
+ validateTailArguments(afterSequence, limit);
33
+ const rows = this.#database.prepare(`
34
+ select sequence, run, type, timestamp, data
35
+ from session_events
36
+ where agent_name = ? and session_id = ? and sequence > ?
37
+ order by sequence asc
38
+ limit ?
39
+ `).all(this.agentName, sessionId, afterSequence, limit);
40
+ return rows.map((row) => eventFromRow(row, sessionId));
44
41
  }
45
42
  async append(sessionId, events) {
46
43
  validateSessionId(sessionId);
@@ -75,6 +72,27 @@ export class NodeSqliteSessionStore {
75
72
  `).all(this.agentName);
76
73
  return rows.map((row) => row.session_id);
77
74
  }
75
+ async getCloudAcknowledgement(sessionId) {
76
+ validateSessionId(sessionId);
77
+ const rows = this.#database.prepare(`
78
+ select sequence
79
+ from cloud_acknowledgements
80
+ where agent_name = ? and session_id = ?
81
+ `).all(this.agentName, sessionId);
82
+ return rows[0]?.sequence ?? 0;
83
+ }
84
+ async setCloudAcknowledgement(sessionId, sequence) {
85
+ validateSessionId(sessionId);
86
+ if (!Number.isInteger(sequence) || sequence < 0) {
87
+ throw new Error("Invalid cloud acknowledgement sequence.");
88
+ }
89
+ this.#database.prepare(`
90
+ insert into cloud_acknowledgements (agent_name, session_id, sequence)
91
+ values (?, ?, ?)
92
+ on conflict(agent_name, session_id) do update set sequence = excluded.sequence
93
+ where excluded.sequence > cloud_acknowledgements.sequence
94
+ `).run(this.agentName, sessionId, sequence);
95
+ }
78
96
  subscribe(sessionId, listener) {
79
97
  validateSessionId(sessionId);
80
98
  const listeners = this.#listeners.get(sessionId) ?? new Set();
@@ -128,7 +146,14 @@ function openDatabase(path) {
128
146
  primary key (agent_name, session_id, sequence)
129
147
  );
130
148
 
131
- pragma user_version = 1;
149
+ create table if not exists cloud_acknowledgements (
150
+ agent_name text not null,
151
+ session_id text not null,
152
+ sequence integer not null,
153
+ primary key (agent_name, session_id)
154
+ );
155
+
156
+ pragma user_version = 2;
132
157
  `);
133
158
  databases.set(path, database);
134
159
  return database;
@@ -147,6 +172,30 @@ function validateSessionId(sessionId) {
147
172
  throw new Error("Invalid session ID.");
148
173
  }
149
174
  }
175
+ function validateTailArguments(afterSequence, limit) {
176
+ if (!Number.isInteger(afterSequence) ||
177
+ afterSequence < 0 ||
178
+ !Number.isInteger(limit) ||
179
+ limit <= 0) {
180
+ throw new Error("Invalid session event tail range.");
181
+ }
182
+ }
183
+ function eventFromRow(row, sessionId) {
184
+ let data;
185
+ try {
186
+ data = JSON.parse(row.data);
187
+ }
188
+ catch (error) {
189
+ throw new Error(`Corrupt SQLite event in session "${sessionId}" at sequence ${row.sequence}.`, { cause: error });
190
+ }
191
+ return {
192
+ sequence: row.sequence,
193
+ type: row.type,
194
+ timestamp: row.timestamp,
195
+ ...(row.run === null ? {} : { run: row.run }),
196
+ data,
197
+ };
198
+ }
150
199
  function safelyNotify(notify) {
151
200
  try {
152
201
  notify();
@@ -3,8 +3,11 @@ export declare class ReactNativeJsonlSessionStore implements SessionStore {
3
3
  #private;
4
4
  constructor(namespace: string);
5
5
  read(sessionId: string): Promise<SessionEvent[]>;
6
+ readAfterSequence(sessionId: string, afterSequence: number, limit: number): Promise<SessionEvent[]>;
6
7
  append(sessionId: string, events: SessionEvent[]): Promise<void>;
7
8
  listSessionIds(): Promise<string[]>;
9
+ getCloudAcknowledgement(sessionId: string): Promise<number>;
10
+ setCloudAcknowledgement(sessionId: string, sequence: number): Promise<void>;
8
11
  subscribe(sessionId: string, listener: (events: SessionEvent[]) => void): () => void;
9
12
  subscribeAll(listener: (sessionId: string, events: SessionEvent[]) => void): () => void;
10
13
  describeLocation(sessionId: string): Promise<string>;