@desplega.ai/agent-swarm 2.13.5 → 2.14.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 (414) hide show
  1. package/dist/acp-adapter-99n6z9ky.js +17 -0
  2. package/dist/{acp-targets-w8dbs4nr.js → acp-targets-23exz4z4.js} +10 -10
  3. package/dist/{actions-8zrcbjrx.js → actions-zcr25x27.js} +60 -39
  4. package/dist/{agent-fs-provision-cbt2ttds.js → agent-fs-provision-7fa9e12e.js} +4 -4
  5. package/dist/{amp-adapter-8x6zp8w4.js → amp-adapter-s7ytmv6b.js} +3 -3
  6. package/dist/{app-zfa9dwjw.js → app-5d3sz1hy.js} +7 -7
  7. package/dist/{approval-notifications-rv92zmza.js → approval-notifications-7qgkzkzx.js} +8 -8
  8. package/dist/{assistant-q7s7rm1q.js → assistant-p2yvhc3j.js} +37 -32
  9. package/dist/{boot-args-schema-g27kpzr1.js → boot-args-schema-ry6cb0p7.js} +1 -1
  10. package/dist/{boot-reembed-1mjs52nt.js → boot-reembed-2hkm3vz2.js} +1 -1
  11. package/dist/{boot-reembed-m62dpdkg.js → boot-reembed-c9643ms3.js} +1 -1
  12. package/dist/{boot-scrub-sweep-ss1vcamw.js → boot-scrub-sweep-3ycxr51t.js} +2 -2
  13. package/dist/{boot-seeds-hwnvgbb3.js → boot-seeds-2hzvvzg0.js} +4 -4
  14. package/dist/{boxd-y0szhp0g.js → boxd-9py3x0jb.js} +2 -2
  15. package/dist/{claude-adapter-0rjmbhjk.js → claude-adapter-dnkww93e.js} +9 -9
  16. package/dist/{claude-managed-adapter-6k032agg.js → claude-managed-adapter-yk0cr5x6.js} +4 -4
  17. package/dist/{claude-managed-setup-6czvve8q.js → claude-managed-setup-4byxpp47.js} +5 -5
  18. package/dist/{claude-sdk-session-pr0znb81.js → claude-sdk-session-4wf3dbvs.js} +12467 -12285
  19. package/dist/{cli-t0n9svkb.js → cli-096aftq6.js} +12 -7
  20. package/dist/{cli-2wzkvfgm.js → cli-0e914dp9.js} +3 -3
  21. package/dist/{cli-vcpyttcw.js → cli-0h6m6z5g.js} +1 -1
  22. package/dist/{cli-q41qar56.js → cli-0k7ppk9k.js} +130 -8
  23. package/dist/{cli-ks06cd0n.js → cli-1nfabrt4.js} +8 -8
  24. package/dist/{cli-ebpq3c5z.js → cli-2414h5r9.js} +8 -8
  25. package/dist/{cli-nrt048ys.js → cli-24wervhz.js} +37 -0
  26. package/dist/{cli-pedm2kht.js → cli-2ayk9gn8.js} +2 -2
  27. package/dist/{cli-kr0jpw9c.js → cli-2ckwgs7q.js} +1 -1
  28. package/dist/{cli-evy3egte.js → cli-2savn6mm.js} +11 -100
  29. package/dist/{cli-n79j1vxc.js → cli-2zjxake1.js} +4 -4
  30. package/dist/{cli-z3x7h79n.js → cli-37p61fcg.js} +9 -9
  31. package/dist/{cli-2vp0z049.js → cli-39t9d248.js} +1 -1
  32. package/dist/{cli-sa02jsqt.js → cli-3mhdmcd4.js} +1 -1
  33. package/dist/{cli-34fygf87.js → cli-3wsabyt0.js} +2 -2
  34. package/dist/{cli-grbngev5.js → cli-466jjrwe.js} +11 -2
  35. package/dist/{cli-zxa1vmx7.js → cli-6ajyhxh7.js} +2 -2
  36. package/dist/{cli-bvamr9g0.js → cli-6yy4fepf.js} +4 -4
  37. package/dist/{cli-3vw6dd4g.js → cli-73rmgm45.js} +2 -2
  38. package/dist/{cli-8b4rpnwj.js → cli-7ca8hczj.js} +1 -1
  39. package/dist/{cli-0h8skzss.js → cli-7g5qj2ca.js} +4 -3
  40. package/dist/{cli-srre41gb.js → cli-7w1fs01q.js} +2 -2
  41. package/dist/{cli-tgc1kgg3.js → cli-84wxwt3z.js} +1 -1
  42. package/dist/{cli-4gaf3tx5.js → cli-84xn7bgz.js} +1 -1
  43. package/dist/{cli-s8dhq7rj.js → cli-879txsac.js} +5 -5
  44. package/dist/{cli-9n6g14vs.js → cli-8vbxjzk0.js} +3 -3
  45. package/dist/{cli-cmbb2t8a.js → cli-91amj3md.js} +2 -2
  46. package/dist/{cli-ewk3sg68.js → cli-930zbczq.js} +3 -3
  47. package/dist/{cli-6msnpj1z.js → cli-9fwznq4p.js} +10 -10
  48. package/dist/{cli-qmx8bnt4.js → cli-9j1t3kf6.js} +2 -2
  49. package/dist/{cli-t879ww0y.js → cli-9j47sgzy.js} +2 -2
  50. package/dist/{cli-0qt3epg4.js → cli-ad00h1st.js} +7 -7
  51. package/dist/{cli-avax5mp9.js → cli-adzmmcvf.js} +19 -7
  52. package/dist/{cli-ffn0a515.js → cli-ayxxkk3p.js} +68 -25
  53. package/dist/{cli-4vynxtrb.js → cli-bqfx72e6.js} +10 -3
  54. package/dist/{cli-887vhew6.js → cli-cbg0j1yt.js} +2716 -2643
  55. package/dist/{cli-fw67mnyc.js → cli-cg1q8ymp.js} +1 -1
  56. package/dist/{cli-he5nxaa8.js → cli-dw9rtjm3.js} +1 -1
  57. package/dist/{cli-emdfd8fh.js → cli-dy754erz.js} +9 -1
  58. package/dist/{cli-3860pmrq.js → cli-edxfzgah.js} +4 -4
  59. package/dist/{cli-v09eza21.js → cli-ejnhs815.js} +15 -15
  60. package/dist/{cli-k0nebh10.js → cli-enavhq6r.js} +1 -1
  61. package/dist/{cli-b42yfn17.js → cli-f2rwt43y.js} +13 -13
  62. package/dist/{cli-tvyt8w6n.js → cli-f9g96z28.js} +8 -8
  63. package/dist/{cli-zbbtp02a.js → cli-fww016hh.js} +457 -70
  64. package/dist/{cli-vbge4rsp.js → cli-g6a696c0.js} +4 -4
  65. package/dist/{cli-z1vam71h.js → cli-gc6b94tj.js} +2 -2
  66. package/dist/{cli-5tq15aa7.js → cli-gcyws2bp.js} +2 -2
  67. package/dist/{cli-srktrbby.js → cli-hzhv7yac.js} +1 -1
  68. package/dist/{cli-cp163xga.js → cli-jcnc5ret.js} +44 -32
  69. package/dist/{cli-j69pzrrz.js → cli-jgq9xptq.js} +5 -5
  70. package/dist/{cli-kwj3131p.js → cli-jwnac23b.js} +1 -1
  71. package/dist/{cli-wzecestt.js → cli-kc7vd07m.js} +616 -289
  72. package/dist/{cli-8pd1t17c.js → cli-kg63yp1r.js} +14 -14
  73. package/dist/{cli-zzq96q57.js → cli-krk8y8c7.js} +727 -139
  74. package/dist/{cli-5web09sb.js → cli-m0ea8ggd.js} +8 -10
  75. package/dist/{cli-qrvk9nka.js → cli-md4tn21h.js} +13 -13
  76. package/dist/{cli-1jq2em7b.js → cli-mv8ft7b0.js} +10 -9
  77. package/dist/{cli-ryem5cfq.js → cli-mw1tmn3x.js} +217 -27
  78. package/dist/{cli-abby987g.js → cli-njvpngc6.js} +3 -3
  79. package/dist/{cli-55h8m1x3.js → cli-phe2vcw5.js} +6 -6
  80. package/dist/{cli-prz1p3ft.js → cli-pq0kv31y.js} +5 -5
  81. package/dist/{cli-q1h041y8.js → cli-q457ga28.js} +6 -6
  82. package/dist/{cli-z40t85ms.js → cli-q5n3deaf.js} +1 -1
  83. package/dist/{cli-7ypg8hka.js → cli-qkbevqer.js} +3 -3
  84. package/dist/{cli-f9xw9pr4.js → cli-qrwjk4xy.js} +5 -5
  85. package/dist/{cli-kezzteka.js → cli-r04ve9xw.js} +1 -1
  86. package/dist/{cli-zntvmqmm.js → cli-r495stwd.js} +2 -2
  87. package/dist/{cli-1kvcsd2f.js → cli-r9d2tya0.js} +71 -3
  88. package/dist/{cli-ybte1fqc.js → cli-rp1n2xpd.js} +1 -1
  89. package/dist/{cli-sejvnjvw.js → cli-rs1rzwp4.js} +1 -1
  90. package/dist/{cli-94mxerrp.js → cli-rzbsh6bw.js} +1 -1
  91. package/dist/{cli-94gx6ze9.js → cli-s4pccby1.js} +1 -1
  92. package/dist/{cli-hd5bm1e1.js → cli-shyhb4t5.js} +10 -10
  93. package/dist/{cli-r3dxpmyt.js → cli-srq69pn1.js} +1 -1
  94. package/dist/{cli-7r9tvk8v.js → cli-tc165vrb.js} +8 -3
  95. package/dist/{cli-ced4azn1.js → cli-v4z5v3jd.js} +298 -80
  96. package/dist/{cli-ehg90jd1.js → cli-vxmmttmt.js} +55 -50
  97. package/dist/{cli-tt7dkwjj.js → cli-w4bvtxet.js} +7 -7
  98. package/dist/{cli-x2adbg4j.js → cli-wd7b5hgc.js} +1 -1
  99. package/dist/{cli-htb5bpz2.js → cli-wvbaq052.js} +1 -1
  100. package/dist/{cli-ywy8yz6t.js → cli-wvgg7r4j.js} +2 -2
  101. package/dist/{cli-19d6v8er.js → cli-wym6rxgt.js} +165 -6
  102. package/dist/{cli-f7b9nyvk.js → cli-yd7e590v.js} +12 -12
  103. package/dist/{cli-69zzpjgh.js → cli-yjb3cddd.js} +1 -1
  104. package/dist/{cli-5n9w2xzx.js → cli-z8t4485r.js} +2 -2
  105. package/dist/{cli-jdq3jmny.js → cli-ze1ndjs4.js} +4 -6
  106. package/dist/cli.js +28 -28
  107. package/dist/{codex-adapter-bn7eaxk5.js → codex-adapter-eq61radw.js} +8 -8
  108. package/dist/{codex-hook-nnmezjg9.js → codex-hook-8nmepvz6.js} +3 -3
  109. package/dist/{codex-login-ktfg1cxk.js → codex-login-vbd9707w.js} +1 -1
  110. package/dist/{codex-session-runner-j1e9hffc.js → codex-session-runner-rfx355h4.js} +9 -9
  111. package/dist/{commands-amhpafrr.js → commands-d1z0sx62.js} +3 -3
  112. package/dist/{controller-tw7g10j2.js → controller-9hz6d8x3.js} +4 -4
  113. package/dist/{controllers-connect-2ssqz7f4.js → controllers-connect-tz07d2xr.js} +24 -25
  114. package/dist/core-dynsv289.js +41 -0
  115. package/dist/{cursor-adapter-d6knjmwa.js → cursor-adapter-ef22ze3j.js} +2 -2
  116. package/dist/{db-fd6xxm77.js → db-gd81d68c.js} +3 -3
  117. package/dist/{db-sc59379z.js → db-vrckks6q.js} +4 -2
  118. package/dist/{devin-adapter-3bp6rape.js → devin-adapter-kdt6a2bh.js} +1 -1
  119. package/dist/{dispatcher-a2gdqz8c.js → dispatcher-76as8w2t.js} +21 -22
  120. package/dist/{docker-a59g3ebm.js → docker-51ta7jsh.js} +2 -2
  121. package/dist/dsh-adapter-ypfvcdyz.js +11 -0
  122. package/dist/{e2b-cn7cvjqy.js → e2b-05kn3kpq.js} +16 -5
  123. package/dist/{e2b-qnxyfea6.js → e2b-dm9r8hpy.js} +3 -3
  124. package/dist/{easter-egg-3d-a0pphy71.js → easter-egg-3d-sg21j15g.js} +1 -1
  125. package/dist/{embedding-space-qepzrach.js → embedding-space-zsdw37bb.js} +13 -23
  126. package/dist/{embeddings-d7vr881x.js → embeddings-p4e3e1m6.js} +1 -1
  127. package/dist/{event-bus-7gbsr0g4.js → event-bus-tvf2grf4.js} +1 -1
  128. package/dist/{execute-6afts2bn.js → execute-nztd0af0.js} +1 -1
  129. package/dist/{external-channel-881zq1x4.js → external-channel-717yzn4d.js} +2 -2
  130. package/dist/fx-adapter-9k0hptnz.js +20 -0
  131. package/dist/grok-adapter-skdj2pce.js +20 -0
  132. package/dist/handlers-5btjqkz6.js +39 -0
  133. package/dist/{heartbeat-4c022m6a.js → heartbeat-vfb1gy84.js} +24 -25
  134. package/dist/{hook-a7eh6zty.js → hook-ctz0xmp3.js} +11 -11
  135. package/dist/{hook-4k84x499.js → hook-eh52p7yd.js} +6 -6
  136. package/dist/{http-6aw5wanc.js → http-zregegrx.js} +784 -166
  137. package/dist/{index-xhad0n8m.js → index-5kx15d19.js} +1 -1
  138. package/dist/index-7w8p6em0.js +41 -0
  139. package/dist/index-evay0xyk.js +17 -0
  140. package/dist/{index-yq9hhhhy.js → index-fdym6ryb.js} +25 -26
  141. package/dist/{index-3j803vnb.js → index-mtnbhe12.js} +20533 -19786
  142. package/dist/index-vz4semsx.js +38 -0
  143. package/dist/{index-z2g9469g.js → index-x9qf8dg7.js} +108 -28
  144. package/dist/index-y3s0xp2v.js +43 -0
  145. package/dist/{k8s-36gfn847.js → k8s-ejkk0aw7.js} +2 -2
  146. package/dist/{keepalive-zhbmztqw.js → keepalive-zdqay870.js} +4 -5
  147. package/dist/lead-6cscw8a5.js +82 -0
  148. package/dist/{maintenance-rsp0591h.js → maintenance-t5ndg11m.js} +1 -1
  149. package/dist/{node-rxte5hc6.js → node-jkdd5w7m.js} +1 -1
  150. package/dist/{oauth-refresh-sweep-w3cqmxq7.js → oauth-refresh-sweep-y9zyd7t6.js} +3 -4
  151. package/dist/{object-webhooks-331hay92.js → object-webhooks-mkca91s0.js} +7 -7
  152. package/dist/{onboard-n2w80m2n.js → onboard-ss995244.js} +11 -9
  153. package/dist/{opencode-adapter-z98127cz.js → opencode-adapter-mwpz0278.js} +8 -8
  154. package/dist/{otel-impl-xsk35tvf.js → otel-impl-6n6vva3x.js} +2 -2
  155. package/dist/{pending-2e6trkxd.js → pending-2sxh1t6j.js} +22 -23
  156. package/dist/{pi-mono-adapter-wh6yndtm.js → pi-mono-adapter-sfb7zy43.js} +13 -13
  157. package/dist/{pricing-refresh-9355dj1t.js → pricing-refresh-h79bg4cf.js} +2 -2
  158. package/dist/{rbac-roles-8eajw4s6.js → rbac-roles-ckq0czp4.js} +2 -2
  159. package/dist/{rbac-roles-58y3m912.js → rbac-roles-jg2e260w.js} +3 -3
  160. package/dist/{render-v2-7gskkmd4.js → render-v2-ymbshmn0.js} +7 -7
  161. package/dist/{resume-0drnmpja.js → resume-jdhnt4jk.js} +10 -10
  162. package/dist/{runtime-d2tcmqte.js → runtime-y28jhhnf.js} +1 -1
  163. package/dist/{session-access-0ztys6bd.js → session-access-k4ta5hvp.js} +5 -5
  164. package/dist/{session-source-backfill-cdm5s046.js → session-source-backfill-528j4s8j.js} +3 -3
  165. package/dist/{setup-pqwb9tcc.js → setup-d6pj82fr.js} +15 -6
  166. package/dist/thread-buffer-9w6x5zec.js +40 -0
  167. package/dist/{tree-visibility-rwz67mje.js → tree-visibility-kjxv3nxk.js} +2 -2
  168. package/dist/{user-merge-jobs-mxrhamwt.js → user-merge-jobs-rabbncf6.js} +3 -3
  169. package/dist/{virtual-modules-71y1gsmg.js → virtual-modules-22k51txd.js} +3 -3
  170. package/dist/{work-objects-3k4ykt9j.js → work-objects-xtjbar3r.js} +26 -30
  171. package/dist/{worker-follow-up-y0h64xpr.js → worker-follow-up-fg48vk6d.js} +21 -22
  172. package/dist/worker-g4aj93dt.js +82 -0
  173. package/dist/{x-d27jj7z7.js → x-vfsqypht.js} +2 -2
  174. package/openapi.json +247 -20
  175. package/package.json +10 -10
  176. package/src/apps/definition.ts +76 -24
  177. package/src/apps/row-store.ts +67 -0
  178. package/src/apps/script-types.ts +131 -21
  179. package/src/apps/store.ts +4 -1
  180. package/src/be/db/script-runs.ts +33 -0
  181. package/src/be/db/slack-card-groups.ts +147 -0
  182. package/src/be/db/slack-trees.ts +26 -0
  183. package/src/be/db/task-idempotency.ts +63 -0
  184. package/src/be/db/tasks/read.ts +2 -0
  185. package/src/be/db/tasks/write.ts +4 -2
  186. package/src/be/db/workflow-idempotency.ts +6 -1
  187. package/src/be/db/workflows/read.ts +79 -0
  188. package/src/be/db.ts +51 -147
  189. package/src/be/improvements.ts +24 -2
  190. package/src/be/mcp-proxy.ts +45 -11
  191. package/src/be/memory/embedding-space.ts +10 -20
  192. package/src/be/memory/index.ts +35 -0
  193. package/src/be/memory/providers/openai-embedding.ts +10 -0
  194. package/src/be/migrations/348_task_deferred_until.sql +4 -0
  195. package/src/be/migrations/354_durable_objects.sql +9 -0
  196. package/src/be/migrations/356_slack_outcome_card_groups.sql +14 -0
  197. package/src/be/migrations/357_task_idempotency_keys.sql +27 -0
  198. package/src/be/migrations/362_favorites_app.sql +36 -0
  199. package/src/be/repo-checked-update.ts +58 -5
  200. package/src/be/requester-timezone.ts +10 -0
  201. package/src/be/script-connections.ts +5 -1
  202. package/src/be/script-credential-broker.ts +29 -2
  203. package/src/be/scripts/durable.ts +204 -0
  204. package/src/be/scripts/extract-schema.ts +29 -4
  205. package/src/be/scripts/run-credential.ts +1 -8
  206. package/src/be/scripts/typecheck.ts +32 -7
  207. package/src/be/seed-scripts/catalog/memory-eval.ts +11 -2
  208. package/src/be/seed-scripts/catalog/tool-usage.ts +27 -8
  209. package/src/be/swarm-config-guard.ts +87 -7
  210. package/src/be/users.ts +33 -12
  211. package/src/comb/review-batch.ts +16 -5
  212. package/src/commands/context-preamble.ts +237 -0
  213. package/src/commands/e2b.ts +14 -0
  214. package/src/commands/entrypoint-mcp-config.ts +231 -0
  215. package/src/commands/onboard/agent-fs-version.ts +1 -1
  216. package/src/commands/onboard/compose-generator.ts +2 -1
  217. package/src/commands/onboard/env-generator.ts +16 -7
  218. package/src/commands/runner.ts +23 -7
  219. package/src/commands/setup.tsx +17 -3
  220. package/src/extensions/contract-types.generated.ts +1 -1
  221. package/src/hooks/hook.ts +8 -2
  222. package/src/hooks/native-tool-hooks.ts +4 -2
  223. package/src/http/apps.ts +82 -42
  224. package/src/http/comb.ts +21 -5
  225. package/src/http/config.ts +8 -4
  226. package/src/http/heartbeat.ts +5 -0
  227. package/src/http/index.ts +12 -6
  228. package/src/http/kv.ts +7 -5
  229. package/src/http/mcp-oauth.ts +16 -0
  230. package/src/http/mcp-servers.ts +43 -3
  231. package/src/http/memory.ts +28 -1
  232. package/src/http/metrics.ts +11 -4
  233. package/src/http/onboarding.ts +12 -1
  234. package/src/http/repos.ts +27 -11
  235. package/src/http/request-principal.ts +27 -1
  236. package/src/http/schedules.ts +36 -8
  237. package/src/http/script-connection-proxy.ts +3 -1
  238. package/src/http/script-runs.ts +21 -10
  239. package/src/http/scripts.ts +177 -26
  240. package/src/http/session-cost-recompute.ts +9 -4
  241. package/src/http/skills.ts +70 -0
  242. package/src/http/status.ts +2 -0
  243. package/src/http/tasks.ts +92 -14
  244. package/src/http/trackers/jira.ts +18 -3
  245. package/src/http/trackers/linear.ts +3 -0
  246. package/src/kv-limits.ts +2 -0
  247. package/src/kv-reserved-namespaces.ts +25 -2
  248. package/src/prompts/session-templates.ts +49 -0
  249. package/src/prompts/session-turns.ts +30 -0
  250. package/src/providers/amp-adapter.ts +1 -1
  251. package/src/providers/claude-managed-adapter.ts +14 -0
  252. package/src/providers/claude-sdk-session.ts +14 -1
  253. package/src/providers/cursor-adapter.ts +1 -1
  254. package/src/providers/dsh-adapter.ts +1 -1
  255. package/src/providers/opencode-adapter.ts +3 -5
  256. package/src/providers/runtime-dependencies.ts +11 -8
  257. package/src/rbac/legacy-policy.ts +7 -0
  258. package/src/rbac/permissions.ts +27 -0
  259. package/src/scheduler/scheduler.ts +36 -18
  260. package/src/script-workflows/executor.ts +37 -8
  261. package/src/script-workflows/supervisor.ts +14 -0
  262. package/src/scripts-runtime/ctx.ts +5 -1
  263. package/src/scripts-runtime/durable-object-base.ts +19 -0
  264. package/src/scripts-runtime/eval-harness.ts +46 -1
  265. package/src/scripts-runtime/executors/native.ts +13 -1
  266. package/src/scripts-runtime/executors/quickjs-bundle.ts +20 -1
  267. package/src/scripts-runtime/executors/quickjs-prelude.ts +40 -1
  268. package/src/scripts-runtime/executors/quickjs-runner.ts +26 -3
  269. package/src/scripts-runtime/executors/quickjs-worker.ts +2 -1
  270. package/src/scripts-runtime/executors/types.ts +26 -0
  271. package/src/scripts-runtime/extract-signature.ts +96 -1
  272. package/src/scripts-runtime/loader.ts +11 -5
  273. package/src/scripts-runtime/mcp-client.ts +1 -1
  274. package/src/scripts-runtime/sdk-allowlist.ts +1 -0
  275. package/src/scripts-runtime/swarm-config.ts +7 -0
  276. package/src/scripts-runtime/swarm-sdk.ts +4 -1
  277. package/src/scripts-runtime/types/stdlib.d.ts +19 -0
  278. package/src/scripts-runtime/types/swarm-extension.d.ts +1 -0
  279. package/src/scripts-runtime/types/swarm-sdk.d.ts +19 -0
  280. package/src/slack/actions.ts +24 -0
  281. package/src/slack/assistant.ts +8 -0
  282. package/src/slack/blocks.ts +35 -0
  283. package/src/slack/channel-activity.ts +7 -0
  284. package/src/slack/enrich.ts +46 -54
  285. package/src/slack/files.ts +173 -23
  286. package/src/slack/handlers.test.ts +17 -19
  287. package/src/slack/handlers.ts +15 -14
  288. package/src/slack/render-v2.ts +264 -19
  289. package/src/slack/responses.ts +61 -5
  290. package/src/slack/session-mirror.ts +10 -5
  291. package/src/slack/task-output.ts +25 -14
  292. package/src/slack/templates.ts +9 -0
  293. package/src/slack/thread-participants.ts +64 -24
  294. package/src/slack/watcher.ts +4 -4
  295. package/src/slack/work-objects.ts +1 -1
  296. package/src/stdio.ts +5 -0
  297. package/src/tests/agents-list-model-display.test.ts +4 -0
  298. package/src/tests/apps-script-types.test.ts +63 -16
  299. package/src/tests/apps-sort-order.test.ts +87 -0
  300. package/src/tests/bedrock-model-groups.test.ts +4 -0
  301. package/src/tests/channel-activity.test.ts +9 -0
  302. package/src/tests/chatgpt-subscription-model-groups.test.ts +4 -0
  303. package/src/tests/claude-hook-output.test.ts +2 -0
  304. package/src/tests/claude-managed-adapter.test.ts +15 -3
  305. package/src/tests/claude-sdk-stderr.test.ts +28 -0
  306. package/src/tests/codex-gpt6-release.test.ts +4 -0
  307. package/src/tests/comb-review-batch.test.ts +17 -4
  308. package/src/tests/comb-status.test.ts +1 -0
  309. package/src/tests/db-client.test.ts +11 -5
  310. package/src/tests/db-task-read-contract.test.ts +1 -0
  311. package/src/tests/db-task-write-contract.test.ts +2 -2
  312. package/src/tests/defer-task.test.ts +23 -1
  313. package/src/tests/dsh-adapter.test.ts +1 -1
  314. package/src/tests/e2b-dispatch.test.ts +13 -1
  315. package/src/tests/entrypoint-mcp-config.test.ts +642 -0
  316. package/src/tests/fixtures/onboard/content.env.txt +2 -2
  317. package/src/tests/fixtures/onboard/dev.env.txt +2 -2
  318. package/src/tests/fixtures/onboard/full-all.env.txt +2 -2
  319. package/src/tests/fixtures/onboard/full.env.txt +2 -2
  320. package/src/tests/fixtures/onboard/research.env.txt +2 -2
  321. package/src/tests/fixtures/onboard/solo.env.txt +2 -2
  322. package/src/tests/fixtures/runner-missing-dependency.ts +2 -1
  323. package/src/tests/fx-adapter.test.ts +4 -5
  324. package/src/tests/hook-mcp-config-precedence.test.ts +59 -0
  325. package/src/tests/hook-ping-me-order.test.ts +1 -0
  326. package/src/tests/hook-runtime-close.test.ts +1 -0
  327. package/src/tests/improvements-payload.test.ts +2 -2
  328. package/src/tests/model-groups-live-catalog.test.ts +4 -0
  329. package/src/tests/oauth-credential-bindings.test.ts +8 -3
  330. package/src/tests/oauth-refresh-failure.test.ts +15 -3
  331. package/src/tests/onboard-env.test.ts +1 -1
  332. package/src/tests/openai-compatible-providers.test.ts +5 -0
  333. package/src/tests/openapi-route-headers.test.ts +2 -1
  334. package/src/tests/opus-5-5-registry.test.ts +4 -0
  335. package/src/tests/provider-runtime-dependencies.test.ts +26 -15
  336. package/src/tests/routing-affinity-inventory.test.ts +11 -0
  337. package/src/tests/runner-context-preamble.test.ts +202 -0
  338. package/src/tests/runner-repo-clone-args.test.ts +116 -0
  339. package/src/tests/scheduler-occurrence.test.ts +60 -9
  340. package/src/tests/script-connections-mcp.test.ts +6 -3
  341. package/src/tests/script-connections.test.ts +4 -0
  342. package/src/tests/scripts-namespaces.test.ts +3 -1
  343. package/src/tests/secret-scrubber.test.ts +8 -2
  344. package/src/tests/session-cost-recompute-unit.test.ts +39 -0
  345. package/src/tests/session-costs-recompute-all-providers.test.ts +6 -3
  346. package/src/tests/session-route-posture.test.ts +7 -1
  347. package/src/tests/slack-file-tools-attachments.test.ts +14 -9
  348. package/src/tests/slack-identity-resolution.test.ts +10 -3
  349. package/src/tests/slack-inline-output.test.ts +10 -8
  350. package/src/tests/slack-render-v2.test.ts +9 -4
  351. package/src/tests/slack-steering.test.ts +8 -2
  352. package/src/tests/slack-thread-participants.test.ts +11 -1
  353. package/src/tests/sonnet-5-5-registry.test.ts +4 -0
  354. package/src/tests/swarm-config-encryption.test.ts +5 -8
  355. package/src/tests/ui-spec-script-actions-config.test.ts +7 -3
  356. package/src/tests/workflow-triggers-v2.test.ts +35 -11
  357. package/src/tools/app-patch.ts +6 -2
  358. package/src/tools/app-upsert.ts +8 -4
  359. package/src/tools/defer-task.ts +17 -77
  360. package/src/tools/kv/kv-get.ts +2 -0
  361. package/src/tools/kv/kv-list.ts +11 -5
  362. package/src/tools/kv/kv-set.ts +1 -3
  363. package/src/tools/repos/update-repo.ts +37 -19
  364. package/src/tools/schedules/run-schedule-now.ts +21 -1
  365. package/src/tools/script-apis.ts +9 -4
  366. package/src/tools/script-common.ts +2 -2
  367. package/src/tools/script-run.ts +8 -0
  368. package/src/tools/script-upsert.ts +1 -1
  369. package/src/tools/slack-download-file.ts +15 -12
  370. package/src/tools/slack-post.ts +7 -1
  371. package/src/tools/slack-read.ts +3 -1
  372. package/src/tools/slack-reply.ts +16 -0
  373. package/src/tools/slack-start-thread.ts +8 -1
  374. package/src/tools/slack-upload-file.ts +99 -96
  375. package/src/tools/swarm-config/set-config.ts +3 -1
  376. package/src/tools/swarm-x.ts +0 -2
  377. package/src/tools/utils.ts +3 -0
  378. package/src/types.ts +8 -2
  379. package/src/utils/constants.ts +20 -0
  380. package/src/utils/deferral-time.ts +61 -0
  381. package/src/utils/request-auth-context.ts +15 -16
  382. package/src/utils/secret-scrubber.ts +1 -1
  383. package/src/workflows/engine.ts +6 -11
  384. package/src/workflows/executors/swarm-script.ts +0 -2
  385. package/src/workflows/foreach-driver.ts +6 -12
  386. package/src/workflows/input.ts +24 -1
  387. package/src/workflows/node-timeout.ts +18 -0
  388. package/src/workflows/retry-poller.ts +2 -1
  389. package/src/workflows/triggers.ts +21 -11
  390. package/src/x/composio.ts +10 -1
  391. package/templates/skills/apps/SKILL.md +4 -2
  392. package/templates/skills/apps/content.md +4 -2
  393. package/templates/skills/code-quality/content.md +4 -4
  394. package/templates/skills/scheduled-task-resilience/SKILL.md +2 -0
  395. package/templates/skills/scheduled-task-resilience/content.md +2 -0
  396. package/templates/skills/swarm-docs/content.md +7 -0
  397. package/templates/skills/swarm-scripts/SKILL.md +44 -0
  398. package/templates/skills/swarm-scripts/content.md +44 -0
  399. package/dist/acp-adapter-tbt61zkm.js +0 -17
  400. package/dist/cli-b9ygp1kz.js +0 -459
  401. package/dist/cli-kj0hyr43.js +0 -51
  402. package/dist/cli-m8f4379k.js +0 -173
  403. package/dist/core-bwp98v4w.js +0 -42
  404. package/dist/dsh-adapter-43ygwqn7.js +0 -9
  405. package/dist/fx-adapter-cr2hq17y.js +0 -20
  406. package/dist/grok-adapter-ayddnbsc.js +0 -20
  407. package/dist/handlers-7ghs84x2.js +0 -41
  408. package/dist/index-dtt0d634.js +0 -44
  409. package/dist/index-hmszyqkk.js +0 -42
  410. package/dist/index-j6rm1rtn.js +0 -39
  411. package/dist/index-rwwhsmjg.js +0 -13
  412. package/dist/lead-g2j4q39z.js +0 -83
  413. package/dist/thread-buffer-epx3san4.js +0 -42
  414. package/dist/worker-09gqn9xy.js +0 -83
@@ -2,6 +2,14 @@ import { AsyncLocalStorage } from "node:async_hooks";
2
2
  import type { IncomingMessage } from "node:http";
3
3
  import type { User } from "../types";
4
4
 
5
+ /** Provenance carried by a script run's credential. */
6
+ export type ScriptRunProvenance = {
7
+ sourceStepId?: string;
8
+ sourceScriptRunId?: string;
9
+ objectChain?: string[];
10
+ depth?: number;
11
+ };
12
+
5
13
  export type HttpRequestAuth = (
6
14
  | { kind: "operator"; fingerprint: string }
7
15
  /**
@@ -14,7 +22,7 @@ export type HttpRequestAuth = (
14
22
  | { kind: "guest" }
15
23
  | { kind: "controller"; controllerId: string; tokenId: string; expiresAt: string }
16
24
  /** Session token bound to an ACP task, a worker runtime, or only its agent (aseph_ prefix). */
17
- | {
25
+ | ({
18
26
  kind: "agent";
19
27
  tokenKind: "task" | "runtime" | "agent";
20
28
  agentId: string;
@@ -22,14 +30,7 @@ export type HttpRequestAuth = (
22
30
  runtimeId: string | null;
23
31
  tokenId: string;
24
32
  expiresAt: string;
25
- /**
26
- * Set on a script run's per-run token (`mintScriptRunToken`): the
27
- * swarm-script workflow step that started the run, and the run's own
28
- * `script_runs` row. Rows the request creates are stamped with them.
29
- */
30
- sourceStepId?: string | null;
31
- sourceScriptRunId?: string | null;
32
- }
33
+ } & ScriptRunProvenance)
33
34
  ) & {
34
35
  /** Verified page context for agent-scoped operations. This does not identify the viewer. */
35
36
  page?: { id: string; executionAgentId: string };
@@ -104,19 +105,17 @@ export function getCurrentRequestUserId(): string | undefined {
104
105
  return authUserId(getCurrentRequestAuth());
105
106
  }
106
107
 
107
- /** Where the current request's script run came from, when it presents a script-run token. */
108
- export type RunProvenance = { sourceStepId: string | null; sourceScriptRunId: string | null };
109
-
110
108
  /**
111
109
  * Provenance of the current request: set only when it authenticated with a
112
110
  * script run's per-run token that recorded a step or a script run. Async work
113
111
  * started inside the request inherits it (the workflow engine continuing a run
114
112
  * it triggered), so callers stamp only rows a script can create directly.
115
113
  */
116
- export function getCurrentRunProvenance(): RunProvenance | null {
114
+ export function getCurrentRunProvenance(): ScriptRunProvenance | null {
117
115
  const auth = getCurrentRequestAuth();
118
116
  if (auth?.kind !== "agent") return null;
119
- const sourceStepId = auth.sourceStepId ?? null;
120
- const sourceScriptRunId = auth.sourceScriptRunId ?? null;
121
- return sourceStepId || sourceScriptRunId ? { sourceStepId, sourceScriptRunId } : null;
117
+ const { sourceStepId, sourceScriptRunId, objectChain, depth } = auth;
118
+ return sourceStepId || sourceScriptRunId || objectChain !== undefined || depth
119
+ ? { sourceStepId, sourceScriptRunId, objectChain, depth }
120
+ : null;
122
121
  }
@@ -61,7 +61,7 @@ import { GITLEAKS_RULES } from "./secret-rules.generated";
61
61
  * LangSmith, CircleCI, Google `AQ.`, HubSpot, New Relic and Sentry DSN
62
62
  * shapes; pass 4 redacts a PEM private key cut off before its END line.
63
63
  */
64
- export const SCRUBBER_RULES_VERSION = 15;
64
+ export const SCRUBBER_RULES_VERSION = 16;
65
65
 
66
66
  /** Env-var names that are always considered secrets, even without suffix hints. */
67
67
  const SENSITIVE_KEY_EXACT = new Set<string>([
@@ -57,7 +57,7 @@ import {
57
57
  import { getSecretInputKeys, redactSecretsForStorage, resolveInputs } from "./input";
58
58
  import { validateJsonSchema } from "./json-schema-validator";
59
59
  import { getMaxWorkflowStepsPerRun } from "./limits";
60
- import { resolveNodeTimeoutMs, startStepDeadline } from "./node-timeout";
60
+ import { runWithNodeDeadline } from "./node-timeout";
61
61
  import { findWorkflowReadinessProblems, formatReadinessRunError } from "./readiness";
62
62
  import {
63
63
  hasOwedSuccessors,
@@ -1127,18 +1127,13 @@ async function runClaimedStep(
1127
1127
  inputCtx: interpolationCtx,
1128
1128
  };
1129
1129
 
1130
- const deadline = startStepDeadline(resolveNodeTimeoutMs(node));
1131
-
1132
1130
  let result: Awaited<ReturnType<typeof executor.run>>;
1133
1131
  try {
1134
- result = await Promise.race([
1135
- executor.run({
1136
- config: interpolatedConfig,
1137
- context: executionCtx,
1138
- meta: { ...meta, signal: deadline.signal },
1139
- }),
1140
- deadline.expired,
1141
- ]).finally(deadline.clear);
1132
+ result = await runWithNodeDeadline(node, executor, {
1133
+ config: interpolatedConfig,
1134
+ context: executionCtx,
1135
+ meta,
1136
+ });
1142
1137
  } catch (err) {
1143
1138
  const errorMsg = err instanceof Error ? err.message : String(err);
1144
1139
 
@@ -18,7 +18,6 @@ import {
18
18
  MIN_SCRIPT_WALL_CLOCK_MS,
19
19
  } from "../../scripts-runtime/executors/types";
20
20
  import type { ExecutorMeta } from "../../types";
21
- import { getMcpBaseUrl } from "../../utils/constants";
22
21
  import { findInterpolationTokens } from "../../utils/template";
23
22
  import { BaseExecutor, type ExecutorResult } from "./base";
24
23
 
@@ -136,7 +135,6 @@ export class SwarmScriptExecutor extends BaseExecutor<
136
135
  fsMode: "none",
137
136
  executor: resolved.script.executor,
138
137
  agentId: agentId ?? "workflow",
139
- mcpBaseUrl: getMcpBaseUrl(),
140
138
  egressSecrets: credentials.egressSecrets,
141
139
  failedBindings: credentials.failedBindings,
142
140
  userConfig: credentials.userConfig,
@@ -47,7 +47,7 @@ import {
47
47
  settleForeachChild,
48
48
  } from "./foreach-join";
49
49
  import { getSecretInputKeys } from "./input";
50
- import { resolveNodeTimeoutMs, startStepDeadline } from "./node-timeout";
50
+ import { runWithNodeDeadline } from "./node-timeout";
51
51
  import { rebuildNodeExecutionInput } from "./step-input";
52
52
  import { claimAndOweWalk, type SuccessorWalkDebt } from "./successor-routing";
53
53
 
@@ -521,21 +521,15 @@ async function startChild(input: {
521
521
  }
522
522
 
523
523
  const executor = registry.get(bodyType);
524
- const deadline = startStepDeadline(resolveNodeTimeoutMs({ type: bodyType, config }));
525
524
  let result: Awaited<ReturnType<typeof executor.run>>;
526
525
  try {
527
- result = await Promise.race([
528
- executor.run({
529
- config,
530
- context: { ...ctx, ...bodyCtx },
531
- meta: { ...meta, stepId: child.id, nodeId: child.nodeId, signal: deadline.signal },
532
- }),
533
- deadline.expired,
534
- ]);
526
+ result = await runWithNodeDeadline({ type: bodyType, config }, executor, {
527
+ config,
528
+ context: { ...ctx, ...bodyCtx },
529
+ meta: { ...meta, stepId: child.id, nodeId: child.nodeId },
530
+ });
535
531
  } catch (err) {
536
532
  return { status: "failed", error: err instanceof Error ? err.message : String(err) };
537
- } finally {
538
- deadline.clear();
539
533
  }
540
534
 
541
535
  if (result.status === "failed") {
@@ -23,16 +23,39 @@ export async function resolveInputs(
23
23
  return resolved;
24
24
  }
25
25
 
26
+ /**
27
+ * The `${ENV_VAR}` names a workflow may read, from `WORKFLOW_INPUT_ENV_ALLOWLIST`
28
+ * (comma-separated, blanks ignored). Null means the variable is unset and imposes no
29
+ * restriction. An explicitly empty list allows no names. Read on every call, so a config
30
+ * reload applies at once.
31
+ */
32
+ export function workflowInputEnvAllowlist(): Set<string> | null {
33
+ const raw = process.env.WORKFLOW_INPUT_ENV_ALLOWLIST;
34
+ if (raw === undefined) return null;
35
+ const names = raw
36
+ .split(",")
37
+ .map((name) => name.trim())
38
+ .filter((name) => name.length > 0);
39
+ return new Set(names);
40
+ }
41
+
26
42
  /**
27
43
  * Resolve a single input value, supporting `${ENV_VAR}` and `secret.NAME`
28
44
  * references. A plain string is returned unchanged. Throws if a referenced
29
- * env var or swarm secret cannot be found.
45
+ * env var or swarm secret cannot be found, or if `WORKFLOW_INPUT_ENV_ALLOWLIST`
46
+ * is set and does not list the env var. This is the only place `${ENV_VAR}` is
47
+ * resolved: workflow input (`resolveInputs`) and webhook HMAC secrets both come here.
30
48
  */
31
49
  export async function resolveInputValue(value: string): Promise<string> {
32
50
  // Env var reference: ${MY_VAR}
33
51
  const envMatch = /^\$\{(.+)\}$/.exec(value);
34
52
  if (envMatch?.[1]) {
35
53
  const envName = envMatch[1];
54
+ const allowed = workflowInputEnvAllowlist();
55
+ // Checked before the read, so a name outside the list never touches process.env.
56
+ if (allowed && !allowed.has(envName)) {
57
+ throw new Error(`Environment variable "${envName}" is not in WORKFLOW_INPUT_ENV_ALLOWLIST`);
58
+ }
36
59
  const envValue = process.env[envName];
37
60
  if (envValue === undefined) {
38
61
  throw new Error(`Environment variable "${envName}" is not set`);
@@ -1,4 +1,5 @@
1
1
  import type { WorkflowNode } from "../types";
2
+ import type { BaseExecutor, ExecutorInput } from "./executors/base";
2
3
 
3
4
  /** Watchdog budget for a node that configures none. */
4
5
  export const DEFAULT_NODE_TIMEOUT_MS = 30_000;
@@ -49,3 +50,20 @@ export function startStepDeadline(timeoutMs: number): StepDeadline {
49
50
  });
50
51
  return { signal: controller.signal, expired, clear: () => clearTimeout(timer) };
51
52
  }
53
+
54
+ /** Give each executor invocation its own deadline, including retries. */
55
+ export async function runWithNodeDeadline(
56
+ node: Pick<WorkflowNode, "type" | "config">,
57
+ executor: BaseExecutor,
58
+ input: ExecutorInput,
59
+ ) {
60
+ const deadline = startStepDeadline(resolveNodeTimeoutMs(node));
61
+ try {
62
+ return await Promise.race([
63
+ executor.run({ ...input, meta: { ...input.meta, signal: deadline.signal } }),
64
+ deadline.expired,
65
+ ]);
66
+ } finally {
67
+ deadline.clear();
68
+ }
69
+ }
@@ -25,6 +25,7 @@ import type { AsyncExecutorResult } from "./executors/base";
25
25
  import type { ExecutorRegistry } from "./executors/registry";
26
26
  import { FOREACH_ITEMS_WAIT_FOR, parkAndDriveForeach, runForeachDrive } from "./foreach-driver";
27
27
  import { resolveForeachParent } from "./foreach-join";
28
+ import { runWithNodeDeadline } from "./node-timeout";
28
29
  import { rebuildNodeExecutionInput } from "./step-input";
29
30
  import { hasOwedSuccessors } from "./successor-routing";
30
31
  import { runStepValidation, validateOutputSchema } from "./validation";
@@ -124,7 +125,7 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
124
125
  };
125
126
 
126
127
  try {
127
- const result = await executor.run({
128
+ const result = await runWithNodeDeadline(node, executor, {
128
129
  config: interpolatedConfig,
129
130
  context: ctx,
130
131
  meta,
@@ -1,6 +1,12 @@
1
1
  import crypto from "node:crypto";
2
- import { getWorkflow, getWorkflowsByScheduleId, listWorkflows } from "../be/db";
2
+ import {
3
+ getWorkflow,
4
+ getWorkflowsByEventName,
5
+ getWorkflowsByScheduleId,
6
+ listWorkflows,
7
+ } from "../be/db";
3
8
  import type { ScheduledTask, TriggerConfig } from "../types";
9
+ import { scrubSecrets } from "../utils/secret-scrubber";
4
10
  import { startWorkflowExecution } from "./engine";
5
11
  import type { ExecutorRegistry } from "./executors/registry";
6
12
  import { resolveInputValue } from "./input";
@@ -300,25 +306,29 @@ export async function logOpenWebhookTriggers(): Promise<void> {
300
306
 
301
307
  /**
302
308
  * Start every enabled workflow subscribed to a named in-process event.
303
- * Returns the workflow run IDs in workflow-list order.
309
+ * Returns the workflow run IDs in workflow-list order. A failed subscriber
310
+ * start is logged without preventing delivery to the remaining subscribers.
304
311
  */
305
312
  export async function handleEventTrigger(
306
313
  eventName: string,
307
314
  payload: unknown,
308
315
  registry: ExecutorRegistry,
309
316
  ): Promise<string[]> {
310
- const workflows = (await listWorkflows({ enabled: true })).filter((workflow) =>
311
- workflow.triggers.some(
312
- (trigger) => trigger.type === "event" && trigger.eventName === eventName,
313
- ),
314
- );
317
+ const workflows = await getWorkflowsByEventName(eventName);
315
318
 
316
319
  const runIds: string[] = [];
317
320
  for (const workflow of workflows) {
318
- const runId = await startWorkflowExecution(workflow, payload, registry, {
319
- triggerType: "event",
320
- });
321
- runIds.push(runId);
321
+ try {
322
+ const runId = await startWorkflowExecution(workflow, payload, registry, {
323
+ triggerType: "event",
324
+ });
325
+ runIds.push(runId);
326
+ } catch (err) {
327
+ console.error(
328
+ `[workflows] Failed to start workflow ${workflow.id} for ${eventName} event trigger:`,
329
+ scrubSecrets(err instanceof Error ? err.message : String(err)),
330
+ );
331
+ }
322
332
  }
323
333
  return runIds;
324
334
  }
package/src/x/composio.ts CHANGED
@@ -86,6 +86,7 @@ export function parseComposioArgs(
86
86
  if ((method === "GET" || method === "HEAD") && parsed.body !== undefined) {
87
87
  throw new Error(`${method} requests cannot include --body`);
88
88
  }
89
+ buildComposioUrl(parsed.baseUrl, parsed.endpoint, []);
89
90
 
90
91
  return parsed;
91
92
  }
@@ -131,6 +132,8 @@ export async function executeComposioRequest(
131
132
  body: args.body === undefined ? undefined : JSON.stringify(args.body),
132
133
  headers,
133
134
  method: args.method,
135
+ // A redirect would carry the key header to the new host.
136
+ redirect: "manual",
134
137
  });
135
138
  } catch (err) {
136
139
  return {
@@ -183,9 +186,11 @@ export function composioArgsFromParts(input: {
183
186
  throw new Error(`${method} requests cannot include a body`);
184
187
  }
185
188
  assertRelativeComposioPath(input.endpoint);
189
+ const baseUrl = input.baseUrl || process.env.COMPOSIO_BASE_URL || DEFAULT_COMPOSIO_BASE_URL;
190
+ buildComposioUrl(baseUrl, input.endpoint, []);
186
191
 
187
192
  return {
188
- baseUrl: input.baseUrl || process.env.COMPOSIO_BASE_URL || DEFAULT_COMPOSIO_BASE_URL,
193
+ baseUrl,
189
194
  body: input.body,
190
195
  endpoint: input.endpoint,
191
196
  headers: input.headers ?? {},
@@ -228,6 +233,10 @@ function buildComposioUrl(
228
233
  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
229
234
  const cleanEndpoint = endpoint.replace(/^\/+/, "");
230
235
  const url = new URL(cleanEndpoint, normalizedBase);
236
+ // The key header is bound to the base URL's host: a path must not change it.
237
+ if (url.origin !== new URL(normalizedBase).origin) {
238
+ throw new Error("endpoint must be a Composio API path on the configured base URL");
239
+ }
231
240
  for (const [key, value] of query) {
232
241
  url.searchParams.append(key, value);
233
242
  }
@@ -34,6 +34,8 @@ Swarm Apps are persistent, agent-authored internal applications: a schema-backed
34
34
 
35
35
  For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch` -> if rejected, fix every returned `issues[]` entry (`path` + `message`) and retry. Validation happens before storage, so a rejected update leaves the saved app unchanged. Do not guess at the current definition or use `app-upsert` with a partial definition.
36
36
 
37
+ When refreshing row data, write only the diff: read the current rows with `app-rows-list`, then `app-row-patch` the changed rows, `app-rows-create` the new ones, and `app-row-delete` the removed ones. Do not delete every row and recreate it, or recreate the model: a large rewrite can be interrupted partway and leave the app half-populated.
38
+
37
39
  `app-patch` can also change `name`; omit `description` to preserve it or pass `description: null` to clear it.
38
40
 
39
41
  ### Reading an app's callable surface
@@ -179,7 +181,7 @@ When a schema patch reports stale page/query bindings, repair them in that same
179
181
 
180
182
  Optional top-level `layout: "sidebar"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.
181
183
 
182
- Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
184
+ Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-50 models, at most 100 actions, and at most 20 reusable elements; each declared model has 1-200 columns. Operators can change the model, column and action caps per swarm (`APPS_MAX_MODELS`, `APPS_MAX_COLUMNS_PER_MODEL`, `APPS_MAX_ACTIONS`, 1-1000 each); the save error names the current cap. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
183
185
 
184
186
  ### Reusable elements
185
187
 
@@ -411,7 +413,7 @@ Use a task action named Tackle when a person should hand one issue row to the sw
411
413
 
412
414
  For direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.
413
415
 
414
- Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
416
+ Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. A script is typechecked against only the apps it names (literal app id or `App_<Name>`). Types are budgeted at 1 MiB per app and 4 MiB for all the apps one script names. An app past a budget loses its types (calls still work, untyped): `app-upsert` and `app-patch` warn when the app is over the per-app budget, and `script-upsert` warns for each untyped app the script names. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
415
417
 
416
418
  ### Pages, routes, and page trees
417
419
 
@@ -29,6 +29,8 @@ Swarm Apps are persistent, agent-authored internal applications: a schema-backed
29
29
 
30
30
  For every edit: `app-get` -> modify the smallest coherent subtree -> `app-patch` -> if rejected, fix every returned `issues[]` entry (`path` + `message`) and retry. Validation happens before storage, so a rejected update leaves the saved app unchanged. Do not guess at the current definition or use `app-upsert` with a partial definition.
31
31
 
32
+ When refreshing row data, write only the diff: read the current rows with `app-rows-list`, then `app-row-patch` the changed rows, `app-rows-create` the new ones, and `app-row-delete` the removed ones. Do not delete every row and recreate it, or recreate the model: a large rewrite can be interrupted partway and leave the app half-populated.
33
+
32
34
  `app-patch` can also change `name`; omit `description` to preserve it or pass `description: null` to clear it.
33
35
 
34
36
  ### Reading an app's callable surface
@@ -174,7 +176,7 @@ When a schema patch reports stale page/query bindings, repair them in that same
174
176
 
175
177
  Optional top-level `layout: "sidebar"` turns on the app shell (see Pages, routes, and page trees). Without it every page renders on the plain canvas, exactly as before.
176
178
 
177
- Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-10 models and at most 20 reusable elements; each declared model has 1-40 columns. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
179
+ Model, reusable-element, element-prop, query, action, column, page, and page-param names start with a lowercase letter, contain only letters, numbers, or underscores, and are at most 40 characters. A definition has 0-50 models, at most 100 actions, and at most 20 reusable elements; each declared model has 1-200 columns. Operators can change the model, column and action caps per swarm (`APPS_MAX_MODELS`, `APPS_MAX_COLUMNS_PER_MODEL`, `APPS_MAX_ACTIONS`, 1-1000 each); the save error names the current cap. Zero-model apps are valid for pure UI utilities as long as their pages and reusable elements validate.
178
180
 
179
181
  ### Reusable elements
180
182
 
@@ -406,7 +408,7 @@ Use a task action named Tackle when a person should hand one issue row to the sw
406
408
 
407
409
  For direct MCP calls, `app-query` accepts `{ appId, query, params? }` and returns rows from that declared named query; every supplied param must be referenced by a `$param` filter in that query. Use it when an agent needs to read app state without scraping the UI.
408
410
 
409
- Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
411
+ Saved scripts use the generated SDK name `ctx.swarm.app_query({ appId, query, params? })`. Use `app_query` in scripts or workflows that turn current app rows into reports, digests, or follow-up work. Saved scripts also get generated per-app types automatically: each app contributes an `App_<Name>` namespace with one row interface per model (enum columns as literal unions) and a typed `app_query` overload per named query, all visible via `script-query-types`. A script is typechecked against only the apps it names (literal app id or `App_<Name>`). Types are budgeted at 1 MiB per app and 4 MiB for all the apps one script names. An app past a budget loses its types (calls still work, untyped): `app-upsert` and `app-patch` warn when the app is over the per-app budget, and `script-upsert` warns for each untyped app the script names. Scripts can create, list, get, patch, and delete rows with the seven row tools. Actions remain REST/MCP-only and have no script SDK method.
410
412
 
411
413
  ### Pages, routes, and page trees
412
414
 
@@ -17,7 +17,7 @@ The task's `vcsProvider` field or the remote URL tells you the provider.
17
17
 
18
18
  ## Before you push
19
19
 
20
- 1. Run every command in the Repository Guidelines section "PR Checks" of your system prompt, one after the other. When no guidelines exist, run the checklist in the repo's CLAUDE.md. When neither exists, ask the lead before you push.
20
+ 1. Run every command in the Repository Guidelines section "PR Checks" of your system prompt, one after the other. Follow each check's own scope: a check the guidelines run once before the PR opens does not rerun on later fix pushes. When no guidelines exist, run the checklist in the repo's CLAUDE.md. When neither exists, ask the lead before you push.
21
21
  2. A failing check: fix the cause and run the check again. Push only when every check passes.
22
22
  3. Git hooks stay on. `--no-verify` and any other bypass flag are out.
23
23
  4. `main` and `master` are never force-pushed.
@@ -38,9 +38,9 @@ A workflow or task brief that opens a PR names this section instead of restating
38
38
 
39
39
  ## After you open a PR
40
40
 
41
- 1. Wait about 30 seconds, then read CI: `gh pr checks <number>` or `glab mr view --json pipelines`.
42
- 2. Red CI: read the failing job, fix, push, read CI again. Repeat until green.
43
- 3. Put the PR URL and the CI status in your task output.
41
+ 1. Put the PR URL and the head SHA in your task output.
42
+ 2. When the Repository Guidelines or a repo skill say the deployment handles red CI, review rounds and merge-queue ejections with workflows, your task ends here. Do not wait for CI: no `gh pr checks --watch`, `gh run watch` or sleep loops. A red check or a review round comes back to you as a new task.
43
+ 3. Otherwise, wait about 30 seconds, then read CI: `gh pr checks <number>` or `glab mr view --json pipelines`. Red CI: read the failing job, fix, push, read CI again. Repeat until green, and put the CI status in your task output.
44
44
 
45
45
  ## Merge policy
46
46
 
@@ -7,6 +7,8 @@ description: Guardrails for polling, scheduled jobs, and long-running external o
7
7
 
8
8
  Use these rules whenever a scheduled or regular task polls or waits on a long-running operation. They prevent heartbeat collisions, lost work, duplicate delivery, and sessions that fail after holding an external job open too long.
9
9
 
10
+ Before you poll a pull request's CI at all, check whether you need to. When the Repository Guidelines or a repo skill say workflows handle red CI, review rounds and merge-queue ejections, end the task at push instead (`code-quality`, "After you open a PR"). The rules below cover the waits that remain.
11
+
10
12
  ## Rule 1 — Never use `ScheduleWakeup` with `delaySeconds >= 300`
11
13
 
12
14
  The runtime heartbeat staleness threshold may sit near the same window as the model prompt-cache TTL. Sleeping for five minutes or longer can therefore look like a dead worker and cause the heartbeat sweep to fail the task mid-poll.
@@ -2,6 +2,8 @@
2
2
 
3
3
  Use these rules whenever a scheduled or regular task polls or waits on a long-running operation. They prevent heartbeat collisions, lost work, duplicate delivery, and sessions that fail after holding an external job open too long.
4
4
 
5
+ Before you poll a pull request's CI at all, check whether you need to. When the Repository Guidelines or a repo skill say workflows handle red CI, review rounds and merge-queue ejections, end the task at push instead (`code-quality`, "After you open a PR"). The rules below cover the waits that remain.
6
+
5
7
  ## Rule 1 — Never use `ScheduleWakeup` with `delaySeconds >= 300`
6
8
 
7
9
  The runtime heartbeat staleness threshold may sit near the same window as the model prompt-cache TTL. Sleeping for five minutes or longer can therefore look like a dead worker and cause the heartbeat sweep to fail the task mid-poll.
@@ -71,6 +71,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
71
71
  - [Reviewing purchase order and supplier confirmation differences with AI agents](https://docs.agent-swarm.dev/docs/guides/supplier-order-confirmation-review). Reference.
72
72
  - [Reviewing marketplace partner payout discrepancies with AI agents](https://docs.agent-swarm.dev/docs/guides/marketplace-payout-exception-review). Reference.
73
73
  - [Preparing marketplace moderation appeals for human review with AI agents](https://docs.agent-swarm.dev/docs/guides/marketplace-moderation-appeals). Reference.
74
+ - [Preparing a suspected marketplace fraud alert for human investigation with AI agents](https://docs.agent-swarm.dev/docs/guides/marketplace-fraud-alert-investigation). Reference.
74
75
  - [Reviewing customer billing disputes with AI agents](https://docs.agent-swarm.dev/docs/guides/customer-billing-dispute-review). Reference.
75
76
  - [Preparing unmatched bank transactions for finance review with AI agents](https://docs.agent-swarm.dev/docs/guides/agent-assisted-bank-reconciliation-review). Reference.
76
77
  - [Reviewing a proposed customer pricing change with AI agents](https://docs.agent-swarm.dev/docs/guides/customer-pricing-change-review). Reference.
@@ -87,10 +88,14 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
87
88
  - [Coordinating a guest accessibility request between guest support and property operations with AI agents](https://docs.agent-swarm.dev/docs/guides/guest-accessibility-request-handoff). Reference.
88
89
  - [Reviewing supplier performance across delivery, quality and service records with AI agents](https://docs.agent-swarm.dev/docs/guides/supplier-performance-review). Reference.
89
90
  - [Reviewing a supplier ingredient specification change with AI agents](https://docs.agent-swarm.dev/docs/guides/food-supplier-ingredient-change-review). Reference.
91
+ - [Preparing a batch traceability packet for a mock recall with AI agents](https://docs.agent-swarm.dev/docs/guides/food-batch-traceability-exercise). Reference.
90
92
  - [Preparing a bid or no-bid review for an incoming RFP with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-rfp-bid-qualification). Reference.
93
+ - [Reviewing why sales opportunities were won or lost with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-win-loss-review). Reference.
91
94
  - [Preparing contractor credential expiry checks for human review with AI agents](https://docs.agent-swarm.dev/docs/guides/contractor-license-expiry-review). Reference.
92
95
  - [Coordinating a departing employee's access review across HR and IT with AI agents](https://docs.agent-swarm.dev/docs/guides/employee-offboarding-access-review). Reference.
96
+ - [Preparing workforce training completion evidence for human review with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-training-completion-evidence-review). Reference.
93
97
  - [Briefing sales and leadership on competitor changes with AI agents](https://docs.agent-swarm.dev/docs/guides/competitor-change-brief). Reference.
98
+ - [Preparing a business continuity tabletop exercise with AI agents](https://docs.agent-swarm.dev/docs/guides/business-continuity-tabletop-preparation). Reference.
94
99
  - [Deployment Guide](https://docs.agent-swarm.dev/docs/guides/deployment). When: Someone wants to run Agent Swarm on their own server with Docker Compose.
95
100
  - [One-click deploy](https://docs.agent-swarm.dev/docs/guides/one-click-deploy). When: Someone has no server yet and wants Agent Swarm running in the cloud with HTTPS.
96
101
  - [Kubernetes and Helm](https://docs.agent-swarm.dev/docs/guides/kubernetes). When: Someone wants to install Agent Swarm on Kubernetes.
@@ -101,6 +106,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
101
106
  - [Asset Namespaces](https://docs.agent-swarm.dev/docs/guides/asset-namespaces). Reference.
102
107
  - [agent-fs Co-deployment](https://docs.agent-swarm.dev/docs/guides/agent-fs-co-deployment). When: Someone wants shared persistent files for agents on a self-hosted swarm.
103
108
  - [Self-Hosted SSO](https://docs.agent-swarm.dev/docs/guides/self-hosted-sso). When: Someone wants their self-hosted swarm dashboard behind single sign-on.
109
+ - [Reviewing why actual demand differed from a forecast with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-demand-forecast-accuracy-review). Reference.
104
110
  - [AI operations governance for small companies](https://docs.agent-swarm.dev/docs/guides/ai-operations-governance). Reference.
105
111
  - [Repo merge policy](https://docs.agent-swarm.dev/docs/guides/repo-merge-policy). Reference.
106
112
  - [E2B Provider Smoke Tests](https://docs.agent-swarm.dev/docs/guides/e2b-provider-smoke-tests). Reference.
@@ -143,6 +149,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
143
149
  - [Runtime pools (beta)](https://docs.agent-swarm.dev/docs/guides/runtime-pools). Reference.
144
150
  - [boxd runtime provider](https://docs.agent-swarm.dev/docs/guides/boxd-runtime-provider). Reference.
145
151
  - [Coordinating delivery delay investigations between operations and support with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-delivery-delay-handoff). Reference.
152
+ - [Investigating a payroll discrepancy for human review with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-payroll-discrepancy-review). Reference.
146
153
  - [Preparing a service capacity planning brief with AI agents](https://docs.agent-swarm.dev/docs/guides/ai-service-capacity-planning). Reference.
147
154
  - [Preparing a property maintenance request for human triage with AI agents](https://docs.agent-swarm.dev/docs/guides/maintenance-work-order-triage). Reference.
148
155
  - [Reviewing customer help content for conflicts with AI agents](https://docs.agent-swarm.dev/docs/guides/support-knowledge-conflict-review). Reference.
@@ -101,6 +101,7 @@ The route runs the same typecheck and scope rules as the tool.
101
101
  - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `retry`, `Redacted`.
102
102
  - Retries: `ctx.swarm` calls retry a 429 on any call, and a 502/503/504 or network error on reads and on writes that send an idempotency key (such as `workflow_trigger` with `idempotencyKey`), within about 5 s. `ctx.stdlib.fetch` retries a 429 on any method and a 502/503/504 or network error on GET, HEAD, OPTIONS, PUT and DELETE. A POST or PATCH retries those only with an `Idempotency-Key` header: pass `retry: { idempotencyKey: true }` to send one UUID on every attempt. The key prevents a duplicate only when the server dedupes by it. `retry: false` makes one attempt. Wrap anything else, sync or async, in `ctx.stdlib.retry(fn, { retries, minDelayMs, maxDelayMs, budgetMs, retryOn })`; it rethrows the last error or returns the last result when attempts run out.
103
103
  - `ctx.logger`: `log`, `warn`, `error`. Keep logs short.
104
+ - `ctx.caller`: who started this run. `{ kind: "agent", agentId }` for a direct call, `{ kind: "script", agentId }` for a call from another script. Frozen.
104
105
 
105
106
  ### Files and shell
106
107
 
@@ -126,6 +127,49 @@ const { stdout, exitCode } = await ctx.sh("grep -rn TODO /afs/notes | sort | hea
126
127
  - Each `ctx.step.agentTask` step is a normal worker task (`taskType: "script-run-step"`). When it finishes, the lead gets the usual "Worker task completed — review needed" follow-up, even while the run is still awaiting that step. The step config has no `followUpConfig` field, so a value passed there is dropped. Let the script's own judge step be the gate and close those follow-ups with a one-line accept.
127
128
  - When a crash supersedes an in-flight step and resumes it as a new task, the run does not follow the new task id: it can stay `failed` (for example `write EPIPE`) while the resumed task completes. Check the resumed task's output before you re-launch the run.
128
129
 
130
+ ### Durable objects
131
+
132
+ A durable object is a named instance of a global script class. Each instance keeps its own JSON state between calls. Only one call runs on an instance at a time, so you do not need your own KV locks.
133
+
134
+ ```ts
135
+ import { DurableObject } from "swarm-sdk";
136
+
137
+ export default class Counter extends DurableObject<{ n: number }> {
138
+ initialState() { return { n: 0 }; }
139
+ async add(args: { by: number }) { this.state.n += args.by; return this.state.n; }
140
+ }
141
+ ```
142
+
143
+ Save it with `script_upsert` in `scope: "global"`. The API refuses a DurableObject class in agent scope and in an inline `script_run`. Call one instance by id:
144
+
145
+ ```ts
146
+ script_run({ name: "counter", object: { id: "team-a", method: "add" }, args: { by: 2 } })
147
+ // → result: 2, object: { id: "team-a", stateVersion: 1, destroyed: false }
148
+ ```
149
+
150
+ - **Methods**: each callable method takes `(args, ctx)` and returns a JSON value. You cannot call `constructor`, `initialState`, `migrate`, `destroy`, a name that starts with `_`, a static method, a getter or an arrow-function field. The API refuses such a call before it runs any code.
151
+ - **First call**: an id with no state starts from `initialState()`.
152
+ - **State rules**:
153
+ - `this.state` must be JSON, at most 2 MiB.
154
+ - The API saves it only when the method returns without an error. A thrown error keeps the old state.
155
+ - The API saves `this.state` as it is when the method returns. A change made later, by work the method did not await, is lost.
156
+ - **Versions**: every call runs the latest saved version of the script. When the stored state comes from an older version, `migrate(state, fromVersion)` runs once before the method, if you define it.
157
+ - **Destroy**: `this.destroy()` deletes the state when the method returns. The next call on that id starts again from `initialState()`.
158
+ - **Idle expiry**: `static idleTtlSec = 3600` deletes the state after 1 hour with no call. Without it, state is kept until `destroy()`.
159
+ - **Read the state**: `kv_get({ namespace: "durable:<scriptId>", key: "state/<id>" })` returns `{ codeVersion, stateVersion, state }`, with secrets scrubbed. KV writes on a `durable:` namespace are refused. Change state only through a method.
160
+ - **Errors**:
161
+ - `object busy` (409): another call held the instance for 30 s (5 s for a call from a script). Retry the call later. Do not loop.
162
+ - `already in this call chain` (409): a method called its own instance, directly or through other scripts. Restructure the call. Do not retry.
163
+ - `call depth exceeds 16` (400): a chain of nested script runs is too deep.
164
+
165
+ | Cloudflare Durable Objects | Swarm durable objects |
166
+ |---|---|
167
+ | `this.ctx.storage` key-value API | One JSON `this.state` snapshot per instance |
168
+ | `fetch()` and RPC from a Worker | `script_run` with `object: { id, method }` |
169
+ | `env` bindings | `ctx` (the same `ctx` as other scripts), passed to each method |
170
+ | Alarms | Not available yet |
171
+ | Methods take any arguments | Methods take `(args, ctx)` |
172
+
129
173
  ## Inline script pattern
130
174
 
131
175
  ```typescript
@@ -96,6 +96,7 @@ The route runs the same typecheck and scope rules as the tool.
96
96
  - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `retry`, `Redacted`.
97
97
  - Retries: `ctx.swarm` calls retry a 429 on any call, and a 502/503/504 or network error on reads and on writes that send an idempotency key (such as `workflow_trigger` with `idempotencyKey`), within about 5 s. `ctx.stdlib.fetch` retries a 429 on any method and a 502/503/504 or network error on GET, HEAD, OPTIONS, PUT and DELETE. A POST or PATCH retries those only with an `Idempotency-Key` header: pass `retry: { idempotencyKey: true }` to send one UUID on every attempt. The key prevents a duplicate only when the server dedupes by it. `retry: false` makes one attempt. Wrap anything else, sync or async, in `ctx.stdlib.retry(fn, { retries, minDelayMs, maxDelayMs, budgetMs, retryOn })`; it rethrows the last error or returns the last result when attempts run out.
98
98
  - `ctx.logger`: `log`, `warn`, `error`. Keep logs short.
99
+ - `ctx.caller`: who started this run. `{ kind: "agent", agentId }` for a direct call, `{ kind: "script", agentId }` for a call from another script. Frozen.
99
100
 
100
101
  ### Files and shell
101
102
 
@@ -121,6 +122,49 @@ const { stdout, exitCode } = await ctx.sh("grep -rn TODO /afs/notes | sort | hea
121
122
  - Each `ctx.step.agentTask` step is a normal worker task (`taskType: "script-run-step"`). When it finishes, the lead gets the usual "Worker task completed — review needed" follow-up, even while the run is still awaiting that step. The step config has no `followUpConfig` field, so a value passed there is dropped. Let the script's own judge step be the gate and close those follow-ups with a one-line accept.
122
123
  - When a crash supersedes an in-flight step and resumes it as a new task, the run does not follow the new task id: it can stay `failed` (for example `write EPIPE`) while the resumed task completes. Check the resumed task's output before you re-launch the run.
123
124
 
125
+ ### Durable objects
126
+
127
+ A durable object is a named instance of a global script class. Each instance keeps its own JSON state between calls. Only one call runs on an instance at a time, so you do not need your own KV locks.
128
+
129
+ ```ts
130
+ import { DurableObject } from "swarm-sdk";
131
+
132
+ export default class Counter extends DurableObject<{ n: number }> {
133
+ initialState() { return { n: 0 }; }
134
+ async add(args: { by: number }) { this.state.n += args.by; return this.state.n; }
135
+ }
136
+ ```
137
+
138
+ Save it with `script_upsert` in `scope: "global"`. The API refuses a DurableObject class in agent scope and in an inline `script_run`. Call one instance by id:
139
+
140
+ ```ts
141
+ script_run({ name: "counter", object: { id: "team-a", method: "add" }, args: { by: 2 } })
142
+ // → result: 2, object: { id: "team-a", stateVersion: 1, destroyed: false }
143
+ ```
144
+
145
+ - **Methods**: each callable method takes `(args, ctx)` and returns a JSON value. You cannot call `constructor`, `initialState`, `migrate`, `destroy`, a name that starts with `_`, a static method, a getter or an arrow-function field. The API refuses such a call before it runs any code.
146
+ - **First call**: an id with no state starts from `initialState()`.
147
+ - **State rules**:
148
+ - `this.state` must be JSON, at most 2 MiB.
149
+ - The API saves it only when the method returns without an error. A thrown error keeps the old state.
150
+ - The API saves `this.state` as it is when the method returns. A change made later, by work the method did not await, is lost.
151
+ - **Versions**: every call runs the latest saved version of the script. When the stored state comes from an older version, `migrate(state, fromVersion)` runs once before the method, if you define it.
152
+ - **Destroy**: `this.destroy()` deletes the state when the method returns. The next call on that id starts again from `initialState()`.
153
+ - **Idle expiry**: `static idleTtlSec = 3600` deletes the state after 1 hour with no call. Without it, state is kept until `destroy()`.
154
+ - **Read the state**: `kv_get({ namespace: "durable:<scriptId>", key: "state/<id>" })` returns `{ codeVersion, stateVersion, state }`, with secrets scrubbed. KV writes on a `durable:` namespace are refused. Change state only through a method.
155
+ - **Errors**:
156
+ - `object busy` (409): another call held the instance for 30 s (5 s for a call from a script). Retry the call later. Do not loop.
157
+ - `already in this call chain` (409): a method called its own instance, directly or through other scripts. Restructure the call. Do not retry.
158
+ - `call depth exceeds 16` (400): a chain of nested script runs is too deep.
159
+
160
+ | Cloudflare Durable Objects | Swarm durable objects |
161
+ |---|---|
162
+ | `this.ctx.storage` key-value API | One JSON `this.state` snapshot per instance |
163
+ | `fetch()` and RPC from a Worker | `script_run` with `object: { id, method }` |
164
+ | `env` bindings | `ctx` (the same `ctx` as other scripts), passed to each method |
165
+ | Alarms | Not available yet |
166
+ | Methods take any arguments | Methods take `(args, ctx)` |
167
+
124
168
  ## Inline script pattern
125
169
 
126
170
  ```typescript
@@ -1,17 +0,0 @@
1
- import {
2
- ACPAdapter2
3
- } from "./cli-887vhew6.js";
4
- import"./cli-0qt3epg4.js";
5
- import"./cli-f7b9nyvk.js";
6
- import"./cli-prz1p3ft.js";
7
- import"./cli-1jq2em7b.js";
8
- import"./cli-k0nebh10.js";
9
- import"./cli-0h8skzss.js";
10
- import"./cli-srre41gb.js";
11
- import"./cli-0726awxw.js";
12
- import"./cli-zntvmqmm.js";
13
- import"./cli-9n6g14vs.js";
14
- import"./cli-ywy8yz6t.js";
15
- export {
16
- ACPAdapter2 as ACPAdapter
17
- };