@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
package/README.md CHANGED
@@ -87,12 +87,32 @@ and injected collaboration-tool implementations are internal wiring. See
87
87
  [`BUGS.md`](./src/zukhruf/BUGS.md) for known residue.
88
88
 
89
89
  Compose infrastructure in a reusable `defineStack(async (resources) => ...)`
90
- recipe returning `{ store, streams, queue, mailboxStore }`, plus any plugin
91
- `bindings` or host options. The callback receives JavaScript's native
92
- `AsyncDisposableStack`: use `resources.use()` for disposable adapters and
93
- `resources.adopt()` for adapters exposing a cleanup method. Backend choices
94
- and startup calls stay explicit; see
95
- [`demo/zukhruf-simple/stack.ts`](../../demo/zukhruf-simple/stack.ts).
90
+ recipe returning `{ storage }`, plus any plugin `bindings` or host options.
91
+ `storage` is an `AgentStorage`: the context store, stream manager, turn queue
92
+ and mailbox store on one database, and `admit(tree, work)`, which runs `work`
93
+ with all four bound to one unit under a per-tree lock. On PostgreSQL,
94
+ `PostgresAgentStorage.create({ pool, boss })` builds the stores on the host's
95
+ pool and the turn queue on PgBoss, refuses a PgBoss on another database with
96
+ `AgentStorageDatabaseMismatchError`, and admits in one transaction under a
97
+ per-tree advisory lock. It borrows the pool and PgBoss; register it with
98
+ `resources.use()` so the host closes the stream change source it opened.
99
+ For one process, `EmbeddedAgentStorage.open({ directory })` keeps the stores in
100
+ `<directory>/zukhruf.sqlite` and pg-boss on PGlite in `<directory>/zukhruf.queue`,
101
+ and closes both. Its admissions run one at a time in one SQLite `BEGIN
102
+ IMMEDIATE` transaction; a turn pushed inside one is an outbox row of that
103
+ transaction, which a relay pushes to pg-boss after the commit, and `open`
104
+ pushes the rows a killed process left. Work inside `admit` uses its scope: a
105
+ call to the storage itself there rejects with `AdmissionScopeError`. The
106
+ callback receives JavaScript's native `AsyncDisposableStack`: use
107
+ `resources.use()` for disposable adapters and `resources.adopt()` for adapters
108
+ exposing a cleanup method. Backend choices and startup calls stay explicit.
109
+
110
+ ```ts
111
+ const stack = defineStack(async (resources) => ({
112
+ storage: resources.use(await PostgresAgentStorage.create({ pool, boss })),
113
+ multiAgent: { maxConcurrentThreadsPerSession: 4 },
114
+ }));
115
+ ```
96
116
 
97
117
  ```ts
98
118
  import declaration from './agent.ts';
@@ -194,10 +214,7 @@ const root = defineAgent({
194
214
  });
195
215
 
196
216
  const stack = defineStack(async () => ({
197
- store,
198
- streams,
199
- queue,
200
- mailboxStore,
217
+ storage,
201
218
  bindings: [
202
219
  schedulesCapabilities.boss.bind(boss),
203
220
  schedulesCapabilities.transaction.bind(transaction),