@deepagents/experimental 7.8.1 → 7.9.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 (32) hide show
  1. package/README.md +27 -10
  2. package/dist/index.js +601 -54
  3. package/dist/index.js.map +4 -4
  4. package/dist/zukhruf/index.d.ts +4 -0
  5. package/dist/zukhruf/index.d.ts.map +1 -1
  6. package/dist/zukhruf/index.js +601 -54
  7. package/dist/zukhruf/index.js.map +4 -4
  8. package/dist/zukhruf/mailbox/postgres.store.d.ts +9 -1
  9. package/dist/zukhruf/mailbox/postgres.store.d.ts.map +1 -1
  10. package/dist/zukhruf/mailbox/sqlite.store.d.ts +3 -1
  11. package/dist/zukhruf/mailbox/sqlite.store.d.ts.map +1 -1
  12. package/dist/zukhruf/mailbox/store.d.ts +4 -0
  13. package/dist/zukhruf/mailbox/store.d.ts.map +1 -1
  14. package/dist/zukhruf/plugins/conversation-scheduling/index.js.map +1 -1
  15. package/dist/zukhruf/plugins/schedules/index.js.map +1 -1
  16. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts +14 -1
  17. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts.map +1 -1
  18. package/dist/zukhruf/queue/turn-queue.d.ts +2 -0
  19. package/dist/zukhruf/queue/turn-queue.d.ts.map +1 -1
  20. package/dist/zukhruf/runtime/agent-runtime.d.ts +6 -7
  21. package/dist/zukhruf/runtime/agent-runtime.d.ts.map +1 -1
  22. package/dist/zukhruf/storage/agent-storage.d.ts +41 -0
  23. package/dist/zukhruf/storage/agent-storage.d.ts.map +1 -0
  24. package/dist/zukhruf/storage/embedded-agent-storage.d.ts +63 -0
  25. package/dist/zukhruf/storage/embedded-agent-storage.d.ts.map +1 -0
  26. package/dist/zukhruf/storage/postgres-agent-storage.d.ts +56 -0
  27. package/dist/zukhruf/storage/postgres-agent-storage.d.ts.map +1 -0
  28. package/dist/zukhruf/storage/sqlite-admission-gate.d.ts +29 -0
  29. package/dist/zukhruf/storage/sqlite-admission-gate.d.ts.map +1 -0
  30. package/dist/zukhruf/storage/turn-outbox.d.ts +65 -0
  31. package/dist/zukhruf/storage/turn-outbox.d.ts.map +1 -0
  32. package/package.json +6 -6
@@ -232,7 +232,10 @@ function defineInstructions(...fragments) {
232
232
 
233
233
  // packages/experimental/src/zukhruf/mailbox/postgres.store.ts
234
234
  import { z as z2 } from "zod";
235
- import { lockSchemaDDL, postgresTransaction } from "@deepagents/context";
235
+ import {
236
+ PostgresStoreDatabase,
237
+ lockSchemaDDL
238
+ } from "@deepagents/context";
236
239
 
237
240
  // packages/experimental/src/zukhruf/mailbox/communication-schema.ts
238
241
  import { z } from "zod";
@@ -341,21 +344,26 @@ var mailboxItemRowsSchema = z2.array(
341
344
  );
342
345
  var existsRowsSchema = z2.tuple([z2.object({ exists: z2.boolean() })]);
343
346
  var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
344
- #pool;
345
- #schema;
346
- constructor(pool, schema) {
347
+ #database;
348
+ constructor(database) {
347
349
  super();
348
- this.#pool = pool;
349
- this.#schema = schema;
350
+ this.#database = database;
350
351
  }
351
352
  /** Opens the store: creates its schema objects before it returns. */
352
353
  static async create(options) {
353
- const schema = options.schema ?? "public";
354
- await options.pool.query(lockSchemaDDL(mailboxDDL(schema), schema));
355
- return new _PostgresMailboxStore(options.pool, schema);
354
+ const database = new PostgresStoreDatabase(options.pool, options.schema);
355
+ await database.query(
356
+ lockSchemaDDL(mailboxDDL(database.schema), database.schema)
357
+ );
358
+ return new _PostgresMailboxStore(database);
356
359
  }
357
- #t(name) {
358
- return `"${this.#schema}"."${name}"`;
360
+ /**
361
+ * A view of this store whose reads and writes run inside `tx`. Each of its
362
+ * writes takes the recipient's lock in a savepoint of `tx`, and the lock is
363
+ * held until `tx` ends.
364
+ */
365
+ bind(tx) {
366
+ return new _PostgresMailboxStore(this.#database.bind(tx));
359
367
  }
360
368
  /**
361
369
  * Runs `fn` while holding the recipient's lock, so enqueue, drain and turn
@@ -363,21 +371,18 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
363
371
  * immediate transactions do.
364
372
  */
365
373
  #forRecipient(recipient, fn) {
366
- return postgresTransaction(this.#pool, async (client) => {
367
- await client.query(
368
- "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))",
369
- [
370
- `zukhruf:mailbox:${JSON.stringify([this.#schema, recipient.chatId, recipient.userId])}`
371
- ]
372
- );
373
- return fn(client);
374
+ return this.#database.transaction(async (tx) => {
375
+ await tx.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
376
+ `zukhruf:mailbox:${JSON.stringify([this.#database.schema, recipient.chatId, recipient.userId])}`
377
+ ]);
378
+ return fn(tx);
374
379
  });
375
380
  }
376
381
  async beginTurn(recipient, turnId) {
377
382
  await this.#forRecipient(
378
383
  recipient,
379
384
  (client) => client.query(
380
- `INSERT INTO ${this.#t("zukhruf_mailbox_activity")}
385
+ `INSERT INTO ${this.#database.table("zukhruf_mailbox_activity")}
381
386
  (recipient_chat_id, recipient_user_id, turn_id)
382
387
  VALUES ($1, $2, $3)
383
388
  ON CONFLICT (recipient_chat_id, recipient_user_id)
@@ -392,13 +397,13 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
392
397
  const consumedTerminal = communication.type === InterAgentCommunicationTypes.FinalAnswer && await this.#exists(
393
398
  client,
394
399
  `SELECT EXISTS (
395
- SELECT 1 FROM ${this.#t("zukhruf_mailbox_consumed_terminal_ids")}
400
+ SELECT 1 FROM ${this.#database.table("zukhruf_mailbox_consumed_terminal_ids")}
396
401
  WHERE communication_id = $1)`,
397
402
  [communication.id]
398
403
  );
399
404
  if (!consumedTerminal) {
400
405
  await client.query(
401
- `INSERT INTO ${this.#t("zukhruf_mailbox_items")}
406
+ `INSERT INTO ${this.#database.table("zukhruf_mailbox_items")}
402
407
  (communication_id, recipient_chat_id, recipient_user_id, communication)
403
408
  VALUES ($1, $2, $3, $4::jsonb)
404
409
  ON CONFLICT (communication_id) DO NOTHING`,
@@ -416,7 +421,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
416
421
  endTurn(recipient, turnId) {
417
422
  return this.#forRecipient(recipient, async (client) => {
418
423
  const ended = await client.query(
419
- `DELETE FROM ${this.#t("zukhruf_mailbox_activity")}
424
+ `DELETE FROM ${this.#database.table("zukhruf_mailbox_activity")}
420
425
  WHERE recipient_chat_id = $1
421
426
  AND recipient_user_id = $2
422
427
  AND turn_id = $3`,
@@ -429,7 +434,18 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
429
434
  });
430
435
  }
431
436
  hasPending(recipient) {
432
- return this.#hasPending(this.#pool, recipient);
437
+ return this.#hasPending(this.#database, recipient);
438
+ }
439
+ hasPendingTriggerTurn(recipient) {
440
+ return this.#exists(
441
+ this.#database,
442
+ `SELECT EXISTS (
443
+ SELECT 1 FROM ${this.#database.table("zukhruf_mailbox_items")}
444
+ WHERE recipient_chat_id = $1
445
+ AND recipient_user_id = $2
446
+ AND communication @> '{"triggerTurn": true}')`,
447
+ [recipient.chatId, recipient.userId]
448
+ );
433
449
  }
434
450
  drain(recipient) {
435
451
  return this.#drain(recipient, false);
@@ -442,7 +458,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
442
458
  const items = mailboxItemRowsSchema.parse(
443
459
  (await client.query(
444
460
  `SELECT sequence, communication
445
- FROM ${this.#t("zukhruf_mailbox_items")}
461
+ FROM ${this.#database.table("zukhruf_mailbox_items")}
446
462
  WHERE recipient_chat_id = $1
447
463
  AND recipient_user_id = $2
448
464
  ORDER BY sequence`,
@@ -453,7 +469,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
453
469
  const consumed = firstTrigger === -1 ? items : items.slice(0, firstTrigger);
454
470
  if (consumed.length === 0) return [];
455
471
  await client.query(
456
- `INSERT INTO ${this.#t("zukhruf_mailbox_consumed_terminal_ids")} (communication_id)
472
+ `INSERT INTO ${this.#database.table("zukhruf_mailbox_consumed_terminal_ids")} (communication_id)
457
473
  SELECT unnest($1::text[])
458
474
  ON CONFLICT (communication_id) DO NOTHING`,
459
475
  [
@@ -463,7 +479,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
463
479
  ]
464
480
  );
465
481
  await client.query(
466
- `DELETE FROM ${this.#t("zukhruf_mailbox_items")}
482
+ `DELETE FROM ${this.#database.table("zukhruf_mailbox_items")}
467
483
  WHERE sequence = ANY($1::bigint[])`,
468
484
  [consumed.map(({ sequence }) => sequence)]
469
485
  );
@@ -474,7 +490,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
474
490
  return this.#exists(
475
491
  queryable,
476
492
  `SELECT EXISTS (
477
- SELECT 1 FROM ${this.#t("zukhruf_mailbox_items")}
493
+ SELECT 1 FROM ${this.#database.table("zukhruf_mailbox_items")}
478
494
  WHERE recipient_chat_id = $1 AND recipient_user_id = $2)`,
479
495
  [recipient.chatId, recipient.userId]
480
496
  );
@@ -483,7 +499,7 @@ var PostgresMailboxStore = class _PostgresMailboxStore extends MailboxStore {
483
499
  return this.#exists(
484
500
  client,
485
501
  `SELECT EXISTS (
486
- SELECT 1 FROM ${this.#t("zukhruf_mailbox_activity")}
502
+ SELECT 1 FROM ${this.#database.table("zukhruf_mailbox_activity")}
487
503
  WHERE recipient_chat_id = $1 AND recipient_user_id = $2)`,
488
504
  [recipient.chatId, recipient.userId]
489
505
  );
@@ -545,9 +561,9 @@ var mailboxItemRowsSchema2 = z3.array(
545
561
  );
546
562
  var SqliteMailboxStore = class extends MailboxStore {
547
563
  #database;
548
- constructor(path3) {
564
+ constructor(pathOrDb) {
549
565
  super();
550
- this.#database = open(path3);
566
+ this.#database = typeof pathOrDb === "string" ? open(pathOrDb) : pathOrDb;
551
567
  this.#database.exec(SETUP);
552
568
  tables.apply(this.#database);
553
569
  }
@@ -614,6 +630,17 @@ var SqliteMailboxStore = class extends MailboxStore {
614
630
  async hasPending(recipient) {
615
631
  return this.#hasPending(recipient);
616
632
  }
633
+ async hasPendingTriggerTurn(recipient) {
634
+ const row = this.#database.prepare(
635
+ `SELECT 1
636
+ FROM zukhruf_mailbox_items
637
+ WHERE recipient_chat_id = ?
638
+ AND recipient_user_id = ?
639
+ AND json_extract(communication, '$.triggerTurn') = 1
640
+ LIMIT 1`
641
+ ).get(recipient.chatId, recipient.userId);
642
+ return row !== void 0;
643
+ }
617
644
  #hasPending(recipient) {
618
645
  const row = this.#database.prepare(
619
646
  `SELECT 1
@@ -737,6 +764,7 @@ var PgBossTurnQueue = class _PgBossTurnQueue extends TurnQueue {
737
764
  static async create(boss, options = {}) {
738
765
  const settings = _PgBossTurnQueue.#settings(boss, options);
739
766
  const opened = await _PgBossTurnQueue.#openQueue(boss, settings);
767
+ await boss.findJobs(settings.queue, { id: uuidv7() });
740
768
  return new _PgBossTurnQueue(boss, settings, opened);
741
769
  }
742
770
  static #settings(boss, options) {
@@ -811,19 +839,53 @@ var PgBossTurnQueue = class _PgBossTurnQueue extends TurnQueue {
811
839
  get deadLetterQueue() {
812
840
  return deadLetterQueueOf(this.#queue);
813
841
  }
814
- async push(turn) {
842
+ /**
843
+ * A view whose `push` and `getTurnActivity` run inside `tx`: a pushed turn
844
+ * reaches workers only if `tx` commits, and activity counts what `tx` has
845
+ * pushed so far. `tx` must be on the database PgBoss uses.
846
+ */
847
+ bind(tx) {
848
+ const db = {
849
+ executeSql: (text, values) => tx.query(text, values)
850
+ };
851
+ return {
852
+ push: (turn) => this.#push(turn, db),
853
+ getTurnActivity: (conversation) => this.#getTurnActivity(conversation, db)
854
+ };
855
+ }
856
+ push(turn) {
857
+ return this.#push(turn, void 0);
858
+ }
859
+ getTurnActivity(conversation) {
860
+ return this.#getTurnActivity(conversation, void 0);
861
+ }
862
+ /**
863
+ * Pushes `turn` as the job `id`, a UUID. While pg-boss holds a job with that
864
+ * id, a second push of it adds nothing. Ids that grow with push order (UUIDv7)
865
+ * keep FIFO across timestamp ties.
866
+ */
867
+ async pushAs(id, turn) {
868
+ await this.#send(id, turn, void 0);
869
+ }
870
+ async #push(turn, db) {
815
871
  const jobId = uuidv7();
816
- const inserted = await this.#boss.send(this.#queue, turn, {
817
- id: jobId,
818
- singletonKey: turn.chatId
819
- });
820
- if (inserted === null) {
872
+ if (!await this.#send(jobId, turn, db)) {
821
873
  throw new Error(`PgBossTurnQueue job id collision: ${jobId}`);
822
874
  }
823
875
  }
824
- async getTurnActivity(conversation) {
876
+ /** Whether pg-boss inserted the job: it skips an id it already holds. */
877
+ async #send(id, turn, db) {
878
+ const inserted = await this.#boss.send(this.#queue, turn, {
879
+ id,
880
+ singletonKey: turn.chatId,
881
+ db
882
+ });
883
+ return inserted !== null;
884
+ }
885
+ async #getTurnActivity(conversation, db) {
825
886
  const jobs = await this.#boss.findJobs(this.#queue, {
826
- key: conversation.chatId
887
+ key: conversation.chatId,
888
+ db
827
889
  });
828
890
  const conversationJobs = jobs.filter(
829
891
  (job) => job.data.userId === conversation.userId && (job.state === "created" || job.state === "retry" || job.state === "active")
@@ -2292,12 +2354,12 @@ function replacementRange(messages, keepLastMessages) {
2292
2354
  while (messages[start]?.role === "system") start++;
2293
2355
  let limit = messages.length - keepLastMessages;
2294
2356
  const links = /* @__PURE__ */ new Map();
2295
- const link = (key, index, open2) => {
2357
+ const link = (key, index, open3) => {
2296
2358
  const previous = links.get(key);
2297
2359
  links.set(key, {
2298
2360
  first: previous?.first ?? index,
2299
2361
  last: index,
2300
- open: open2 ?? previous?.open ?? false
2362
+ open: open3 ?? previous?.open ?? false
2301
2363
  });
2302
2364
  };
2303
2365
  for (const [index, message] of messages.entries()) {
@@ -2326,8 +2388,8 @@ function replacementRange(messages, keepLastMessages) {
2326
2388
  }
2327
2389
  }
2328
2390
  const crossings = new Int32Array(messages.length + 1);
2329
- for (const { first, last, open: open2 } of links.values()) {
2330
- if (open2) limit = Math.min(limit, first);
2391
+ for (const { first, last, open: open3 } of links.values()) {
2392
+ if (open3) limit = Math.min(limit, first);
2331
2393
  crossings[first + 1]++;
2332
2394
  crossings[last + 1]--;
2333
2395
  }
@@ -4616,37 +4678,38 @@ var RuntimeHost = class {
4616
4678
  new PluginManager(root, options.bindings, multiAgent)
4617
4679
  );
4618
4680
  const declarations = plugins.declarations;
4619
- const directory = new AgentDirectory(options.store);
4620
- const streams = options.streams;
4681
+ const { storage } = options;
4682
+ const directory = new AgentDirectory(storage.store);
4683
+ const streams = storage.streams;
4621
4684
  const conversationStatus = new ConversationStatusProjector({
4622
- store: options.store,
4685
+ store: storage.store,
4623
4686
  streams,
4624
- queue: options.queue,
4687
+ queue: storage.queue,
4625
4688
  directory,
4626
4689
  changeSource: options.conversationStatusChanges
4627
4690
  });
4628
4691
  const queue = new StatusPublishingTurnQueue(
4629
- options.queue,
4692
+ storage.queue,
4630
4693
  (conversation) => conversationStatus.publish(conversation)
4631
4694
  );
4632
4695
  const mailbox = new MailboxCoordinator({
4633
- store: options.mailboxStore,
4696
+ store: storage.mailboxStore,
4634
4697
  queue,
4635
4698
  streams
4636
4699
  });
4637
4700
  const approvals = new ApprovalController({
4638
- store: options.store,
4701
+ store: storage.store,
4639
4702
  queue
4640
4703
  });
4641
4704
  const statusProjector = new AgentStatusProjector({
4642
- store: options.store,
4705
+ store: storage.store,
4643
4706
  streams,
4644
4707
  queue,
4645
4708
  mailbox,
4646
4709
  directory,
4647
4710
  approvals
4648
4711
  });
4649
- const historyForker = new AgentHistoryForker(options.store);
4712
+ const historyForker = new AgentHistoryForker(storage.store);
4650
4713
  const controlPlane = new AgentControlPlane({
4651
4714
  root: declarations.root,
4652
4715
  streams,
@@ -4659,7 +4722,7 @@ var RuntimeHost = class {
4659
4722
  recordActivity: (thread, activity) => conversationStatus.recordActivity(thread, activity),
4660
4723
  maxConcurrentThreadsPerSession: multiAgent.maxConcurrentThreadsPerSession
4661
4724
  });
4662
- this.#store = options.store;
4725
+ this.#store = storage.store;
4663
4726
  this.#queue = queue;
4664
4727
  this.#streams = streams;
4665
4728
  this.#mailbox = mailbox;
@@ -4685,7 +4748,7 @@ var RuntimeHost = class {
4685
4748
  };
4686
4749
  const sandboxes = resources.use(new ConversationSandboxes());
4687
4750
  this.#executor = new AgentTurnExecutor({
4688
- store: options.store,
4751
+ store: storage.store,
4689
4752
  streams,
4690
4753
  controlPlane,
4691
4754
  mailbox,
@@ -5023,24 +5086,508 @@ function defineSandbox(createBackend, options) {
5023
5086
  };
5024
5087
  }
5025
5088
 
5089
+ // packages/experimental/src/zukhruf/storage/agent-storage.ts
5090
+ var AgentStorage = class {
5091
+ };
5092
+
5093
+ // packages/experimental/src/zukhruf/storage/embedded-agent-storage.ts
5094
+ import { PGlite } from "@electric-sql/pglite";
5095
+ import { FileLock } from "@zukhruf/fs";
5096
+ import { open as open2 } from "@zukhruf/sqlite-open";
5097
+ import { mkdir } from "node:fs/promises";
5098
+ import { join as join2 } from "node:path";
5099
+ import { PgBoss, fromPglite } from "pg-boss";
5100
+ import {
5101
+ PollingChangeSource,
5102
+ SqliteContextStore,
5103
+ SqliteStreamStore,
5104
+ StreamManager
5105
+ } from "@deepagents/context";
5106
+
5107
+ // packages/experimental/src/zukhruf/storage/sqlite-admission-gate.ts
5108
+ import { Lock } from "@zukhruf/async";
5109
+ import { AsyncLocalStorage } from "node:async_hooks";
5110
+ var AdmissionScopeError = class extends Error {
5111
+ name = "AdmissionScopeError";
5112
+ constructor() {
5113
+ super(
5114
+ "EmbeddedAgentStorage: an admission's work called the storage itself; inside admit, read and write through the AdmissionScope it was given"
5115
+ );
5116
+ }
5117
+ };
5118
+ var SqliteAdmissionGate = class {
5119
+ #database;
5120
+ #connection = new Lock();
5121
+ #admission = new AsyncLocalStorage();
5122
+ constructor(database) {
5123
+ this.#database = database;
5124
+ }
5125
+ /** `part` with every method run through `call`. */
5126
+ view(part) {
5127
+ return new Proxy(part, {
5128
+ get: (target, property) => {
5129
+ const value = Reflect.get(target, property, target);
5130
+ if (typeof value !== "function") return value;
5131
+ return (...args) => this.call(async () => Reflect.apply(value, target, args));
5132
+ }
5133
+ });
5134
+ }
5135
+ /** Runs `operation` while it holds the connection alone. */
5136
+ async call(operation) {
5137
+ if (this.#insideAdmission()) throw new AdmissionScopeError();
5138
+ return this.#connection.run(operation, { signal: void 0 });
5139
+ }
5140
+ /** Runs `work` in one `BEGIN IMMEDIATE` transaction: commits when it resolves, rolls back when it throws. */
5141
+ async admit(work) {
5142
+ if (this.#insideAdmission()) throw new AdmissionScopeError();
5143
+ return this.#connection.run(
5144
+ async () => {
5145
+ const admission = { open: true };
5146
+ this.#database.exec("BEGIN IMMEDIATE");
5147
+ try {
5148
+ const result = await this.#admission.run(admission, work);
5149
+ this.#database.exec("COMMIT");
5150
+ return result;
5151
+ } catch (error) {
5152
+ if (this.#database.isTransaction) this.#database.exec("ROLLBACK");
5153
+ throw error;
5154
+ } finally {
5155
+ admission.open = false;
5156
+ }
5157
+ },
5158
+ { signal: void 0 }
5159
+ );
5160
+ }
5161
+ /**
5162
+ * Inside its own admission a call would wait for that admission to end,
5163
+ * which waits for the call. Work the admission left running after it
5164
+ * ended is no longer inside it.
5165
+ */
5166
+ #insideAdmission() {
5167
+ return this.#admission.getStore()?.open === true;
5168
+ }
5169
+ };
5170
+
5171
+ // packages/experimental/src/zukhruf/storage/turn-outbox.ts
5172
+ import { Lock as Lock2 } from "@zukhruf/async";
5173
+ import { Declaration as Declaration2 } from "@zukhruf/sqlite-drift";
5174
+ import { v7 as uuidv72 } from "uuid";
5175
+ import { z as z14 } from "zod";
5176
+ var tables2 = new Declaration2(
5177
+ [
5178
+ `CREATE TABLE zukhruf_turn_outbox (
5179
+ sequence INTEGER PRIMARY KEY AUTOINCREMENT,
5180
+ job_id TEXT NOT NULL UNIQUE,
5181
+ chat_id TEXT NOT NULL,
5182
+ user_id TEXT NOT NULL,
5183
+ stream_id TEXT NOT NULL,
5184
+ turn TEXT NOT NULL
5185
+ )`,
5186
+ `CREATE INDEX zukhruf_turn_outbox_conversation
5187
+ ON zukhruf_turn_outbox (chat_id, user_id, sequence)`
5188
+ ],
5189
+ { rows: "keep" }
5190
+ );
5191
+ var outboxRowSchema = z14.object({ jobId: z14.string(), turn: z14.string() });
5192
+ function parseTurn(text) {
5193
+ const turn = JSON.parse(text);
5194
+ return turn;
5195
+ }
5196
+ var TurnOutbox = class {
5197
+ #database;
5198
+ constructor(database) {
5199
+ this.#database = database;
5200
+ tables2.apply(database);
5201
+ }
5202
+ add(turn) {
5203
+ this.#database.prepare(
5204
+ `INSERT INTO zukhruf_turn_outbox (job_id, chat_id, user_id, stream_id, turn)
5205
+ VALUES (?, ?, ?, ?, ?)`
5206
+ ).run(
5207
+ uuidv72(),
5208
+ turn.chatId,
5209
+ turn.userId,
5210
+ turn.streamId,
5211
+ JSON.stringify(turn)
5212
+ );
5213
+ }
5214
+ oldest() {
5215
+ return this.#outboxed(
5216
+ this.#database.prepare(
5217
+ `SELECT job_id AS jobId, turn FROM zukhruf_turn_outbox
5218
+ ORDER BY sequence LIMIT 1`
5219
+ ).get()
5220
+ );
5221
+ }
5222
+ oldestOf(conversation) {
5223
+ return this.#outboxed(
5224
+ this.#database.prepare(
5225
+ `SELECT job_id AS jobId, turn FROM zukhruf_turn_outbox
5226
+ WHERE chat_id = ? AND user_id = ?
5227
+ ORDER BY sequence LIMIT 1`
5228
+ ).get(conversation.chatId, conversation.userId)
5229
+ )?.turn;
5230
+ }
5231
+ holds(conversation) {
5232
+ return this.#database.prepare(
5233
+ `SELECT 1 FROM zukhruf_turn_outbox
5234
+ WHERE chat_id = ? AND user_id = ? LIMIT 1`
5235
+ ).get(conversation.chatId, conversation.userId) !== void 0;
5236
+ }
5237
+ remove(jobId) {
5238
+ this.#database.prepare("DELETE FROM zukhruf_turn_outbox WHERE job_id = ?").run(jobId);
5239
+ }
5240
+ removeStream(streamId) {
5241
+ this.#database.prepare("DELETE FROM zukhruf_turn_outbox WHERE stream_id = ?").run(streamId);
5242
+ }
5243
+ #outboxed(row) {
5244
+ if (row === void 0) return void 0;
5245
+ const { jobId, turn } = outboxRowSchema.parse(row);
5246
+ return { jobId, turn: parseTurn(turn) };
5247
+ }
5248
+ };
5249
+ function withOutboxed(activity, outboxed) {
5250
+ if (activity === "running") return activity;
5251
+ return outboxed ? "queued" : activity;
5252
+ }
5253
+ var OutboxRelay = class {
5254
+ #gate;
5255
+ #outbox;
5256
+ #queue;
5257
+ /** Held by a drain, and by work that must not run while a row is between its push and its delete. */
5258
+ #rows = new Lock2();
5259
+ constructor(gate, outbox, queue) {
5260
+ this.#gate = gate;
5261
+ this.#outbox = outbox;
5262
+ this.#queue = queue;
5263
+ }
5264
+ /** Resolves once every row added before the call has reached pg-boss. */
5265
+ drain() {
5266
+ return this.between(async () => {
5267
+ for (; ; ) {
5268
+ const next = await this.#gate.call(async () => this.#outbox.oldest());
5269
+ if (!next) return;
5270
+ await this.#queue.pushAs(next.jobId, next.turn);
5271
+ await this.#gate.call(async () => this.#outbox.remove(next.jobId));
5272
+ }
5273
+ });
5274
+ }
5275
+ /** Runs `operation` while no drain runs. */
5276
+ between(operation) {
5277
+ return this.#rows.run(operation, { signal: void 0 });
5278
+ }
5279
+ };
5280
+ var OutboxTurnQueue = class extends TurnQueue {
5281
+ #gate;
5282
+ #outbox;
5283
+ #relay;
5284
+ #queue;
5285
+ constructor(parts) {
5286
+ super();
5287
+ this.#gate = parts.gate;
5288
+ this.#outbox = parts.outbox;
5289
+ this.#relay = parts.relay;
5290
+ this.#queue = parts.queue;
5291
+ }
5292
+ /** The view an admission pushes and counts through: its pushes are outbox rows of its transaction. */
5293
+ scope() {
5294
+ return {
5295
+ push: async (turn) => this.#outbox.add(turn),
5296
+ getTurnActivity: async (conversation) => {
5297
+ const outboxed = this.#outbox.holds(conversation);
5298
+ return withOutboxed(
5299
+ await this.#queue.getTurnActivity(conversation),
5300
+ outboxed
5301
+ );
5302
+ }
5303
+ };
5304
+ }
5305
+ /** Resolves once the turn is in pg-boss. */
5306
+ async push(turn) {
5307
+ await this.#gate.call(async () => this.#outbox.add(turn));
5308
+ await this.#relay.drain();
5309
+ }
5310
+ async getTurnActivity(conversation) {
5311
+ const outboxed = await this.#gate.call(
5312
+ async () => this.#outbox.holds(conversation)
5313
+ );
5314
+ return withOutboxed(
5315
+ await this.#queue.getTurnActivity(conversation),
5316
+ outboxed
5317
+ );
5318
+ }
5319
+ async getCurrentTurn(conversation) {
5320
+ const outboxed = await this.#gate.call(
5321
+ async () => this.#outbox.oldestOf(conversation)
5322
+ );
5323
+ return await this.#queue.getCurrentTurn(conversation) ?? outboxed;
5324
+ }
5325
+ cancel(streamId) {
5326
+ return this.#relay.between(async () => {
5327
+ await this.#gate.call(async () => this.#outbox.removeStream(streamId));
5328
+ await this.#queue.cancel(streamId);
5329
+ });
5330
+ }
5331
+ consume(handler, options) {
5332
+ return this.#queue.consume(handler, options);
5333
+ }
5334
+ resumeParked(chatId) {
5335
+ return this.#queue.resumeParked(chatId);
5336
+ }
5337
+ };
5338
+
5339
+ // packages/experimental/src/zukhruf/storage/embedded-agent-storage.ts
5340
+ var EmbeddedAgentStorageInUseError = class extends Error {
5341
+ name = "EmbeddedAgentStorageInUseError";
5342
+ directory;
5343
+ constructor(directory) {
5344
+ super(
5345
+ `EmbeddedAgentStorage: ${JSON.stringify(directory)} is open in another EmbeddedAgentStorage; one storage at a time may open a directory`
5346
+ );
5347
+ this.directory = directory;
5348
+ }
5349
+ };
5350
+ function emitWarning(error) {
5351
+ process.emitWarning(
5352
+ Error.isError(error) ? error : new Error(String(error), { cause: error })
5353
+ );
5354
+ }
5355
+ var EmbeddedAgentStorage = class _EmbeddedAgentStorage extends AgentStorage {
5356
+ store;
5357
+ streams;
5358
+ queue;
5359
+ mailboxStore;
5360
+ /** Started and owned; a host may bind it to plugins that keep jobs beside the turns. */
5361
+ boss;
5362
+ /** The PGlite database pg-boss runs on, for transactions of such plugins. */
5363
+ queueDatabase;
5364
+ #gate;
5365
+ #scope;
5366
+ #relay;
5367
+ #resources;
5368
+ constructor(parts) {
5369
+ super();
5370
+ this.store = parts.store;
5371
+ this.streams = parts.streams;
5372
+ this.queue = parts.queue;
5373
+ this.mailboxStore = parts.mailboxStore;
5374
+ this.boss = parts.boss;
5375
+ this.queueDatabase = parts.queueDatabase;
5376
+ this.#gate = parts.gate;
5377
+ this.#scope = parts.scope;
5378
+ this.#relay = parts.relay;
5379
+ this.#resources = parts.resources;
5380
+ }
5381
+ /**
5382
+ * Opens the storage in `directory` and pushes the turns its outbox still
5383
+ * holds. Rejects with `EmbeddedAgentStorageInUseError` while another storage
5384
+ * has the directory open.
5385
+ */
5386
+ static async open(options) {
5387
+ await mkdir(options.directory, { recursive: true });
5388
+ await using resources = new AsyncDisposableStack();
5389
+ const lock = resources.use(
5390
+ FileLock.open(join2(options.directory, "zukhruf.lock"))
5391
+ );
5392
+ if (!lock.tryLock()) {
5393
+ throw new EmbeddedAgentStorageInUseError(options.directory);
5394
+ }
5395
+ const database = resources.adopt(
5396
+ open2(join2(options.directory, "zukhruf.sqlite")),
5397
+ (database2) => database2.close()
5398
+ );
5399
+ const queueDatabase = resources.adopt(
5400
+ new PGlite(join2(options.directory, "zukhruf.queue")),
5401
+ (queueDatabase2) => queueDatabase2.close()
5402
+ );
5403
+ const boss = new PgBoss({
5404
+ db: fromPglite(queueDatabase),
5405
+ backend: "pglite"
5406
+ });
5407
+ boss.on("error", emitWarning);
5408
+ await boss.start();
5409
+ resources.defer(() => boss.stop({ graceful: false }));
5410
+ const turns = await PgBossTurnQueue.create(boss, {
5411
+ pollingIntervalSeconds: 0.5,
5412
+ ...options.queue,
5413
+ schema: "pgboss"
5414
+ });
5415
+ const gate = new SqliteAdmissionGate(database);
5416
+ const store = new SqliteContextStore(database);
5417
+ const streamStore = new SqliteStreamStore(database);
5418
+ const mailboxStore = new SqliteMailboxStore(database);
5419
+ const outbox = new TurnOutbox(database);
5420
+ const relay = new OutboxRelay(gate, outbox, turns);
5421
+ resources.defer(() => relay.between(async () => void 0));
5422
+ const queue = new OutboxTurnQueue({ gate, outbox, relay, queue: turns });
5423
+ const streams = gate.view(streamStore);
5424
+ await relay.drain();
5425
+ return new _EmbeddedAgentStorage({
5426
+ store: gate.view(store),
5427
+ streams: new StreamManager({
5428
+ store: streams,
5429
+ changeSource: new PollingChangeSource({ reads: streams })
5430
+ }),
5431
+ queue,
5432
+ mailboxStore: gate.view(mailboxStore),
5433
+ boss,
5434
+ queueDatabase,
5435
+ gate,
5436
+ scope: {
5437
+ store,
5438
+ streams: streamStore,
5439
+ mailboxStore,
5440
+ queue: queue.scope()
5441
+ },
5442
+ relay,
5443
+ resources: resources.move()
5444
+ });
5445
+ }
5446
+ /**
5447
+ * Runs `work` in one SQLite transaction while no other admission, to any
5448
+ * tree, runs. Resolves once it has committed; the relay then pushes the
5449
+ * turns it outboxed.
5450
+ */
5451
+ async admit(_tree, work) {
5452
+ const result = await this.#gate.admit(() => work(this.#scope));
5453
+ this.#relay.drain().catch(emitWarning);
5454
+ return result;
5455
+ }
5456
+ /** Waits for the relay, stops pg-boss, and closes both databases. */
5457
+ async [Symbol.asyncDispose]() {
5458
+ await this.#resources.disposeAsync();
5459
+ }
5460
+ };
5461
+
5462
+ // packages/experimental/src/zukhruf/storage/postgres-agent-storage.ts
5463
+ import { z as z15 } from "zod";
5464
+ import {
5465
+ PostgresContextStore,
5466
+ PostgresNotifyChangeSource,
5467
+ PostgresStreamStore,
5468
+ StreamManager as StreamManager2,
5469
+ postgresTransaction
5470
+ } from "@deepagents/context";
5471
+ var DATABASE_IDENTITY_SQL = `SELECT current_database() AS database,
5472
+ (pg_control_system()).system_identifier::text AS "systemIdentifier"`;
5473
+ var databaseIdentityRowsSchema = z15.tuple([
5474
+ z15.object({ database: z15.string(), systemIdentifier: z15.string() })
5475
+ ]);
5476
+ async function databaseIdentity(result) {
5477
+ return databaseIdentityRowsSchema.parse((await result).rows)[0];
5478
+ }
5479
+ var AgentStorageDatabaseMismatchError = class extends Error {
5480
+ name = "AgentStorageDatabaseMismatchError";
5481
+ pool;
5482
+ boss;
5483
+ constructor(pool, boss) {
5484
+ super(
5485
+ `PostgresAgentStorage needs the pool and PgBoss on one database; the pool reaches "${pool.database}" (system ${pool.systemIdentifier}) and PgBoss reaches "${boss.database}" (system ${boss.systemIdentifier})`
5486
+ );
5487
+ this.pool = pool;
5488
+ this.boss = boss;
5489
+ }
5490
+ };
5491
+ var PostgresAgentStorage = class _PostgresAgentStorage extends AgentStorage {
5492
+ store;
5493
+ streams;
5494
+ queue;
5495
+ mailboxStore;
5496
+ #pool;
5497
+ #schema;
5498
+ #streamStore;
5499
+ #ownedChangeSource;
5500
+ constructor(parts) {
5501
+ super();
5502
+ this.#pool = parts.pool;
5503
+ this.#schema = parts.schema;
5504
+ this.store = parts.store;
5505
+ this.#streamStore = parts.streamStore;
5506
+ this.streams = parts.streams;
5507
+ this.queue = parts.queue;
5508
+ this.mailboxStore = parts.mailboxStore;
5509
+ this.#ownedChangeSource = parts.ownedChangeSource;
5510
+ }
5511
+ /**
5512
+ * Opens the storage: checks that the pool and PgBoss reach one database,
5513
+ * then creates the tables and the turn queue.
5514
+ */
5515
+ static async create(options) {
5516
+ const { pool, boss } = options;
5517
+ const schema = options.schema ?? "public";
5518
+ const [poolIdentity, bossIdentity] = await Promise.all([
5519
+ databaseIdentity(pool.query(DATABASE_IDENTITY_SQL)),
5520
+ databaseIdentity(boss.getDb().executeSql(DATABASE_IDENTITY_SQL))
5521
+ ]);
5522
+ if (poolIdentity.database !== bossIdentity.database || poolIdentity.systemIdentifier !== bossIdentity.systemIdentifier) {
5523
+ throw new AgentStorageDatabaseMismatchError(poolIdentity, bossIdentity);
5524
+ }
5525
+ const store = await PostgresContextStore.create({ pool, schema });
5526
+ const streamStore = await PostgresStreamStore.create({ pool, schema });
5527
+ const mailboxStore = await PostgresMailboxStore.create({ pool, schema });
5528
+ const queue = await PgBossTurnQueue.create(boss, options.queue);
5529
+ let changeSource = options.changeSource;
5530
+ let ownedChangeSource;
5531
+ if (changeSource === void 0) {
5532
+ ownedChangeSource = await PostgresNotifyChangeSource.create({
5533
+ pool,
5534
+ schema
5535
+ });
5536
+ changeSource = ownedChangeSource;
5537
+ }
5538
+ return new _PostgresAgentStorage({
5539
+ pool,
5540
+ schema,
5541
+ store,
5542
+ streamStore,
5543
+ streams: new StreamManager2({ store: streamStore, changeSource }),
5544
+ queue,
5545
+ mailboxStore,
5546
+ ownedChangeSource
5547
+ });
5548
+ }
5549
+ admit(tree, work) {
5550
+ return postgresTransaction(this.#pool, async (tx) => {
5551
+ await tx.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
5552
+ `zukhruf:agent-tree:${JSON.stringify([this.#schema, tree.userId, tree.treeId])}`
5553
+ ]);
5554
+ return work({
5555
+ store: this.store.bind(tx),
5556
+ streams: this.#streamStore.bind(tx),
5557
+ mailboxStore: this.mailboxStore.bind(tx),
5558
+ queue: this.queue.bind(tx)
5559
+ });
5560
+ });
5561
+ }
5562
+ async [Symbol.asyncDispose]() {
5563
+ await this.#ownedChangeSource?.close();
5564
+ }
5565
+ };
5566
+
5026
5567
  // packages/experimental/src/zukhruf/tool.ts
5027
5568
  function defineTool(definition) {
5028
5569
  return definition;
5029
5570
  }
5030
5571
  export {
5572
+ AdmissionScopeError,
5031
5573
  AgentObservation,
5032
5574
  AgentPath,
5033
5575
  AgentPluginCapability,
5034
5576
  AgentRuntime,
5577
+ AgentStorage,
5578
+ AgentStorageDatabaseMismatchError,
5035
5579
  AgentThread,
5036
5580
  AgentThreadLimitError,
5037
5581
  ConversationNotFoundError,
5038
5582
  DEFAULT_CONVERSATION_STATUS_CHANNEL,
5583
+ EmbeddedAgentStorage,
5584
+ EmbeddedAgentStorageInUseError,
5039
5585
  InterAgentCommunicationTypes,
5040
5586
  MailboxStore,
5041
5587
  MessageDeliveryModes,
5042
5588
  PgBossConversationStatusChangeSource,
5043
5589
  PgBossTurnQueue,
5590
+ PostgresAgentStorage,
5044
5591
  PostgresMailboxStore,
5045
5592
  SqliteMailboxStore,
5046
5593
  StaleTurnError,