@desplega.ai/agent-swarm 2.8.2 → 2.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 (558) hide show
  1. package/dist/acp-adapter-jqn86aam.js +16 -0
  2. package/dist/acp-targets-swxq55dr.js +23 -0
  3. package/dist/{actions-kxek041g.js → actions-pb678g3e.js} +22 -20
  4. package/dist/agent-fs-provision-dmhnc38q.js +27 -0
  5. package/dist/{amp-adapter-ce7jjke4.js → amp-adapter-3pa66q27.js} +3 -3
  6. package/dist/{anthropic-messages-jkva0zps.js → anthropic-messages-x2cp5fvf.js} +41 -41
  7. package/dist/{app-v6zz8yh0.js → app-17d12ev4.js} +6 -4
  8. package/dist/approval-notifications-h7vd9pmg.js +20 -0
  9. package/dist/{assistant-m0sw9xx2.js → assistant-t7k39ree.js} +56 -34
  10. package/dist/{azure-openai-responses-wgtqkbr3.js → azure-openai-responses-590s1eea.js} +10 -10
  11. package/dist/{boot-args-schema-66bk37wv.js → boot-args-schema-0gqmkfbe.js} +1 -1
  12. package/dist/{boot-reembed-edjpwsc1.js → boot-reembed-f064w382.js} +1 -1
  13. package/dist/{boot-reembed-y27n09tz.js → boot-reembed-n6anc01d.js} +1 -1
  14. package/dist/{boot-scrub-sweep-1xc35965.js → boot-scrub-sweep-ejd5dnrz.js} +84 -13
  15. package/dist/{boot-seeds-7hjj91qj.js → boot-seeds-f99fjs5q.js} +4 -4
  16. package/dist/{boxd-ent8ch04.js → boxd-wn235q80.js} +7 -7
  17. package/dist/claude-adapter-gvznwxgc.js +28 -0
  18. package/dist/{claude-managed-adapter-jh6c523j.js → claude-managed-adapter-pbrbvc64.js} +4 -4
  19. package/dist/{claude-managed-setup-y6z2perp.js → claude-managed-setup-kdxttvc3.js} +11 -11
  20. package/dist/{claude-sdk-session-vvya8wqk.js → claude-sdk-session-0t2teq6n.js} +9386 -9197
  21. package/dist/{cli-yjdgea32.js → cli-1jx0srjt.js} +17 -17
  22. package/dist/{cli-rmzsadkf.js → cli-1tvdx9t5.js} +2 -2
  23. package/dist/{cli-3vmb0n58.js → cli-25nstr34.js} +1 -1
  24. package/dist/{cli-959kp5h2.js → cli-2kg31ted.js} +45 -38
  25. package/dist/{cli-4vzgeta4.js → cli-2tnbc3gw.js} +375 -127
  26. package/dist/{cli-tekytdq9.js → cli-3zxdz9r7.js} +9 -9
  27. package/dist/{cli-bsywb58a.js → cli-4ghh072d.js} +16 -16
  28. package/dist/{cli-9mb2q6pb.js → cli-57pvhnyt.js} +4 -4
  29. package/dist/{cli-d84byzn8.js → cli-5a6pqy45.js} +441 -53
  30. package/dist/{cli-jrzkw01m.js → cli-5gpqgs8b.js} +2 -2
  31. package/dist/{cli-0cq8y6m7.js → cli-5gygrr67.js} +9 -9
  32. package/dist/{cli-z1w943va.js → cli-5kcmxwxv.js} +3 -3
  33. package/dist/{cli-3e875j5p.js → cli-5ntc4we6.js} +3189 -328
  34. package/dist/{cli-bst1vp7e.js → cli-5y2fvw4z.js} +13 -5
  35. package/dist/{cli-mrt48bx7.js → cli-6237rnyr.js} +1 -1
  36. package/dist/cli-6dp0jkfj.js +754 -0
  37. package/dist/{cli-b98a65ed.js → cli-7831nhaw.js} +5 -5
  38. package/dist/{cli-kjtwrhea.js → cli-7cgf614g.js} +10 -10
  39. package/dist/{cli-fwy8kfd6.js → cli-7fx9jyfs.js} +942 -63
  40. package/dist/{cli-28fq781p.js → cli-7zm3b3f5.js} +1 -1
  41. package/dist/{cli-v1dv1r37.js → cli-812paz57.js} +143 -9
  42. package/dist/{cli-837vfs2x.js → cli-8axx8vnw.js} +4 -4
  43. package/dist/cli-8x8y70av.js +103 -0
  44. package/dist/{cli-vj75tyaw.js → cli-95930z69.js} +15 -7
  45. package/dist/{cli-j24zbska.js → cli-9a2rtd77.js} +16 -14
  46. package/dist/cli-9ttx00s3.js +137 -0
  47. package/dist/{cli-6ek0hff4.js → cli-a9hfzg2r.js} +3 -3
  48. package/dist/{cli-dzpc6en0.js → cli-aa8s22gn.js} +19 -14
  49. package/dist/{cli-x1wa213s.js → cli-bk9v1xrv.js} +21 -21
  50. package/dist/{cli-a0z912j7.js → cli-c07v0qfa.js} +194 -75
  51. package/dist/{cli-1qkz151v.js → cli-c5cspahx.js} +28 -36
  52. package/dist/{cli-vdektqgf.js → cli-cw7mc1je.js} +4 -4
  53. package/dist/{cli-n6vtrcht.js → cli-dd37e0cm.js} +2 -2
  54. package/dist/cli-dqgnbnxs.js +132 -0
  55. package/dist/{cli-kc7v1nfv.js → cli-dx439zpg.js} +1 -1
  56. package/dist/{cli-q6mfk1ej.js → cli-dzzh58sy.js} +2 -2
  57. package/dist/{cli-f6bahpn5.js → cli-e9973bf0.js} +8 -6
  58. package/dist/{cli-2znm3dzj.js → cli-eds5xnsz.js} +2 -2
  59. package/dist/{cli-6rc5frdm.js → cli-eepnpee7.js} +34 -37
  60. package/dist/{cli-rvhdmjvt.js → cli-eg437b5p.js} +1 -1
  61. package/dist/cli-faf46gdq.js +714 -0
  62. package/dist/{cli-f4r3g076.js → cli-fgphc007.js} +2 -2
  63. package/dist/{cli-5y340nzn.js → cli-fnh4b12r.js} +24 -18
  64. package/dist/{cli-fsgttth8.js → cli-g0vv9dg4.js} +13 -13
  65. package/dist/{cli-e1p3n5gq.js → cli-g3zzby8t.js} +13 -13
  66. package/dist/{cli-3vjhs18n.js → cli-gabsjg8x.js} +3 -1
  67. package/dist/{cli-1pz0330a.js → cli-gddgcnav.js} +3 -3
  68. package/dist/{cli-97ae65rz.js → cli-h474mvp5.js} +11 -11
  69. package/dist/{cli-m88rpzkh.js → cli-hnamkvnc.js} +2 -2
  70. package/dist/{cli-8bpgbr8k.js → cli-j49yqpvh.js} +6 -6
  71. package/dist/{cli-w401b9tq.js → cli-jd3kxppb.js} +1 -1
  72. package/dist/{cli-m9s2qff2.js → cli-jg5txpm6.js} +187 -93
  73. package/dist/{cli-8aes17e4.js → cli-js8zrfyg.js} +3 -3
  74. package/dist/{cli-pfs8adn4.js → cli-k09cxm6m.js} +9 -7
  75. package/dist/{cli-q24n86d2.js → cli-k7pt28ad.js} +10 -3
  76. package/dist/{cli-zh9rsbqf.js → cli-kaa4bd7x.js} +11 -8
  77. package/dist/cli-kj0hyr43.js +51 -0
  78. package/dist/{cli-g70vxtjh.js → cli-kmvcm34h.js} +2 -2
  79. package/dist/{cli-t2tma8gb.js → cli-kqh27v2y.js} +2 -2
  80. package/dist/{cli-mxn1qvbn.js → cli-m1fbz2wj.js} +32 -57
  81. package/dist/{cli-2kvhc7x8.js → cli-mc1fx4xd.js} +51 -90
  82. package/dist/{cli-pchypa1s.js → cli-me4maa4j.js} +61 -6
  83. package/dist/{cli-504akrp9.js → cli-meydjstb.js} +3 -3
  84. package/dist/{cli-n30e0hcp.js → cli-mna6pmfx.js} +2 -2
  85. package/dist/cli-nhq5js1b.js +142 -0
  86. package/dist/cli-nmcpzbty.js +296 -0
  87. package/dist/cli-nr46j5pw.js +78 -0
  88. package/dist/{cli-5mrq3ake.js → cli-pn1v1pb0.js} +1 -1
  89. package/dist/{cli-f4e8r23x.js → cli-pwsax0vp.js} +11 -6
  90. package/dist/{cli-gyt3zydq.js → cli-pz1c00aa.js} +9 -754
  91. package/dist/{cli-eddnyg3t.js → cli-q2d3e1k1.js} +1 -1
  92. package/dist/{cli-fpjmegdb.js → cli-q8cfh1t9.js} +2 -2
  93. package/dist/{cli-vqva1teb.js → cli-qe909n63.js} +2 -2
  94. package/dist/{cli-2r0jcc3k.js → cli-qj39vrc6.js} +1 -1
  95. package/dist/{cli-0agcv1v5.js → cli-rqx70rcz.js} +2 -2
  96. package/dist/{cli-0jzra9ad.js → cli-rts1qvb4.js} +2 -2
  97. package/dist/{cli-3rkdne1h.js → cli-sn4pc4qx.js} +2 -2
  98. package/dist/{cli-98rwmcyc.js → cli-snxhtehz.js} +3 -3
  99. package/dist/{cli-d829z3xc.js → cli-spfz393q.js} +6 -6
  100. package/dist/{cli-6wj7p986.js → cli-spzkdgtg.js} +3 -3
  101. package/dist/{cli-m2z8jagn.js → cli-srtkr1h2.js} +18 -18
  102. package/dist/{cli-2gxeg5gr.js → cli-ssvdrk4y.js} +1 -1
  103. package/dist/{cli-jdknh18m.js → cli-svc803vq.js} +69 -816
  104. package/dist/{cli-7349va39.js → cli-t9ga4qmb.js} +935 -445
  105. package/dist/{cli-m5akxq8q.js → cli-vs9vdpy0.js} +1 -1
  106. package/dist/{cli-26ctbcdp.js → cli-vvgaz8t6.js} +93 -44
  107. package/dist/{cli-3sy2xags.js → cli-vw5x18yj.js} +39 -69
  108. package/dist/{cli-kchjb7qy.js → cli-w16kwbzw.js} +1 -1
  109. package/dist/cli-w7dxb2fj.js +921 -0
  110. package/dist/{cli-x6t50dmw.js → cli-wr1h0k28.js} +3 -3
  111. package/dist/{cli-d6521kb5.js → cli-x40a0w9j.js} +1 -1
  112. package/dist/{cli-k28wkapa.js → cli-xf1wn5ns.js} +2 -2
  113. package/dist/{cli-rh15cakt.js → cli-xwsm6xkr.js} +1 -1
  114. package/dist/{cli-rcecc3yq.js → cli-ymct0ycy.js} +321 -111
  115. package/dist/{cli-xzm9vcfg.js → cli-zg3z63x3.js} +2 -2
  116. package/dist/cli.js +29 -26
  117. package/dist/{codex-adapter-zerf5qsp.js → codex-adapter-44yq2fkn.js} +9 -9
  118. package/dist/{codex-hook-30gyhzxe.js → codex-hook-h1zb7cfk.js} +6 -6
  119. package/dist/{codex-login-bcda78ge.js → codex-login-cdyrr5y1.js} +1 -1
  120. package/dist/{codex-session-runner-89s304py.js → codex-session-runner-zbh26gbw.js} +10 -10
  121. package/dist/{commands-jeh1b51j.js → commands-54f02v5b.js} +3 -3
  122. package/dist/{controller-mctfbrse.js → controller-9gpwcdek.js} +6 -6
  123. package/dist/{controllers-connect-nxa1ddwn.js → controllers-connect-61re6k1n.js} +26 -25
  124. package/dist/{cursor-adapter-qj8vehv6.js → cursor-adapter-7e4g81vd.js} +2 -2
  125. package/dist/{db-b36qn6k3.js → db-dg2gc7fd.js} +17 -13
  126. package/dist/{db-2dvay0es.js → db-wnh0qjy1.js} +3 -3
  127. package/dist/{devin-adapter-xedz98zv.js → devin-adapter-zp4tqq53.js} +1 -1
  128. package/dist/{dispatcher-gndbta01.js → dispatcher-jrm24r43.js} +19 -18
  129. package/dist/{docker-866qpzt9.js → docker-9aq30pp2.js} +5 -5
  130. package/dist/{dsh-adapter-f75sz821.js → dsh-adapter-1yqk267c.js} +2 -2
  131. package/dist/{e2b-3gpc2n3w.js → e2b-3v1e745x.js} +6 -6
  132. package/dist/{e2b-jbm7mj93.js → e2b-sm28k0k3.js} +6 -6
  133. package/dist/{easter-egg-3d-533knw22.js → easter-egg-3d-r4h9cs9m.js} +1 -1
  134. package/dist/{embedding-space-4p05vb2x.js → embedding-space-bafjr5f7.js} +6 -6
  135. package/dist/{embeddings-m6768mgh.js → embeddings-7xmgqe0e.js} +1 -1
  136. package/dist/{event-bus-e66gh7cc.js → event-bus-xr83x566.js} +1 -1
  137. package/dist/{execute-b3mrb1mv.js → execute-d6jg5ns0.js} +1 -1
  138. package/dist/{external-channel-gjv3jne3.js → external-channel-frq1xvq2.js} +2 -2
  139. package/dist/fx-adapter-0zrkfbkd.js +19 -0
  140. package/dist/{getMachineId-bsd-nfgrzarv.js → getMachineId-bsd-637a7rbk.js} +3 -3
  141. package/dist/{getMachineId-darwin-wz886dsk.js → getMachineId-darwin-9vytrcnn.js} +3 -3
  142. package/dist/{getMachineId-linux-1nng3p1p.js → getMachineId-linux-mkzsvyyz.js} +3 -3
  143. package/dist/{getMachineId-unsupported-a0428vw9.js → getMachineId-unsupported-4cfs2n11.js} +3 -3
  144. package/dist/{getMachineId-win-h45922nq.js → getMachineId-win-154s3qma.js} +3 -3
  145. package/dist/{google-generative-ai-h7s3e9kk.js → google-generative-ai-hh7strj3.js} +1 -1
  146. package/dist/{google-vertex-fhxaafzw.js → google-vertex-fy5bw2pm.js} +5 -5
  147. package/dist/grok-adapter-3db1c538.js +19 -0
  148. package/dist/handlers-k22n8mnn.js +33 -0
  149. package/dist/{heartbeat-a1tv60gt.js → heartbeat-6bpa611t.js} +22 -21
  150. package/dist/{hook-8h5dzcgq.js → hook-hvm5nf46.js} +5 -5
  151. package/dist/{hook-cyaps9ba.js → hook-w12k146y.js} +14 -14
  152. package/dist/{http-t15mhbd9.js → http-43tthdvs.js} +5838 -2600
  153. package/dist/{index-d6wkh8ar.js → index-1f0vypbg.js} +2 -2
  154. package/dist/{index-enn321kd.js → index-42jq9yy3.js} +3 -3
  155. package/dist/{index-khe3gp0k.js → index-4b1q8kan.js} +20 -20
  156. package/dist/{index-hjhfk3ra.js → index-585gyczt.js} +1 -1
  157. package/dist/index-8xcyd3mc.js +33 -0
  158. package/dist/index-9sy2bh6n.js +38 -0
  159. package/dist/{index-2skqtd76.js → index-b24j7t2m.js} +30 -28
  160. package/dist/{index-gjwaqaq8.js → index-cret47a5.js} +6 -6
  161. package/dist/{index-qwj6ntem.js → index-e3krvkh2.js} +4 -4
  162. package/dist/{index-w1zqf680.js → index-fn054vsf.js} +1 -1
  163. package/dist/{index-qav6455f.js → index-ftywhyr0.js} +214 -152
  164. package/dist/{index-tvfafeyy.js → index-mhq4sh5w.js} +1 -1
  165. package/dist/index-tx9mc2ap.js +570 -0
  166. package/dist/index-wjd56k1v.js +34 -0
  167. package/dist/{keepalive-91s7hzrb.js → keepalive-rk0j0jvh.js} +4 -4
  168. package/dist/lead-atxf3q6e.js +72 -0
  169. package/dist/{maintenance-7pjmy5xy.js → maintenance-g6z6kaxw.js} +1 -1
  170. package/dist/{node-4c5jqxr3.js → node-7qsx5kvm.js} +1 -1
  171. package/dist/{node-252anz2h.js → node-jftbyawr.js} +4 -4
  172. package/dist/{node-ray25snp.js → node-zd6shky9.js} +3 -3
  173. package/dist/{oauth-refresh-sweep-rzqfm94j.js → oauth-refresh-sweep-2k3g2q4w.js} +3 -3
  174. package/dist/{onboard-74st7pag.js → onboard-6fdbvh3v.js} +8 -8
  175. package/dist/{openai-codex-responses-k9gapdze.js → openai-codex-responses-bkcd8pjj.js} +9 -9
  176. package/dist/{openai-responses-4d5dx3c7.js → openai-responses-gbh0wfqe.js} +13 -13
  177. package/dist/{opencode-adapter-arn7gm8q.js → opencode-adapter-fdbsvts7.js} +7 -7
  178. package/dist/{otel-impl-rnzey8cb.js → otel-impl-rvwtc09q.js} +110 -110
  179. package/dist/pending-sqkrb836.js +80 -0
  180. package/dist/{pi-mono-adapter-6mkwq64n.js → pi-mono-adapter-asqayqcg.js} +13 -13
  181. package/dist/{pricing-refresh-ha21jhk7.js → pricing-refresh-f5tkgmw2.js} +2 -2
  182. package/dist/{rbac-roles-wqhma4dr.js → rbac-roles-06s555fa.js} +3 -3
  183. package/dist/{rbac-roles-59dxachk.js → rbac-roles-szxsg8t1.js} +10 -3
  184. package/dist/{render-v2-14kpzx12.js → render-v2-103p266q.js} +4 -4
  185. package/dist/{resume-gsa5fb5f.js → resume-v7kjewt9.js} +8 -7
  186. package/dist/{runtime-1hv06jsn.js → runtime-f1gmk0b7.js} +1 -1
  187. package/dist/{session-access-skm7bnp6.js → session-access-6shev8ts.js} +4 -4
  188. package/dist/{session-source-backfill-pbqzbncv.js → session-source-backfill-bd7spzjd.js} +3 -3
  189. package/dist/{setup-5yermsem.js → setup-kmxmztdb.js} +1 -1
  190. package/dist/thread-buffer-4yz236d0.js +36 -0
  191. package/dist/{virtual-modules-gazyapte.js → virtual-modules-57eje5wy.js} +5 -5
  192. package/dist/{work-objects-xj0ck0w4.js → work-objects-zr47ygmf.js} +23 -21
  193. package/dist/{worker-follow-up-911xc0b8.js → worker-follow-up-grrr3fda.js} +19 -18
  194. package/dist/worker-p4hbtcy3.js +72 -0
  195. package/dist/{x-2fyrt5pp.js → x-wg164ss9.js} +2 -2
  196. package/openapi.json +4518 -2356
  197. package/package.json +11 -8
  198. package/plugin/commands/create-pr.md +1 -1
  199. package/plugin/pi-skills/create-pr/SKILL.md +1 -1
  200. package/src/apps/action-runner.ts +21 -1
  201. package/src/apps/catalog.generated.json +626 -17
  202. package/src/apps/page-validator.ts +314 -8
  203. package/src/assets/key.ts +6 -0
  204. package/src/be/agent-fs-user-keys.ts +186 -0
  205. package/src/be/audit-user.ts +27 -13
  206. package/src/be/automation-preflight.test.ts +14 -14
  207. package/src/be/automation-preflight.ts +24 -16
  208. package/src/be/boot-scrub-sweep.ts +143 -14
  209. package/src/be/caller-session-group.ts +86 -0
  210. package/src/be/checklist.ts +375 -0
  211. package/src/be/db/agents.ts +12 -1
  212. package/src/be/db/approvals.ts +26 -0
  213. package/src/be/db/session-moves.ts +23 -0
  214. package/src/be/db/session-tree.ts +78 -19
  215. package/src/be/db/tasks/eligibility-scan.ts +14 -0
  216. package/src/be/db/tasks/read.ts +33 -0
  217. package/src/be/db/tasks/slack-fold.ts +116 -0
  218. package/src/be/db/tasks/write.ts +34 -0
  219. package/src/be/db-queries/mcp-servers.ts +13 -0
  220. package/src/be/db-queries/oauth.ts +6 -0
  221. package/src/be/db-queries/task-artifacts.ts +10 -8
  222. package/src/be/db.ts +74 -22
  223. package/src/be/extensions/assets.ts +17 -13
  224. package/src/be/import/config.ts +54 -0
  225. package/src/be/import/dir-source.ts +372 -0
  226. package/src/be/import/index.ts +149 -0
  227. package/src/be/import/pending.ts +71 -0
  228. package/src/be/import/schema.ts +137 -0
  229. package/src/be/import/seeders.ts +462 -0
  230. package/src/be/migrations/289_automation_savings_daily.sql +47 -0
  231. package/src/be/migrations/291_task_slack_participants.sql +4 -0
  232. package/src/be/migrations/293_savings_component_links.sql +58 -0
  233. package/src/be/migrations/296_automation_savings_daily_read_index.sql +6 -0
  234. package/src/be/migrations/297_import_ownership.sql +34 -0
  235. package/src/be/migrations/301_favorites_key_type.sql +36 -0
  236. package/src/be/migrations/302_checklist_items.sql +23 -0
  237. package/src/be/model-profile-check.ts +10 -2
  238. package/src/be/multi-runtime.ts +8 -1
  239. package/src/be/rbac-roles.ts +8 -1
  240. package/src/be/runtime-pools/demand.ts +20 -2
  241. package/src/be/runtime-pools/reachability.ts +31 -0
  242. package/src/be/runtime-pools/routing.ts +8 -1
  243. package/src/be/runtime-pools/supervisor.ts +6 -7
  244. package/src/be/savings/compute.ts +511 -16
  245. package/src/be/savings/model.ts +282 -14
  246. package/src/be/savings/read.ts +1502 -0
  247. package/src/be/savings/rollup.ts +571 -0
  248. package/src/be/script-credential-broker.ts +2 -2
  249. package/src/be/scripts/run-credential.ts +15 -3
  250. package/src/be/scripts/typecheck.ts +90 -8
  251. package/src/be/seed/agent-fs-provision.ts +104 -19
  252. package/src/be/seed/index.ts +1 -1
  253. package/src/be/seed/registry.ts +27 -8
  254. package/src/be/seed/runner.ts +1 -1
  255. package/src/be/seed/schedules-seeder.ts +24 -6
  256. package/src/be/seed/seed-toggle.ts +32 -0
  257. package/src/be/seed/types.ts +6 -0
  258. package/src/be/seed-scripts/catalog/dreaming-gather.ts +2 -2
  259. package/src/be/seed-scripts/catalog/dreaming-learnings.ts +10 -2
  260. package/src/be/seed-scripts/catalog/dreaming-memtax-create.ts +70 -4
  261. package/src/be/steering.ts +27 -4
  262. package/src/be/swarm-config-guard.ts +38 -0
  263. package/src/be/task-citations.ts +8 -5
  264. package/src/be/users.ts +29 -2
  265. package/src/commands/onboard/agent-fs-version.ts +1 -1
  266. package/src/commands/runner.ts +219 -42
  267. package/src/e2b/env.ts +2 -0
  268. package/src/extensions/catalog.generated.json +17 -0
  269. package/src/extensions/contract-types.generated.ts +1 -1
  270. package/src/github/app.ts +10 -1
  271. package/src/github/handlers.ts +6 -3
  272. package/src/github/reactions.ts +12 -14
  273. package/src/heartbeat/heartbeat.ts +14 -4
  274. package/src/http/agents.ts +19 -10
  275. package/src/http/all-routes.ts +2 -0
  276. package/src/http/approval-requests.ts +24 -4
  277. package/src/http/apps.ts +69 -5
  278. package/src/http/checklist.ts +176 -0
  279. package/src/http/db-query-bounded.ts +256 -11
  280. package/src/http/db-query-shared.ts +9 -0
  281. package/src/http/favorites.ts +14 -2
  282. package/src/http/fs.ts +346 -1
  283. package/src/http/index.ts +37 -2
  284. package/src/http/kv.ts +13 -0
  285. package/src/http/mcp-oauth.ts +1 -1
  286. package/src/http/mcp-servers.ts +15 -2
  287. package/src/http/onboarding.ts +2 -9
  288. package/src/http/poll.ts +59 -1
  289. package/src/http/requested-by.ts +97 -1
  290. package/src/http/savings.ts +676 -190
  291. package/src/http/script-connections.ts +1 -0
  292. package/src/http/scripts.ts +26 -15
  293. package/src/http/sessions.ts +17 -0
  294. package/src/http/slack-events.ts +101 -0
  295. package/src/http/status.ts +25 -7
  296. package/src/http/task-requester.ts +46 -0
  297. package/src/http/tasks.ts +107 -42
  298. package/src/http/users.ts +14 -0
  299. package/src/http/webhooks.ts +15 -0
  300. package/src/integrations/cards/index.ts +151 -0
  301. package/src/integrations/chat-sdk/outbound.ts +39 -13
  302. package/src/integrations/chat-sdk/runtime.ts +7 -1
  303. package/src/integrations/chat-sdk/status.ts +17 -0
  304. package/src/integrations/chat-sdk/telegram-api.ts +6 -1
  305. package/src/kv-reserved-namespaces.ts +17 -2
  306. package/src/oauth/presets.ts +29 -2
  307. package/src/prompts/base-prompt.ts +17 -4
  308. package/src/prompts/session-templates.ts +163 -9
  309. package/src/providers/acp-targets.ts +2 -2
  310. package/src/providers/amp-adapter.ts +1 -1
  311. package/src/providers/claude-adapter.ts +0 -20
  312. package/src/providers/claude-flag-settings.ts +12 -10
  313. package/src/providers/claude-managed-adapter.ts +5 -1
  314. package/src/providers/codex-adapter.ts +10 -35
  315. package/src/providers/codex-app-server.ts +2 -11
  316. package/src/providers/opencode-adapter.ts +41 -31
  317. package/src/providers/runtime-dependencies.ts +158 -0
  318. package/src/rbac/legacy-policy.ts +2 -0
  319. package/src/rbac/permissions.ts +10 -1
  320. package/src/scheduler/scheduler.ts +20 -14
  321. package/src/scripts-runtime/credential-broker/default-bindings.ts +19 -11
  322. package/src/scripts-runtime/credential-broker/index.ts +1 -1
  323. package/src/scripts-runtime/ctx.ts +1 -1
  324. package/src/scripts-runtime/egress-secrets.ts +2 -2
  325. package/src/scripts-runtime/executors/quickjs-bundle.ts +1 -0
  326. package/src/scripts-runtime/executors/quickjs-prelude.ts +162 -2
  327. package/src/scripts-runtime/executors/quickjs-runner.ts +4 -1
  328. package/src/scripts-runtime/stdlib/fetch.ts +113 -15
  329. package/src/scripts-runtime/stdlib/index.ts +3 -1
  330. package/src/scripts-runtime/stdlib/retry.ts +174 -0
  331. package/src/scripts-runtime/swarm-sdk.ts +187 -17
  332. package/src/scripts-runtime/types/stdlib.d.ts +97 -8
  333. package/src/scripts-runtime/types/swarm-extension.d.ts +27 -1
  334. package/src/scripts-runtime/types/swarm-sdk.d.ts +71 -6
  335. package/src/server.ts +4 -4
  336. package/src/slack/actions.ts +1 -0
  337. package/src/slack/app.ts +87 -46
  338. package/src/slack/assistant.ts +35 -7
  339. package/src/slack/enrich.ts +144 -50
  340. package/src/slack/handlers.ts +43 -99
  341. package/src/slack/http-receiver.ts +284 -0
  342. package/src/slack/inbound-dispatch.ts +43 -7
  343. package/src/slack/inbound-files.ts +33 -14
  344. package/src/slack/message-text.ts +47 -4
  345. package/src/slack/render-v2.ts +2 -1
  346. package/src/slack/socket-ack.ts +17 -10
  347. package/src/slack/steering.ts +5 -0
  348. package/src/slack/templates.ts +9 -0
  349. package/src/slack/thread-buffer-store.ts +58 -0
  350. package/src/slack/thread-buffer.ts +367 -109
  351. package/src/slack/thread-participants.ts +187 -0
  352. package/src/tasks/context-key.ts +24 -0
  353. package/src/tasks/sibling-awareness.ts +13 -1
  354. package/src/tests/agent-fs-live-url.test.ts +15 -0
  355. package/src/tests/agent-fs-provision-seeder.test.ts +140 -0
  356. package/src/tests/agent-fs-user-keys.test.ts +483 -0
  357. package/src/tests/agentfs-proxy.test.ts +8 -8
  358. package/src/tests/approval-card-resolution.test.ts +396 -0
  359. package/src/tests/approval-requests-notifications.test.ts +1 -1
  360. package/src/tests/approval-respond-auth.test.ts +28 -0
  361. package/src/tests/apps-action-parent-task.test.ts +140 -0
  362. package/src/tests/apps-catalog-additions.test.ts +315 -0
  363. package/src/tests/apps-catalog-files.test.ts +114 -0
  364. package/src/tests/apps-catalog-hitl.test.ts +117 -0
  365. package/src/tests/apps-catalog-inputs.test.ts +86 -0
  366. package/src/tests/apps-catalog-table.test.ts +47 -0
  367. package/src/tests/apps-chart-shell.test.ts +1 -1
  368. package/src/tests/apps-element-assembly.test.ts +52 -3
  369. package/src/tests/apps-session-thread.test.ts +182 -0
  370. package/src/tests/asset-key-invariants.test.ts +14 -0
  371. package/src/tests/base-prompt.test.ts +108 -23
  372. package/src/tests/boot-scrub-sweep.test.ts +172 -0
  373. package/src/tests/caller-session-group.test.ts +199 -0
  374. package/src/tests/cards.test.ts +169 -0
  375. package/src/tests/chat-sdk-status-route.test.ts +16 -3
  376. package/src/tests/chat-sdk-telegram-token.test.ts +76 -0
  377. package/src/tests/chat-sdk-tools.test.ts +147 -0
  378. package/src/tests/checklist-nudge.test.ts +208 -0
  379. package/src/tests/checklist.test.ts +686 -0
  380. package/src/tests/claude-adapter-binary.test.ts +7 -1
  381. package/src/tests/claude-adapter.test.ts +10 -64
  382. package/src/tests/claude-flag-settings.test.ts +15 -11
  383. package/src/tests/claude-hook-credentials.test.ts +0 -1
  384. package/src/tests/claude-sdk-lifecycle.test.ts +5 -1
  385. package/src/tests/codex-adapter.test.ts +17 -78
  386. package/src/tests/codex-app-server.test.ts +16 -0
  387. package/src/tests/comb-config-guard.test.ts +21 -0
  388. package/src/tests/comb-default.test.ts +59 -97
  389. package/src/tests/comb-links.test.ts +86 -16
  390. package/src/tests/comb-status.test.ts +24 -27
  391. package/src/tests/create-page-tool.test.ts +101 -1
  392. package/src/tests/create-schedule-key.test.ts +105 -0
  393. package/src/tests/create-task-vcs-repo.test.ts +136 -0
  394. package/src/tests/credential-broker.test.ts +2 -2
  395. package/src/tests/db-query.test.ts +87 -1
  396. package/src/tests/db-task-read-contract.test.ts +3 -0
  397. package/src/tests/db-task-write-contract.test.ts +3 -1
  398. package/src/tests/docs-index-footprint.test.js +3 -3
  399. package/src/tests/dreaming-learnings.test.ts +104 -0
  400. package/src/tests/entrypoint-github-enterprise.test.ts +158 -0
  401. package/src/tests/extensions-assets.test.ts +7 -3
  402. package/src/tests/extensions-catalog.test.ts +1 -0
  403. package/src/tests/extensions-example-sql-admin-only.test.ts +198 -0
  404. package/src/tests/extensions-pre-task.test.ts +7 -5
  405. package/src/tests/extensions-steering.test.ts +14 -2
  406. package/src/tests/favorites-agent-fs-path.test.ts +124 -0
  407. package/src/tests/fetch-resolved-env.test.ts +115 -1
  408. package/src/tests/fixtures/import-package.ts +32 -0
  409. package/src/tests/fixtures/runner-missing-dependency.ts +129 -0
  410. package/src/tests/fs-routes.test.ts +505 -2
  411. package/src/tests/github-ghes-mock.test.ts +196 -0
  412. package/src/tests/github-host.test.ts +285 -0
  413. package/src/tests/heartbeat-supersede-resume.test.ts +73 -0
  414. package/src/tests/heartbeat.test.ts +56 -0
  415. package/src/tests/import-config.test.ts +209 -0
  416. package/src/tests/import.test.ts +464 -0
  417. package/src/tests/invites-http.test.ts +144 -1
  418. package/src/tests/kv-http.test.ts +11 -0
  419. package/src/tests/literal-matcher.test.ts +58 -0
  420. package/src/tests/mcp-oauth-manual-client.test.ts +1 -1
  421. package/src/tests/oauth-presets.test.ts +12 -0
  422. package/src/tests/opencode-adapter.test.ts +53 -6
  423. package/src/tests/pool-affinity.test.ts +50 -0
  424. package/src/tests/prompt-template-session.test.ts +69 -6
  425. package/src/tests/provider-registration.test.ts +2 -55
  426. package/src/tests/provider-runtime-dependencies.test.ts +212 -0
  427. package/src/tests/rbac-admission.test.ts +19 -0
  428. package/src/tests/rbac-charact-misc-tools.test.ts +31 -0
  429. package/src/tests/rbac-engine.test.ts +2 -0
  430. package/src/tests/rbac-roles.test.ts +2 -0
  431. package/src/tests/runner-missing-dependency.test.ts +61 -0
  432. package/src/tests/runner-requester-profile.test.ts +139 -1
  433. package/src/tests/runtime-pool-reachability.test.ts +135 -1
  434. package/src/tests/runtime-pool-routing.test.ts +52 -0
  435. package/src/tests/runtime-stale-threshold.test.ts +40 -0
  436. package/src/tests/savings-compound.test.ts +774 -0
  437. package/src/tests/savings-compute.test.ts +7 -198
  438. package/src/tests/savings-fleet-latency.test.ts +143 -0
  439. package/src/tests/savings-fleet-read.test.ts +195 -0
  440. package/src/tests/savings-fleet-scale.test.ts +222 -0
  441. package/src/tests/savings-fleet-slices.test.ts +122 -0
  442. package/src/tests/savings-model.test.ts +212 -0
  443. package/src/tests/savings-read.test.ts +408 -0
  444. package/src/tests/savings-rollup.test.ts +766 -0
  445. package/src/tests/savings-scripts.test.ts +617 -0
  446. package/src/tests/script-connections.test.ts +4 -0
  447. package/src/tests/script-executor-conformance.test.ts +481 -0
  448. package/src/tests/scripts-http.test.ts +55 -0
  449. package/src/tests/scripts-runtime-fetch.test.ts +2 -2
  450. package/src/tests/secret-rules.test.ts +124 -1
  451. package/src/tests/secret-scrub-gate.test.ts +257 -0
  452. package/src/tests/secret-scrubber.test.ts +1 -1
  453. package/src/tests/seed-registry.test.ts +142 -9
  454. package/src/tests/session-source-keys.test.ts +42 -1
  455. package/src/tests/sessions-move.test.ts +70 -0
  456. package/src/tests/sessions-tree.test.ts +98 -0
  457. package/src/tests/sessions.test.ts +69 -0
  458. package/src/tests/slack-config.test.ts +4 -18
  459. package/src/tests/slack-dm-implicit-mention.test.ts +20 -1
  460. package/src/tests/slack-http-receiver.test.ts +472 -0
  461. package/src/tests/slack-identity-resolution.test.ts +23 -0
  462. package/src/tests/slack-inbound-files.test.ts +2 -1
  463. package/src/tests/slack-inbound-logging.test.ts +64 -0
  464. package/src/tests/slack-leave-thread.test.ts +1 -1
  465. package/src/tests/slack-message-text.test.ts +104 -0
  466. package/src/tests/slack-mode-lifecycle.test.ts +6 -4
  467. package/src/tests/slack-render-v2.test.ts +48 -0
  468. package/src/tests/slack-skip-reaction.test.ts +2 -2
  469. package/src/tests/slack-steering.test.ts +22 -10
  470. package/src/tests/slack-thread-buffer-context.test.ts +1 -1
  471. package/src/tests/slack-thread-buffer-fold.test.ts +417 -0
  472. package/src/tests/slack-thread-buffer-restore.test.ts +198 -0
  473. package/src/tests/slack-thread-buffer-startup-restore.test.ts +86 -0
  474. package/src/tests/slack-thread-buffer.test.ts +34 -34
  475. package/src/tests/slack-thread-participants.test.ts +447 -0
  476. package/src/tests/slack-tool-blocks.test.ts +167 -0
  477. package/src/tests/status.test.ts +32 -6
  478. package/src/tests/steering-core.test.ts +13 -0
  479. package/src/tests/steering-enabled.test.ts +7 -1
  480. package/src/tests/steering-promotion.test.ts +24 -0
  481. package/src/tests/swarm-config-reserved-keys.test.ts +17 -0
  482. package/src/tests/system-one-hosts-ui-mirror.test.ts +67 -0
  483. package/src/tests/task-artifacts.test.ts +50 -0
  484. package/src/tests/task-session-prompts.test.ts +95 -1
  485. package/src/tests/tool-annotations.test.ts +30 -0
  486. package/src/tests/workflow-system-one-extraction.test.ts +149 -1
  487. package/src/tools/chat-post.ts +19 -4
  488. package/src/tools/chat-reply.ts +20 -4
  489. package/src/tools/create-page.ts +21 -4
  490. package/src/tools/get-swarm.ts +18 -2
  491. package/src/tools/join-swarm.ts +2 -1
  492. package/src/tools/kv/kv-write-auth.ts +17 -1
  493. package/src/tools/schedules/create-schedule.ts +22 -4
  494. package/src/tools/slack-post.ts +40 -7
  495. package/src/tools/slack-reply.ts +50 -14
  496. package/src/types.ts +74 -2
  497. package/src/utils/constants.ts +60 -138
  498. package/src/utils/github-host.ts +217 -0
  499. package/src/utils/github-pull-request.ts +8 -5
  500. package/src/utils/literal-matcher.ts +118 -0
  501. package/src/utils/mcp-server-fetcher.test.ts +89 -0
  502. package/src/utils/mcp-server-fetcher.ts +13 -5
  503. package/src/utils/request-auth-context.ts +24 -0
  504. package/src/utils/secret-rules.generated.ts +1 -1
  505. package/src/utils/secret-scrubber.ts +485 -54
  506. package/src/utils/task-attachment-links.ts +9 -12
  507. package/src/vcs/index.ts +3 -0
  508. package/src/workflows/approval-notifications.ts +188 -12
  509. package/src/workflows/executors/swarm-script.ts +23 -19
  510. package/src/workflows/executors/system-one-extraction.ts +14 -7
  511. package/src/workflows/executors/system-one-providers.ts +22 -1
  512. package/templates/community/open-prompt-showreel/PLAYBOOK.md +1 -1
  513. package/templates/community/open-prompt-showreel/skills/open-prompt-showreel/SKILL.md +1 -1
  514. package/templates/extensions/README.md +1 -0
  515. package/templates/extensions/sql-admin-only/README.md +19 -0
  516. package/templates/extensions/sql-admin-only/hooks.ts +96 -0
  517. package/templates/extensions/sql-admin-only/manifest.json +8 -0
  518. package/templates/import/manifest.schema.json +136 -0
  519. package/templates/import/sources.schema.json +44 -0
  520. package/templates/skills/agent-browser/SKILL.md +1 -1
  521. package/templates/skills/agent-browser/content.md +1 -1
  522. package/templates/skills/apps/SKILL.md +122 -12
  523. package/templates/skills/apps/content.md +122 -12
  524. package/templates/skills/asset-namespaces/content.md +2 -1
  525. package/templates/skills/chat-sdk/content.md +17 -0
  526. package/templates/skills/db-query-guidance/content.md +2 -1
  527. package/templates/skills/scheduling/content.md +27 -0
  528. package/templates/skills/slack-interaction/content.md +12 -2
  529. package/templates/skills/swarm-docs/content.md +1 -0
  530. package/templates/skills/swarm-extensions/config.json +1 -1
  531. package/templates/skills/swarm-extensions/content.md +33 -23
  532. package/templates/skills/swarm-scripts/SKILL.md +18 -4
  533. package/templates/skills/swarm-scripts/content.md +18 -4
  534. package/templates/skills/work-on-task/SKILL.md +1 -1
  535. package/templates/skills/work-on-task/content.md +1 -1
  536. package/templates/skills/workflow-iterate/content.md +4 -7
  537. package/templates/workflows/dreaming/content.md +3 -3
  538. package/dist/acp-adapter-fqzkxyra.js +0 -15
  539. package/dist/claude-adapter-stw7jdcf.js +0 -25
  540. package/dist/cli-4bd1rck6.js +0 -4
  541. package/dist/cli-dns0y538.js +0 -194
  542. package/dist/cli-g5mtmf6t.js +0 -432
  543. package/dist/cli-xf3qw745.js +0 -104
  544. package/dist/fx-adapter-rpsgb1tw.js +0 -18
  545. package/dist/grok-adapter-n2m3zjg1.js +0 -18
  546. package/dist/handlers-nv8edn19.js +0 -32
  547. package/dist/index-ksmyd6kc.js +0 -37
  548. package/dist/index-rjnrje98.js +0 -32
  549. package/dist/index-tv3413wy.js +0 -33
  550. package/dist/lead-3hmddvrm.js +0 -70
  551. package/dist/worker-qgg0m2gw.js +0 -70
  552. package/src/providers/ctx-mode-env.ts +0 -10
  553. package/src/tests/entrypoint-acp-target-binary.test.ts +0 -439
  554. package/dist/{cli-4caa1x7d.js → cli-tsa40663.js} +4 -4
  555. package/dist/{index-0rvk3vd4.js → index-bs7gw5fd.js} +3 -3
  556. package/dist/{mistral-conversations-a45tx39a.js → mistral-conversations-0c30em7t.js} +4 -4
  557. package/dist/{openai-completions-xd579js7.js → openai-completions-f3n69rep.js} +18 -18
  558. package/dist/{pi-messages-hjbv8v10.js → pi-messages-zebyt7gb.js} +5 -5
@@ -526,9 +526,9 @@ The sidebar lists pages in definition order and marks the current one. Below 768
526
526
 
527
527
  Param `kind` is `string` by default, or `number` / `boolean`; `required` defaults to false. The names `mode`, `apiUrl`, `apiKey`, `email`, and `name` are reserved. `/apps/<id>` renders `defaultPage`; `/apps/<id>/p/<page>?issueId=42` is the shareable deep link for another page. Browser navigation is client-side, so app state and polled data stay warm across page changes.
528
528
 
529
- Within each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Container, Card, Section, and Drawer). `watch` maps state paths to an action step or chain.
529
+ Within each page, `root` names one entry in its non-empty `elements` map. Elements are a flat, single-parent tree: ids are map keys, `children` contains ids (not nested elements), all elements must be reachable from `root`, and cycles, missing children, or shared children are invalid. Element and Form/UI ids are page-local. Element keys are `type`, `props`, `children`, `on`, `visible`, `repeat`, and `watch`; only components with a `default` child slot accept `children` (Stack, Grid, Split, Tabs, Accordion, Container, Card, Section, Drawer, and Dialog). `watch` maps state paths to an action step or chain.
530
530
 
531
- ## Component catalog (all 35)
531
+ ## Component catalog (all 45)
532
532
 
533
533
  Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
534
534
 
@@ -541,8 +541,9 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
541
541
  | `Stack` | none | Primary layout; `direction: "column", "row"`, `gap`, `padding: "none", "xs", "sm", "md", "lg", "xl"`; `align: "start", "center", "end", "stretch"`, `justify: "start", "center", "end", "between"`, `wrap`; `motion: "rise"` (default), `"fade"`, or `"none"` (see Motion below); `fill` (grow to fill a `fill`-aware parent; see Layout below); has the `default` child slot. |
542
542
  | `Grid` | none | Responsive `columns`: integer 1 through 6, or `{ base, sm, md, lg }` counts 1 through 6; `gap` uses the Stack spacing values; has the `default` child slot. |
543
543
  | `Split` | none | `ratio: "1-1", "1-2", "2-1", "1-3", "3-1"`, `gap`, `collapseBelow: "sm", "md", "lg"`, `reverse`, `fill` (same contract as Stack); has the positional `default` child slot. |
544
- | `Divider` | none | `label`; no children. |
544
+ | `Divider` | none | `label`, `orientation: "horizontal"` (default) or `"vertical"` (a rule between the items of a row `Stack`, as tall as the row); no children. |
545
545
  | `Tabs` | `id`, `tabs` | `tabs` entries are `{ key, label?, icon?, count? }` (`count` is a number shown as a small pill); `defaultTab`; `variant: "line"` (default) or `"segmented"` (a compact segmented control, same state and warm panels); has the positional `default` child slot. |
546
+ | `Accordion` | `id`, `items` | Grouped collapsible sections. `items` entries are `{ key, title, description?, icon? }`; children are positional like Tabs (`children[i]` is the body of `items[i]`, same count, validated). `type: "single"` (default: opening one closes the others, and the open one can close) or `"multiple"`. Open keys are client state at `{ "$state": "/ui/<id>/open" }`, always an array; `defaultOpen` lists the keys open on first render. Bodies mount only while open. `Section collapsible` stays the one-item form. |
546
547
  | `Container` | none | Legacy layout primitive; prefer Stack. `direction: "row", "column"`, `gap: "none", "sm", "md", "lg"`; has the `default` child slot. |
547
548
  | `Card` | none | `title`, `description`; has the `default` child slot. |
548
549
  | `Heading` | `text` | `level: "h1", "h2", or "h3"`. |
@@ -553,8 +554,8 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
553
554
  | `NumberInput` | `id` | `label`, `placeholder`, `min`, `max`; a text field with a decimal keyboard that writes the parsed number to `/ui/<id>/value` on every change (no debounce), or null when the field is empty; non-numeric text (a bare `-` mid-edit, letters) leaves the stored value untouched; `min`/`max` clamp the stored value and the visible text snaps to it when the field loses focus; no children. |
554
555
  | `Chips` | `id`, `options` | Toggle chips for quick filters. `options` are strings or `{ value, label?, icon? }`; `multiple`; `label` (group name for screen readers). Writes a string or null to `/ui/<id>/value`, or a string array with `multiple`; pressing the selected chip clears it. |
555
556
  | `Button` | `label` | `variant: "default", "secondary", "outline", "ghost", "destructive", or "destructive-outline"` (use `destructive-outline` for standalone deletes); `disabled` (constant or bound boolean); `busyWith: "<actionName>"` swaps the label for a spinner while that custom action's `/actions/<name>/status` is `"running"` (presses are ignored), then shows a check and `successLabel` for about 1.5s when it turns `"ok"`; `icon`, `iconPosition: "start" or "end"`; `size: "sm", "default", or "lg"`; `shortcut` (one key, shown as a keycap, presses the button); `hint` (tooltip); dispatch with element-level `on.press`. |
556
- | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. |
557
- | `Chart` | `kind`, `x`, `series` | `kind: "line", "area", or "bar"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: "category"` (default, row order) or `"time"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: "number"` (default), `"currency"` (with `currency`, an ISO code, default `USD`) or `"percent"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default "No data yet"). `x` and every `series[].key` must be columns of the bound query's model. Wrap it in a `Card` for a title. |
557
+ | `Metric` | `label`, `value` | The dashboard stat tile. `value` is string or number (empty renders an em dash); bind `loading` to `/queries/<name>/loading` for a skeleton while the query loads; `icon` with `tone` tinting its tile; `detail` (a line under the value); `trend: { direction: "up", "down", or "flat", label }`; `info` (explanation tooltip next to the label). `sparkline`: a small trend line under the value in the `tone` color, from an array of numbers (`null` is a gap) or from rows (bind `/queries/<name>/data`) read through `sparklineKey`; fewer than two points draws nothing. `format: "number"`, `"currency"` (with `currency`, an ISO code, default `USD`) or `"percent"` (a ratio: 0.42 is 42%) formats a numeric `value`, like Chart; a string value shows as is. |
558
+ | `Chart` | `kind`, `x`, `series` | `kind: "line", "area", "bar", "pie" or "donut"`; bind `data` / `loading` / `error` to a named query like Table. `x` is the row field on the x axis; `xType: "category"` (default, row order) or `"time"` (ISO date or epoch ms, sorted, date ticks; rows whose `x` does not parse are dropped). `series`: 1-8 `{ key, label?, color? }`, `color` one of `chart-1`..`chart-5`, `primary`, `success`, `warning`, `error`, `info`, `muted` (default palette, in order: `primary`, `chart-2`..`chart-5`). `stacked` stacks area and bar series (lines never stack). `format: "number"` (default), `"currency"` (with `currency`, an ISO code, default `USD`) or `"percent"` (values are ratios: 0.42 is 42%). Tooltip on hover; the legend shows with two or more series (`legend` forces it on or off). `height` 120-640 px (default 240); `emptyMessage` (default "No data yet"). `x` and every `series[].key` must be columns of the bound query's model. `pie` and `donut` take exactly one series: `x` is the slice label, each row with a positive value is a slice labelled with its share, the tooltip adds the share to the formatted value, and the legend defaults on (`xType` and `stacked` do not apply). Wrap it in a `Card` for a title. |
558
559
  | `Alert` | `message` | `title`, `tone: "info", "success", "warning", or "error"`, `icon` (overrides the tone icon), `actionLabel` (a button inside the callout that emits `press`; wire it with `on.press`). |
559
560
  | `Badge` | `text` | `text` is string or number; `tone`; `icon` replaces the dot; `variant: "tag"` (default uppercase chip), `"status"` (sentence-case pill), `"count"` (numeric pill), or `"beta"` (the BETA tag); `status` (a lifecycle value renders the dashboard status chip); `hint` (tooltip; the beta tag's explanation). |
560
561
  | `Icon` | `name` | `size: "sm", "md", or "lg"`, `tone: "default", "muted", "success", "warning", "error", or "info"`, `label` (accessible name; decorative without it). |
@@ -568,18 +569,25 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
568
569
  | `Section` | `title` | `description`, `collapsible`, `defaultOpen` (default true); has the `default` child slot. |
569
570
  | `Table` | `columns` | `data`, `loading`, `refreshing`, `error`, `emptyMessage`, `emptyState`, `rowActions`, `id`, `selectable`, `bulkActions`, `filterable`, `clearState`, `onRetry`, `onRowClick`, `selectedId`, `rowId`, `mobile`, `mobileFields`, `search`, `filters`; see below. |
570
571
  | `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |
571
- | `Drawer` | `param` | `title`, `description`, `side: "right" or "left"`, `size: "sm", "md" (default), "lg", or "xl"` (about 480/660/900/1010px at 1440px; grows with the viewport up to 640/960/1280/1600px; full width on phones), `actions` (sticky footer buttons; see below); has the `default` child slot. |
572
+ | `Drawer` | `param` | `title`, `description`, `side: "right" or "left"`, `size: "sm", "md" (default), "lg", or "xl"` (about 480/660/900/1010px at 1440px; grows with the viewport up to 640/960/1280/1600px; full width on phones), `actions` (sticky footer buttons; see below), `presentation: "sheet"` (default) or `"split"` (an inline right pane beside the page; see below); has the `default` child slot. |
573
+ | `Dialog` | `param` | A centered modal with the Drawer route contract: open exactly while the page param named by `param` is set; Escape, the X or a click outside clears it. `title`, `description`, `size: "sm", "md" (default), or "lg"`, `actions` (footer buttons, Drawer rules). Use it for a short form opened from `headerActions`; after the write, an `app.navigate` without the param closes it. Has the `default` child slot. |
572
574
  | `DetailList` | `fields` | `data`, `emptyMessage`, `columns: 1 or 2`, `loading` (bind `/queries/<name>/loading` for skeleton fields while loading); renders one record without edit controls; see below for field kinds. |
573
575
  | `CardGrid` | `titleKey` | `data`, `loading`, `error`, `emptyMessage`, `imageKey`, `fields`, `columns`, `onClick`; one card per row for record browsers; see below. |
574
576
  | `Kanban` | `columnField`, `columns`, `titleField` | `data`, `loading`, `cardFields`, `idField` (default `id`), `onMove`, `onCardClick`; see below. |
575
577
  | `Calendar` | `startField`, `titleField` | `data`, `loading`, `endField`, `idField`, `onSelect`; read-only month grid; see below. |
576
578
  | `ContributionGraph` | none | `data`, `loading`, `dateField` (default `date`), `countField`, `days` (7-730, default 365); read-only activity heatmap. |
577
579
  | `Tree` | `id`, `nodes` | `label`, `maxHeight` (default `480px`), `fill`; collapsible outline of a doc-shaped value that writes the clicked node key to `/ui/<id>/value`; see below. |
580
+ | `Files` | `path` | `mode: "list"` (default) or `"browser"`, `selectedPath`, `emptyMessage`, `maxHeight` (default `480px`), `fill`, `onSelect`, `upload`; an agent-fs folder listing read as the viewer; see below. |
581
+ | `File` | `path` | `height`, `fill`; one agent-fs file (Markdown, image, PDF, text) read as the viewer; see below. |
582
+ | `DateRange` | `id` | `presets` (any of `7d`, `30d`, `90d`, `mtd`, `custom`; default all five), `defaultPreset` (default the first), `label`; writes `/ui/<id>/from` and `/ui/<id>/to`; see below. |
583
+ | `Timeline` | `timeField`, `titleField` | `data`, `loading`, `descriptionField`, `statusField`, `tones`, `icon`, `emptyMessage`, `onSelect`; vertical event list, newest first, grouped by day; see below. |
578
584
  | `SchemaForm` | `id`, `schema` | `value`, `baseDoc`, `nodeKey`, `onChange`, `fill`; form generated from a JSON schema's `properties`, mirrored to `/ui/<id>/value`; see below. |
585
+ | `Approval` | `requestId` | `showResolved` (default true), `compact`, `onResolved`; one approval request answered in place by the viewer; see below. |
586
+ | `SessionThread` | `id`, `sessionKey` | `scope`, `placeholder`, `onDispatch`, `fill`; the dashboard's session conversation (the "Session about this page" panel) for one session per viewer and key, with a composer that steers or chains tasks; the draft is mirrored to `/ui/<id>/value`; see below. |
579
587
 
580
588
  Table details:
581
589
 
582
- - `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", hint?: string, popover?: { title?, fields, trigger? }, href?: "<row field>", linkLabel?: "<template>", max?: number, format?: "<template>", onChange?: chain, filter?: "values" or "text" or false, muted?: string[] }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `checkbox`, `link`, or `json`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
590
+ - `columns[]`: `{ key, label?, kind?, tones?: {value: badgeTone}, width?: number, pinned?: "left" or "right", align?: "start" or "end", truncate?: "end" or "middle", icon?, tooltip?: "<row field>", hint?: string, popover?: { title?, fields, trigger? }, href?: "<row field>", linkLabel?: "<template>", max?: number, format?: "<template>", currency?: "<ISO 4217>", onChange?: chain, filter?: "values" or "text" or false, muted?: string[] }`. `kind` is `text`, `string`, `enum`, `number`, `boolean`, `date`, `badge`, `status`, `user`, `agent`, `relative`, `duration`, `progress`, `copy`, `switch`, `checkbox`, `link`, `json`, `currency`, or `percent`; `string` and `enum` render as text, and `json` renders a truncated single-line `JSON.stringify` preview. `currency` shows a number as money in the column's `currency` (an uppercase ISO 4217 code, default `USD`): `1234.5` is `$1,234.50`. `percent` reads a ratio: `0.42` is `42%`. Both right-align and show a non-numeric value as is. Pin id/actions columns so they survive horizontal scroll on narrow viewports.
583
591
  - `status`: lifecycle values (`pending`, `in_progress`, `running`, `completed`, `failed`, `cancelled`, `paused`, `reviewing`, ...) render the dashboard status chip with its icon; other values use `tones` like `badge`.
584
592
  - `user` / `agent`: avatar plus name. `relative` (and `date`): smart time, exact time on hover. `duration`: milliseconds as `1m 23s`. `progress`: a bar against `max` (default 100). `copy`: the value plus a copy button. `link`: a smart link (see Smart links, tooltips and popovers below); any other http(s) URL opens in a new tab and other values render as text.
585
593
  - `switch` / `checkbox`: a toggle or a checkbox bound to a boolean column. `onChange` runs with `$row` = the row with this column already set to the new value, e.g. `[{ "action": "app.mutate", "params": { "model": "m", "op": "update", "rowId": { "$row": "id" }, "values": { "enabled": { "$row": "enabled" } } } }]`. Without `onChange` the control is read-only. Each toggle is a model write, so to pick rows for a bulk action use `selectable` (below), not a boolean column.
@@ -626,15 +634,97 @@ Tree details:
626
634
  - Each row shows `key — type`. Clicking a row writes its key to `/ui/<id>/value`, and the row bound to that path renders selected; read the selection with `{ "$state": "/ui/<id>/value" }`. The Tree never writes `null`: when the selected key leaves the doc (a refetch, an edit) the stored key stays and no row renders selected. Selection and collapse are keyed by node key, so a key reachable through two parents selects and collapses in both places.
627
635
  - Rows scroll inside `maxHeight` (default `480px`). Set `fill: true` inside a `fill` Stack or Split pane to grow to that height instead and scroll within it (ignores `maxHeight`).
628
636
 
637
+ Files and File details:
638
+
639
+ - Both read agent-fs as the viewer, with the viewer's own agent-fs key (the one Comb saves in their browser), from the swarm's default drive (`agent_fs.comb` in `/status`). There is no `drive` prop yet. The swarm key never reaches agent-fs, and the viewer sees only what their drive membership allows; an app cannot widen it.
640
+ - A viewer who has not connected agent-fs sees a "Connect agent-fs" card that opens Comb's connect flow. In a `?mode=chromeless` iframe the card links to the app in the dashboard instead, because the iframe has no saved key.
641
+ - `path` is absolute. A literal path must not contain `..`; bind it with `$state` to follow a route param. A folder that does not exist yet lists as empty (`emptyMessage`).
642
+ - `Files` sorts folders first. `mode: "browser"` opens subfolders in place, with crumbs that never go above `path`, and reopens on the folder holding `selectedPath`. A file click (in list mode, any row) runs `onSelect` with `$row` = `{ path, name, type, size, modifiedAt }`; `type` is `file` or `directory`, and a folder's `path` ends with `/`. Usually: `[{ "action": "app.navigate", "params": { "page": "docs", "params": { "file": { "$row": "path" } } } }]`, plus `"selectedPath": { "$state": "/route/params/file" }`.
643
+ - `File` renders Markdown with raw HTML shown as text, images as `<img>` (SVG too, so its scripts never run), PDFs in the browser's viewer, video and audio in a player, CSV as a table, and text files (HTML as source) as lines. Other types show Download and "Open in agent-fs". An empty `path` shows "No file selected".
644
+ - List and view: a `Split` with `Files` in the left pane and `File` with `"path": { "$state": "/route/params/file" }` in the right; declare `file` in the page's `params`.
645
+ - `upload: true` adds an Upload button and a drop zone over the list. Files upload with the viewer's key into the folder on screen (the opened subfolder in browser mode), create-only: a taken name asks Keep both or Skip. The list refreshes when a file lands. agent-fs's own upload limit applies.
646
+ - Scripts: an `app.action` script runs as its owner agent, so `ctx.fs` `/afs` reads that agent's default drive, not the viewer's. It sees the same files only when the agent's default drive is the swarm's comb drive.
647
+
648
+ DateRange and Timeline details:
649
+
650
+ - `DateRange` writes inclusive `YYYY-MM-DD` dates (the viewer's local calendar) to `/ui/<id>/from` and `/ui/<id>/to`, and the active preset to `/ui/<id>/preset`. On first load it writes `defaultPreset` unless the state already holds a range. Bind query params with `{ "$state": "/ui/<id>/from" }` so the query refetches when the range changes. `7d` is today and the six days before it; `mtd` starts on the 1st. `custom` opens two date inputs in a popover; Apply needs both dates, from not after to. `id` must match `[A-Za-z0-9_-]+`, and `defaultPreset` must be one of `presets`.
651
+ - `Timeline` reads `timeField` as an ISO date or epoch ms (rows that do not parse are left out), sorts newest first and groups under day headings: Today, Yesterday, then the date. Each event shows `titleField`, the time, `descriptionField` (two lines at most) and a `statusField` pill (`tones` maps value to tone; lifecycle values get the status chip). `icon` replaces the marker dot. `onSelect` runs with `$row` (the row) and `$rowIndex` (its index in `data`); without it events are not clickable.
652
+
629
653
  SchemaForm details:
630
654
 
631
655
  - `schema` is a JSON schema object held in state (usually `{ "$state": ... }`). Each entry of `properties` becomes one control: `type: "boolean"` a switch, `enum` of strings a select, `type: "number"` or `"integer"` a number input, anything else a text input. `description` is the tooltip. Fields seed from `value[key]`, else the property `default`. At most 100 fields and 200 enum options render. `id` must match `[A-Za-z0-9_-]+`. Rebinding `schema` resets the form.
632
656
  - Typing updates `/ui/<id>/value` with the draft object; switches and selects commit at once and text and number inputs commit on blur. Each commit runs `onChange` with `$form` = the draft.
633
657
  - Nested document editing: bind `baseDoc` to a doc-shaped value (`{ root, elements }`) and `nodeKey` to an element key, such as a Tree's `{ "$state": "/ui/<tree>/value" }`. The form then edits `baseDoc.elements[nodeKey].props`, and `/ui/<id>/value` holds the whole doc with the edit merged in, so one `app.mutate` with `values: { <jsonColumn>: { "$state": "/ui/<id>/value" } }` persists it. Props the schema does not list are kept. Edits the query has not returned yet stay applied, so two quick edits on different nodes both survive. A `nodeKey` that is not a key of `elements` falls back to plain mode, and a `baseDoc` over 5,000 elements is not editable. Typing writes `/ui/<id>/value` on every keystroke, before the commit on blur, so another component's `app.mutate` that reads that path can persist half-typed text; persist from the SchemaForm's own `onChange`.
634
658
 
659
+ Approval details (human-in-the-loop):
660
+
661
+ - `requestId` names one approval request, usually the id an `app.action` script returned: `{ "$state": "/actions/<name>/result/requestId" }`. An empty value renders nothing, so the element can sit on the page before the request exists.
662
+ - While the request is pending, the card shows its questions with the dashboard's answer flow and polls every 5s; polling stops once it resolves. The viewer answers with their own credential, so the server records them and enforces the approvers list and RBAC.
663
+ - A viewer whose role cannot answer, or whose answer the server refuses (not an approver), sees a read-only card with an "Open in dashboard" link. If the request was answered or expired meanwhile, the card refetches and shows that state instead of an error. With an `all` or `{ min: N }` policy, an answer that does not resolve it shows "Your answer is recorded".
664
+ - `showResolved: false` shows only the outcome line after resolution, not the answers. `compact: true` drops the card chrome.
665
+ - `onResolved` is an action chain run once, when the page sees the request leave `pending`. Its params may read `{ "$chain": "status" }` (`approved`, `rejected`, `timeout`, `cancelled`), `{ "$chain": "responses" }` (answers keyed by question id; `{ "$chain": "responses/<questionId>" }` reads one), and `{ "$chain": "resolvedBy" }`. A request that was already resolved when the page loaded does not run it, so a reload never repeats the follow-up. Use `onResolved`, not `on.resolved`: the validator rejects the latter.
666
+
667
+ In-session wait: the follow-up runs in the viewer's browser, so if they close the tab before the answer, nothing continues. The script behind the action creates the request detached and returns its id:
668
+
669
+ ```ts
670
+ export default async function run(args, ctx) {
671
+ const res: any = await ctx.swarm.request_humanInput({
672
+ title: `Deploy ${args.service}?`,
673
+ questions: [{ id: "go", type: "approval", label: "Ship it to production?" }],
674
+ detached: true,
675
+ });
676
+ return { requestId: res?.data?.requestId ?? res?.requestId };
677
+ }
678
+ ```
679
+
680
+ ```json
681
+ {
682
+ "askBtn": { "type": "Button", "props": { "label": "Request deploy", "busyWith": "requestDeploy" },
683
+ "on": { "press": { "action": "app.action", "params": { "name": "requestDeploy", "input": { "service": "api" } } } } },
684
+ "approve": {
685
+ "type": "Approval",
686
+ "props": {
687
+ "requestId": { "$state": "/actions/requestDeploy/result/requestId" },
688
+ "onResolved": [
689
+ { "action": "app.action", "params": { "name": "applyDecision",
690
+ "input": { "status": { "$chain": "status" }, "responses": { "$chain": "responses" } } } },
691
+ { "action": "ui.toast", "params": { "message": "Decision applied", "tone": "success" } }
692
+ ]
693
+ }
694
+ }
695
+ }
696
+ ```
697
+
698
+ Durable wait: when the follow-up must run even if nobody watches the page, put it in a workflow whose human-in-the-loop node waits server-side, and use `Approval` only to answer. A script action starts the run with `ctx.swarm.workflow_trigger({ id, triggerData, wait: false })` and returns `runId`. The request appears once the run reaches its human-in-the-loop node, so a second script action (pressed from the page, or retried) finds it and returns its id: `ctx.swarm.db_query({ sql: "SELECT id FROM approval_requests WHERE workflowRunId = ? AND status = 'pending' ORDER BY createdAt DESC LIMIT 1", params: [args.runId] })`, then `{ requestId: res.data.rows[0]?.[0] }`. Bind `Approval.requestId` to that action's result. The workflow resumes on the answer whether or not the page is open.
699
+
700
+ SessionThread details — a chat on an app page, one session per viewer and `sessionKey`:
701
+
702
+ - `sessionKey` names the session, a plain token (`^[A-Za-z0-9_-]{1,128}$`): a literal such as `"main"`, or a `$state` binding to a token such as a route param or row id (`{ "$state": "/route/params/itemId" }`) for one session per item. No row stores the session: the server keys every task the thread's `app.action` creates as `task:app:<appId>:<sessionKey>:user:<viewer>`, and the thread shows the viewer's newest session with that key. A page can only write sessions of its own app.
703
+ - `scope` is `"user"` (the default): each viewer has their own session per key. The viewer needs an identity; with none picked the composer is disabled. `scope: "shared"` (one session everyone on the page writes to) comes in a follow-up PR: the validator rejects it today. The planned design adds an everyone:write session share on the root when the server creates it.
704
+ - It renders the same conversation as the dashboard's "Session about this page" panel: the session turn timeline (each person message with the sender's name, the swarm's replies with a live Queued / Working status, worker steps, approvals) and the shared composer. A person bubble shows the `message` of an app-action input instead of the whole agent prompt, cut at 4,000 characters. The composer's attachments and mic are off: a message is text only.
705
+ - Sending a message takes one of three routes:
706
+ 1. No session yet → run `onDispatch` with `$form = { message }` and `$chain = { leafTaskId: null, newTaskId: null }`. Its `app.action` creates the session's root task.
707
+ 2. A task in the session is not finished → the composer steers the newest such task, on any agent, with `source: "app-page"`. It offers Queue, and Interrupt where the harness supports it. The server promotes a steer it cannot deliver into a follow-up task (source `ui`), and a toast says so.
708
+ 3. Every task is finished (completed, failed, cancelled, superseded, skipped, or draft) → run `onDispatch` again with `$chain.leafTaskId` set to the newest task id, so `"parentTaskId": { "$chain": "leafTaskId" }` chains the new task under it. The follow-up keeps the session's key.
709
+ - Each `app.action` step of `onDispatch` is sent with the session (`{ key, scope }`) and with `followUp: false` unless the step sets `followUp` itself, so the Lead adds no review task to the chain and each message stays one task. A Lead review that is in the chain anyway (a steer the server promoted to a task) is never steered or chained under.
710
+ - "New session" (shown once a session exists) starts over: the next message creates a new root, and the thread shows only sessions created after the current one. Nothing is deleted; older sessions stay in the dashboard's Sessions list.
711
+ - While the session loads, the composer is disabled with a loading notice. A session whose chain cannot be found blocks sending. After a send, the composer stays busy until the new task shows up, for at most 30 seconds.
712
+ - Without `fill` the thread is 420 px tall; `fill: true` fills a `fill`-aware parent. Inside an element instance, `id` is namespaced per instance, so two instances keep separate drafts.
713
+
714
+ ```json
715
+ { "type": "SessionThread", "props": {
716
+ "id": "chat",
717
+ "sessionKey": { "$state": "/route/params/screenId" },
718
+ "onDispatch": [{ "action": "app.action", "params": {
719
+ "name": "editScreen", "input": { "$form": "" }, "parentTaskId": { "$chain": "leafTaskId" } } }]
720
+ } }
721
+ ```
722
+
635
723
  Form details:
636
724
 
637
- - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, or `enum`, and enum fields need `options`.
725
+ - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, `enum`, or `file`, and enum fields need `options`.
726
+ - `kind: "file"` adds `dir`, `accept` (e.g. `[".pdf", "image/*"]`), `multiple` and `source`: `"upload"` (default) chooses local files, `"pick"` opens a browser of `dir` (or `/`) to attach a file that already exists in agent-fs, `"both"` offers both. `dir` is an absolute agent-fs folder, required unless `source` is `"pick"`. Files use the viewer's own agent-fs key on the swarm's default drive, like `Files`.
727
+ - On submit, chosen files upload first, create-only, to `<dir>/<timestamp>-<id>-<n>-<sanitized name>`: a random id per submit and a counter across all fields, so two fields or two submits never write the same path; then the chain runs. `$form.<name>` is the stored path, or an array of paths with `multiple: true`. An upload failure (the error shows agent-fs's text, e.g. its size limit) stops the chain and keeps the form's values. Without an agent-fs connection the field shows a "Connect agent-fs" card, and a required file field disables submit.
638
728
  - Values live at `/forms/<formId>/<fieldName>`. `onSubmit` is an action chain.
639
729
  - The submit button shows a pending spinner while the chain runs, and `app.mutate` failures in the chain render inline under the fields (not the page banner) — no extra wiring needed.
640
730
 
@@ -642,10 +732,28 @@ Drawer details:
642
732
 
643
733
  - `param` must name a param declared on the containing page. The drawer is open exactly when `/route/params/<param>` has a non-empty value, so its open state survives refresh and is shareable. Its children mount only while open; closing it clears that param with history replacement.
644
734
  - `actions[]`: `{ label, variant?, icon?, confirm?, actions }`, rendered as buttons in a sticky footer under the scrolling body. Confirmation follows Table `rowActions`: destructive variants confirm by default, and a chain with an `app.mutate` delete always confirms. Chains have no `$row`; address the open record with `{ "$state": "/route/params/<param>" }`, for example `{ "action": "app.mutate", "params": { "model": "order", "op": "delete", "rowId": { "$state": "/route/params/panel" } } }`. Prev/next record navigation is not available.
735
+ - `presentation: "split"` renders the Drawer as an inline right pane beside the page instead of a sheet over it. The page canvas shrinks while it is open; the pane has a draggable left edge (arrow keys, Shift for big steps, Home/End for the min/max, double-click or Enter to reset) and the viewer's width is kept per app in the browser. `size` sets its starting width (360/480/640/800px). Opening, closing, refresh and shared links work exactly as for the sheet. Below 768px it falls back to the sheet. At most one split Drawer per page; `side` does not apply.
736
+
737
+ List + detail recipe (a row click opens the record beside the table):
738
+
739
+ ```json
740
+ "params": { "issue": { "kind": "string" } },
741
+ "elements": {
742
+ "root": { "type": "Stack", "props": {}, "children": ["table", "issue"] },
743
+ "table": { "type": "Table", "props": {
744
+ "data": { "$state": "/queries/issues/data" },
745
+ "columns": [{ "key": "title" }, { "key": "status", "kind": "status" }],
746
+ "selectedId": { "$state": "/route/params/issue" },
747
+ "onRowClick": [{ "action": "app.navigate", "params": { "page": "main", "params": { "issue": { "$row": "id" } } } }] } },
748
+ "issue": { "type": "Drawer", "props": { "param": "issue", "presentation": "split", "size": "md", "title": "Issue" },
749
+ "children": ["issueDetail"] },
750
+ "issueDetail": { "type": "DetailList", "props": { "data": { "$state": "/queries/issue/data/0" }, "fields": [{ "key": "title" }] } }
751
+ }
752
+ ```
645
753
 
646
754
  DetailList details:
647
755
 
648
- - `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and the Table cell renderers (`status`: lifecycle chip or `tones` pill; `user`: avatar plus name; `relative`: smart time, exact on hover; `copy`: value plus copy button; `link`: a smart link from the value, or from the row field named by `href`, with `linkLabel` as an optional label template), and add `code` for a monospace block and `json` for a collapsible JSON tree (objects, or a string holding JSON). Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.
756
+ - `fields[]`: `{ key, label?, kind?, tones? }`. Kinds reuse Table formatting (`text`, `string`, `number`, `boolean`, `date`, `badge`, `enum`) and the Table cell renderers (`status`: lifecycle chip or `tones` pill; `user`: avatar plus name; `relative`: smart time, exact on hover; `copy`: value plus copy button; `link`: a smart link from the value, or from the row field named by `href`, with `linkLabel` as an optional label template), and add `code` for a monospace block and `json` for a collapsible JSON tree (objects, or a string holding JSON). `currency` and `percent` (with `currency?: "<ISO 4217>"`) format numbers like the Table kinds. Bind `data` to one record, commonly `/queries/<detailQuery>/data/0`.
649
757
 
650
758
  Motion details:
651
759
 
@@ -731,7 +839,7 @@ Valid `$state` roots are:
731
839
 
732
840
  `/route` is mirrored as `{ page, params }`. Only declared params appear. Values are coerced by their declared kind: `number` becomes a number when possible; boolean strings `true`/`1` become true; failed number coercion remains the raw string.
733
841
 
734
- Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `Table.bulkActions[].actions`, or `Form.onSubmit`) these scoped sentinels are valid, recursively inside objects and arrays:
842
+ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `Table.bulkActions[].actions`, `Form.onSubmit`, or a component chain prop such as `Approval.onResolved` or `SessionThread.onDispatch`) these scoped sentinels are valid, recursively inside objects and arrays:
735
843
 
736
844
  | Sentinel | Resolves to |
737
845
  |---|---|
@@ -741,7 +849,7 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `
741
849
  | `{ "$form": "title" }` | One current Form value. |
742
850
  | `{ "$form": "" }` | All current Form values. |
743
851
  | `{ "$state": "/queries/allIdeas/data" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |
744
- | `{ "$chain": "leafTaskId" }` | One chain-scope value, published by a component that runs a task chain; it carries `leafTaskId` and `newTaskId`. Where no chain scope is published, the sentinel is left in place and the action fails instead of silently dropping the parent. |
852
+ | `{ "$chain": "leafTaskId" }` | One chain-scope value, published by the component that runs the chain: a task chain (`SessionThread`) carries `leafTaskId` and `newTaskId`; `Approval.onResolved` carries `status`, `responses` and `resolvedBy`. The component publishes every key, `null` when it has no value yet; a `null` key resolves to nothing and its param is dropped (a `parentTaskId` bound to a `null` `leafTaskId` creates a root task). Where no chain scope is published (Table, Form), or the key is not one the scope carries (a typo), the sentinel is left in place and the action fails instead of silently dropping the parent. An empty string is not "no parent": a `$state` slot meaning "no parent yet" must hold `null`. |
745
853
  | `{ "$chain": "" }` | The whole chain scope. |
746
854
 
747
855
  Each sentinel object must contain exactly the single key shown.
@@ -750,12 +858,14 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
750
858
 
751
859
  - `app.mutate`: `{ model, op, rowId?, values?, formId? }`, where `op` is `"create"`, `"update"`, or `"delete"`. `update`/`delete` require `rowId` (usually `{ "$row": "id" }`, or `{ "$state": "/route/params/<param>" }` in a Drawer footer); literal `values` keys must be model columns. Successful mutation refetches all queries on that model.
752
860
  - `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.
753
- - `app.action`: `{ name, input?, parentTaskId? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ "$chain": "leafTaskId" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400.
861
+ - `app.action`: `{ name, input?, parentTaskId?, followUp? }`; `name` must be declared in definition `actions`. For a task-kind row action, pass whole-row context with `input: { issue: { "$row": "" } }`. `parentTaskId` chains the created task under an existing one for task-kind actions (typically `{ "$chain": "leafTaskId" }`; a literal or `$state` task id also works); a script or sync action rejects it with 400. `followUp: false` creates the task with no Lead follow-up (the review task the Lead adds when a worker task finishes); script and sync actions ignore it. A task an action creates is attributed to the viewer's identity. `session: { key, scope }` (SessionThread sets it) keys a task-kind action's task into the viewer's session; the server builds the key, never the page.
754
862
  - `app.navigate`: `{ page, params? }`; `page` must be declared, supplied keys must be params of the target page, and every required target param must be supplied. `params` replace the current route params wholesale and may contain action sentinels. Navigation pushes history, so browser Back returns to the previous page/params; only `mode` is preserved automatically.
755
863
  - `ui.toast`: `{ message, description?, tone?, undo? }`, where `tone` is `"success"`, `"error"`, `"info"` (default), or `"warning"`. `undo: { label?, actions }` adds an Undo button (default label `Undo`) that runs `actions` as a chain; its steps are validated like any chain. Put it after the step it confirms, e.g. a row delete followed by `{ "action": "ui.toast", "params": { "message": "Order deleted", "undo": { "actions": [{ "action": "app.mutate", "params": { "model": "order", "op": "create", "values": { "title": { "$row": "title" } } } }] } } }`. Undo params resolve `$state` when Undo is pressed; `$row` / `$form` resolve when the toast is shown.
756
864
  - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.
757
865
  - `swarm.call`: `{ method, endpoint: "/api/...", body? }`, where `method` is `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, or `"PATCH"`; raw authenticated API call.
758
866
 
867
+ A failed step halts its chain: when `app.action`, `app.mutate`, `swarm.sdk` or `swarm.call` fails (a thrown error, a script action that returns `ok: false`, a non-2xx `swarm.call`), the steps after it do not run and the error shows as an error toast. A step's `onError` (`{ set }` or `{ action }`) runs first, and the chain still halts. So a `ui.toast` after a write is a real success message. A `Form`'s failed `app.mutate` shows inline under the fields instead of a toast. A task-backed `app.action` succeeds once the task is created; the task's own failure shows in the page banner and does not halt the chain. A Table bulk action reads each step's own outcome, as before.
868
+
759
869
  ## Patch semantics
760
870
 
761
871
  `app-patch.definition` is RFC 7396 JSON Merge Patch applied to the stored definition:
@@ -13,11 +13,12 @@ Use an asset `key` as directory-like grouping metadata across tasks, workflows,
13
13
 
14
14
  ## Set and inherit keys
15
15
 
16
- Pass `key` when creating a task, workflow, schedule, or page. Omitting it creates a deterministic shared resource key such as `shared/task:<id>/`, `shared/workflow:<id>/`, `shared/schedule:<id>/`, `shared/page:<id>/`, or `shared/fs:agent-fs:<id>/`.
16
+ Pass `key` when creating a task, workflow, schedule, or page. Without inheritance, omitting it creates a deterministic shared resource key such as `shared/task:<id>/`, `shared/workflow:<id>/`, `shared/schedule:<id>/`, `shared/page:<id>/`, or `shared/fs:agent-fs:<id>/`.
17
17
 
18
18
  - Tasks sent from another task inherit the source task's key unless explicitly overridden.
19
19
  - Tasks launched by a workflow inherit the workflow key unless the agent-task node supplies a key.
20
20
  - Tasks launched by a schedule inherit the schedule key.
21
+ - The `create-schedule` and `create_page` tools default to the calling task's group key, excluding namespace roots and resource leaves.
21
22
  - Agent-fs task attachments receive logical file mappings and inherit their task key.
22
23
 
23
24
  Use only a canonical user-registry ID in `personal/<user-id>/`. Do not substitute an agent ID, email address, Slack ID, or unverified caller-provided value. The API authorizes the destination against trusted request/task context and rejects mismatches.
@@ -43,6 +43,13 @@ Write plain, short markdown: bold, italic, inline code, code blocks, bullet list
43
43
  | Slack | Converted to Slack mrkdwn: bold, italic, code, lists, links. Tables do not render well. | 4000 characters |
44
44
  | Teams | Basic markdown: bold, italic, code, lists, links. | 20000 characters |
45
45
 
46
+ Tables and charts go in a `card` on `chat-reply`, not in the markdown text. It posts after the text, as its own message. When the card is the answer, keep the task `output` to one line pointing at it, because the swarm posts `output` too. What a card becomes:
47
+
48
+ - Slack: native Block Kit tables and charts. A spec Slack cannot draw natively is rejected, so fix it and retry.
49
+ - Teams: an Adaptive Card with native tables and fields. Charts fall back to text.
50
+ - Discord: an embed. Tables become pipe-delimited text rows, and charts fall back to text.
51
+ - Telegram: formatted text with link buttons as inline buttons. Tables and charts fall back to text.
52
+
46
53
  The swarm splits longer text into several messages at line breaks. Long answers are hard to read in chat, so keep the answer short and put long material in an artifact or page, then post the link.
47
54
 
48
55
  ## Attachments
@@ -68,6 +75,16 @@ The task text already holds the earlier swarm messages of the thread, so read th
68
75
  - `chat-post { adapter, threadId | channelId, text }` posts outside your task's thread. Lead only. Use it only when the task asks you to message another thread or channel.
69
76
  - `chat-open-dm { adapter, userId }` returns the direct-message thread id for a user. Lead only. Then post to it with `chat-post`.
70
77
 
78
+ ## Leads: use-case thread
79
+
80
+ A use case (a schedule and its runs under one key, see the `scheduling` skill) can post a summary of each run to one chat thread.
81
+
82
+ 1. When you handle the follow-up of the first run (the planning session has usually ended by then), read `kv-get { namespace: "usecase:<key>", key: "thread" }`. A stored value means that you offered before: do not offer again.
83
+ 2. Offer once: "Do you want a summary of each run in a chat channel? Tell me the channel."
84
+ 3. On no: `kv-set { namespace: "usecase:<key>", key: "thread", value: { declined: true } }`.
85
+ 4. On yes: `chat-post { adapter, channelId, text }` with a one-line title, for example "Competitor watch: one summary per run". Then `kv-set { namespace: "usecase:<key>", key: "thread", value: { adapter, channelId, threadId: "<threadId from chat-post>" } }`.
86
+ 5. When you finish or review a run of the use case (the run itself, or the follow-up of a worker's run): `kv-get` the thread. When it has a `threadId`, `chat-post { adapter, threadId, text }` with the run summary and the link to its result file.
87
+
71
88
  ## Leads: `register-chat-channel`
72
89
 
73
90
  By default every message addressed to the swarm goes to the lead. A lead can route one channel to a fixed agent or workflow:
@@ -44,7 +44,7 @@ Run `SELECT name FROM pragma_table_info('<table>')` before you guess a column.
44
44
 
45
45
  - `agent_tasks`: no cost column and no `metadata` column. Cost is `session_costs.totalCostUsd`, joined on `taskId`. Assignee `agentId`, creator `creatorAgentId`, model `model`, `resolvedModel`, `modelSource`. `parentTaskId` is the only SQL child finder, because `key` is unique per task.
46
46
  - `scripts`: the owner is `createdByAgentId`; there is no `agentId`. `isScratch = 1` marks inline `script-run` bodies (`scratch-*` names), and they outnumber named scripts many times over. Add `isScratch = 0` to catalog audits. To find a script's callers, group by `isScratch` instead of dropping scratch rows: inline runs are often the negative tests.
47
- - `script_runs`: `scriptName`, `agentId`, `status`, `startedAt`, `finishedAt`, `error`. There is no duration column: use `(julianday(finishedAt) - julianday(startedAt)) * 86400`.
47
+ - `script_runs`: `scriptName`, `sourceTaskId`, `agentId`, `status`, `startedAt`, `finishedAt`, `error`. There is no `scriptId` (the name column is `scriptName`) and no `taskId` (the task column is `sourceTaskId`). There is no duration column: use `(julianday(finishedAt) - julianday(startedAt)) * 86400`. Filter on `scriptName` plus a narrow `startedAt` window; a `GROUP BY agentId` over a wide window can run past the MCP budget.
48
48
  - `session_costs`: `taskId`, `agentId`, `totalCostUsd`, `model`, the token columns, `createdAt`.
49
49
 
50
50
  ## Operator config knobs
@@ -56,6 +56,7 @@ effect on the next request, no restart) and surfaced on the dashboard's
56
56
  | Env var | Default | Controls |
57
57
  |---|---|---|
58
58
  | `DB_QUERY_BOUNDED_ENABLED` | `true` | Master kill switch for the bounded child-process path. `false` restores the pre-fix synchronous, unbounded path and logs a one-time startup-class warning. |
59
+ | `DB_QUERY_WORKER_POOL_ENABLED` | `true` | Reuse long-lived child processes for bounded queries. `false` spawns a fresh child per query. |
59
60
  | `DB_QUERY_HTTP_BUDGET_MS` | `10000` | Wall-clock budget for `/api/db-query` before its child process is killed. |
60
61
  | `DB_QUERY_HTTP_MAX_ROWS` | `1000` | Row cap for `/api/db-query`, regardless of how many rows the query matched. |
61
62
  | `DB_QUERY_MCP_BUDGET_MS` | `5000` | Wall-clock budget for the MCP `db-query` tool. |
@@ -41,6 +41,33 @@ The template is the whole task the agent receives. It must state:
41
41
 
42
42
  Tasks created by a schedule are automatic tasks. Their completed output is not stored as memory unless the agent calls `store-progress` with `persistMemory: true`.
43
43
 
44
+ ## Use cases: one key for the schedule and its results
45
+
46
+ A recurring job that a person comes back to is a use case. Its planning session, the schedule, the runs, pages, and result files share one asset key, so the dashboard shows them as one Sessions group.
47
+
48
+ - The key is `shared/<slug>/`, or `personal/<user>/<slug>/` for private work. Agree the short slug with the requester, for example `shared/competitor-watch/`.
49
+ - `create-schedule` and `create-page` use the key of the calling task when that key is a use-case group. Otherwise pass `key` explicitly. Runs get the schedule's key.
50
+ - The task template tells each run to write its result under the key in the shared drive, for example `shared/competitor-watch/report-<YYYY-MM-DD>.md`, and to compare with the earlier reports in that folder.
51
+ - End the planning reply with the "lives in" line: `This use case lives in Sessions → competitor-watch: <APP_URL>/sessions?view=shared/competitor-watch/`.
52
+
53
+ ### One-time ask or lasting change
54
+
55
+ In a use-case session, decide what the request changes:
56
+
57
+ - A request for one time only ("also check Acme today"): a normal task in the key. Do not change the schedule.
58
+ - A request that changes the future runs ("from now on also include pricing"): change the schedule. Read the current template with `list-schedules` (`key` is the use-case key), then call `update-schedule` with the full new `taskTemplate`:
59
+
60
+ ```
61
+ update-schedule { scheduleId: "<id>", taskTemplate: "Research the 5 competitors in shared/competitor-watch/competitors.md. Include their pricing. Write shared/competitor-watch/report-<YYYY-MM-DD>.md and compare with the previous report." }
62
+ ```
63
+
64
+ Then show the change as a `diff` block in your reply, and ask the requester to confirm it:
65
+
66
+ ```diff
67
+ - Research the 5 competitors in shared/competitor-watch/competitors.md. Write shared/competitor-watch/report-<YYYY-MM-DD>.md and compare with the previous report.
68
+ + Research the 5 competitors in shared/competitor-watch/competitors.md. Include their pricing. Write shared/competitor-watch/report-<YYYY-MM-DD>.md and compare with the previous report.
69
+ ```
70
+
44
71
  ## Check back later
45
72
 
46
73
  A task whose answer needs time (a build, a deploy, a reply) calls `defer-task` with `delayMs` or `runAt`, a `summary` of what you did so far, and a `note` that says what is pending. The tool completes the task and creates the one-off schedule for you. The task reaches its final state (`completed`) on this call, and the `summary` becomes its output. The wake-up task carries the deferred task as its parent, so you receive that task's context. Add `checks` to list what to verify on wake-up. Do not hand-roll this with `create-schedule`.
@@ -6,10 +6,10 @@ For every task that came from Slack, the engine owns the thread tree and the top
6
6
 
7
7
  ## Your one message
8
8
 
9
- - At most one message per task, and only when the outcome card will not carry it: a question, a decision the requester must make, a link to a page or file with one line of context.
9
+ - At most one message per task, and only when the outcome card will not carry it: a question, a decision the requester must make, a link to a page or file with one line of context, or a table, chart or key figures. Send the last as a `slack-reply` `card` and keep the task `output` to one line pointing at it: the outcome card posts `output` too.
10
10
  - Progress, receipts, acknowledgments, and relayed worker output stay out of Slack.
11
11
  - Concrete content. The length matches what the requester asked for.
12
- - The "How you write" rules of your system prompt apply. Slack renders mrkdwn: `*bold*`, `_italic_`, `` `code` ``, `<url|text>` for links. Markdown headings and tables do not render.
12
+ - The "How you write" rules of your system prompt apply. Slack renders mrkdwn: `*bold*`, `_italic_`, `` `code` ``, `<url|text>` for links. Markdown headings and tables do not render. For a table or chart, send a `card`.
13
13
 
14
14
  ## Where to post
15
15
 
@@ -46,6 +46,16 @@ Files attached to your task already come with download commands in the task mess
46
46
 
47
47
  A task without `requestedByUserId` came from a Slack user the swarm does not know. Register them with `manage-user`, using the Slack user ID and display name from the task metadata, then continue. When you learn a requester's stable preferences (language, tone, verbosity), the lead stores them in the user's `comms` field with `manage-user`.
48
48
 
49
+ ## Use-case thread (lead)
50
+
51
+ A use case (a schedule and its runs under one key, see the `scheduling` skill) can post a summary of each run to one Slack thread.
52
+
53
+ 1. When you handle the follow-up of the first run (the planning session has usually ended by then), read `kv-get { namespace: "usecase:<key>", key: "thread" }`. A stored value means that you offered before: do not offer again.
54
+ 2. Offer once: "Do you want a summary of each run in a Slack channel? Tell me the channel."
55
+ 3. On no: `kv-set { namespace: "usecase:<key>", key: "thread", value: { declined: true } }`.
56
+ 4. On yes: `slack-start-thread { channelId, message }` with a one-line title, for example "Competitor watch: one summary per run". Then `kv-set { namespace: "usecase:<key>", key: "thread", value: { adapter: "slack", channelId, threadTs: "<ts from slack-start-thread>" } }`.
57
+ 5. When you finish or review a run of the use case (the run itself, or the follow-up of a worker's run): `kv-get` the thread. When it has a `threadTs`, `slack-post { channelId, threadTs, message }` with the run summary and the link to its result file.
58
+
49
59
  ## Lead standing orders
50
60
 
51
61
  When your heartbeat runbook says so, check for unaddressed requests older than one hour: `slack-list-channels`, then `slack-read` per channel, then create a task for each open request.
@@ -86,6 +86,7 @@ Fetch the page as markdown: `curl -fsSL https://docs.agent-swarm.dev/llms.mdx/do
86
86
  - [Performance & Resource Sizing](https://docs.agent-swarm.dev/docs/guides/performance-resource-sizing). Reference.
87
87
  - [Cost & context computation](https://docs.agent-swarm.dev/docs/guides/cost-and-context-computation). Reference.
88
88
  - [Extensions](https://docs.agent-swarm.dev/docs/guides/extensions). Reference.
89
+ - [File import](https://docs.agent-swarm.dev/docs/guides/file-import). Reference.
89
90
  - [Scripts runtime](https://docs.agent-swarm.dev/docs/guides/scripts-runtime). Reference.
90
91
  - [Agent capabilities and tool allowlist](https://docs.agent-swarm.dev/docs/guides/agent-capabilities). Reference.
91
92
  - [Scripts-only mode (code-mode)](https://docs.agent-swarm.dev/docs/guides/scripts-only-mode). Reference.
@@ -4,7 +4,7 @@
4
4
  "displayName": "Swarm Extensions",
5
5
  "slug": "swarm-extensions",
6
6
  "title": "Swarm Extensions",
7
- "description": "Write, install, and manage swarm extensions: TypeScript hook bundles that block, modify, or observe task creation, follow-ups, Slack routing, heartbeat remediation, and tool calls. Covers installing predefined catalog extensions (templates/extensions, YAML or JSON manifests) by name and, when EXTENSION_ALLOW_INLINE_INSTALL is on, installing an inline manifest plus files as a lead, plus the scripts, schedules, workflows and skills extensions ship, the hook contract, where to fetch swarm-extension.d.ts, the extension-catalog, extension-install and extension-list tools, config schemas, and the operator enable step.",
7
+ "description": "Write, install, and manage swarm extensions: TypeScript hook bundles that block, modify, or observe task creation, follow-ups, Slack routing, heartbeat remediation, and tool calls. Defaults to building and using inline bundles on the current swarm, with worker handoff to a lead or operator and catalog promotion only when a human asks. Covers inline install configuration, catalog installs by name, plus the scripts, schedules, workflows and skills extensions ship, the hook contract, where to fetch swarm-extension.d.ts, the extension-catalog, extension-install and extension-list tools, config schemas, and the operator enable step.",
8
8
  "version": "1.0.0",
9
9
  "category": "skills",
10
10
  "placeholders": [],
@@ -4,10 +4,14 @@ An extension is a trusted TypeScript hook bundle that runs inside the swarm API
4
4
 
5
5
  Do not use an extension for work that one task, one script, or one schedule can do.
6
6
 
7
- ## Two ways to install
7
+ ## Build and use it on this swarm first
8
8
 
9
- - **Catalog** (always on): a predefined extension in the repo (`templates/extensions/<name>/`), installed by name. Any authenticated agent can do it. To ship a catalog extension, open a PR that adds a template directory (see Bundle shape below); it becomes installable once that build is deployed.
10
- - **Inline** (opt-in): a `manifest` plus a `files` map in the install request, with no PR and no deploy. It is off unless an operator sets `EXTENSION_ALLOW_INLINE_INSTALL=true` (dashboard Settings > Configuration > Security & access, or the API environment). With the flag off the install fails with `inline_install_disabled`. With it on, only a lead, operator, or dashboard user may send an inline bundle; a worker gets 403 and stays catalog-only. An inline bundle runs as code in the API process once enabled, so write it as carefully as a catalog one.
9
+ For a new or custom extension, write an inline bundle (manifest plus every referenced file), install it on the swarm you are on, enable it, and use it. No PR or deploy is needed. Extensions are custom swarm behavior first; promoting one for other deployments comes later.
10
+
11
+ - **Inline (default authoring path):** send `manifest` plus a `files` map. This requires `EXTENSION_ALLOW_INLINE_INSTALL=true` and a lead, operator, or dashboard user. An inline bundle runs as code in the API process once enabled, so write it as carefully as a catalog one.
12
+ - **Worker handoff:** workers cannot send inline bundles (403). Stage the full bundle, including the manifest and every file, where a lead can read it, such as `/workspace/shared/extensions/<name>/` or agent-fs. Hand the location and install/enable steps to a lead or operator; do not open a catalog PR to work around worker permissions.
13
+ - **Flag off:** ask an operator to turn on `EXTENSION_ALLOW_INLINE_INSTALL` (Settings > Configuration > Security & access, or the API environment). Inline requests otherwise fail with `inline_install_disabled`. A catalog template PR is a fallback only if the operator will not enable inline installs and a human asks to promote the extension.
14
+ - **Catalog (promotion):** an existing predefined extension can be installed by name by any authenticated agent. A PR adding `templates/extensions/<name>/` promotes a proven extension to every deployment once that build ships. Open one only when a human asks for promotion.
11
15
 
12
16
  Both paths run the same validation and both land disabled.
13
17
 
@@ -62,6 +66,29 @@ curl -s "$MCP_BASE_URL/api/extensions/type-defs" \
62
66
 
63
67
  ## Bundle shape
64
68
 
69
+ Only `runtime: "api"` is supported. Inline and catalog bundles use the same manifest and referenced files.
70
+
71
+ ### Inline bundle
72
+
73
+ An inline install sends the same manifest as a JSON object, plus every file it references in `files`, keyed by bundle path:
74
+
75
+ ```json
76
+ {
77
+ "manifest": {
78
+ "name": "require-ticket-ref",
79
+ "description": "Blocks REST and MCP tasks that do not name a ticket",
80
+ "version": "1.0.0",
81
+ "runtime": "api",
82
+ "assets": { "hooks": "hooks.ts" }
83
+ },
84
+ "files": { "hooks.ts": "import { block, type SwarmExtension } from \"swarm-extension\";\n..." }
85
+ }
86
+ ```
87
+
88
+ `files` must hold `assets.hooks`, each script `file`, each workflow `file`, and for each skill `dir` its `SKILL.md` plus any `files/**`. A file the manifest does not reference is rejected. Naming rules (`<name>-` prefixes, schedule scripts declared in `assets.scripts`) are the same as for a template. To change an inline extension, send the full bundle again under the same name; it adds a new version.
89
+
90
+ ### Catalog template reference (promotion only)
91
+
65
92
  A predefined extension is a directory `templates/extensions/<name>/` with exactly one manifest, `manifest.yaml`, `manifest.yml` or `manifest.json`, plus the files it references and a `README.md`. Only `runtime: "api"` is supported. Type the manifest with the generated JSON Schema, `templates/extensions/manifest.schema.json`:
66
93
 
67
94
  ```yaml
@@ -91,24 +118,7 @@ A workflow file holds `name`, optional `description`, `definition`, and optional
91
118
 
92
119
  A JSON manifest carries `"$schema": "../manifest.schema.json"` instead. After changing a template, run `bun run build:extension-catalog` and commit `src/extensions/catalog.generated.json`.
93
120
 
94
- ### Inline bundle
95
-
96
- An inline install sends the same manifest as a JSON object, plus every file it references in `files`, keyed by bundle path:
97
-
98
- ```json
99
- {
100
- "manifest": {
101
- "name": "require-ticket-ref",
102
- "description": "Blocks REST and MCP tasks that do not name a ticket",
103
- "version": "1.0.0",
104
- "runtime": "api",
105
- "assets": { "hooks": "hooks.ts" }
106
- },
107
- "files": { "hooks.ts": "import { block, type SwarmExtension } from \"swarm-extension\";\n..." }
108
- }
109
- ```
110
-
111
- `files` must hold `assets.hooks`, each script `file`, each workflow `file`, and for each skill `dir` its `SKILL.md` plus any `files/**`. A file the manifest does not reference is rejected. Naming rules (`<name>-` prefixes, schedule scripts declared in `assets.scripts`) are the same as for a template. To change an inline extension, send the full bundle again under the same name; it adds a new version.
121
+ ### Hook rules (all bundles)
112
122
 
113
123
  Rules for `hooks.ts`:
114
124
 
@@ -162,7 +172,7 @@ export default extension;
162
172
  ## Verify
163
173
 
164
174
  1. Call `extension-list` and confirm the name, version, and `enabled: false`. The install response lists the assets it created.
165
- 2. Report the enable step. After a lead or operator enables it, the dashboard run log shows every dispatch with its result (`continue`, `modify`, `block`, or `error`).
175
+ 2. Enable it as a lead or operator, or hand off the enable step to one. After it is enabled, the dashboard run log shows every dispatch with its result (`continue`, `modify`, `block`, or `error`).
166
176
  3. Trigger the event once and confirm the effect (for example, a blocked REST task returns HTTP 422 with your reason).
167
177
 
168
178
  ## Common mistakes
@@ -173,6 +183,6 @@ export default extension;
173
183
  - Modifying fields the event does not allow. Read the `*Modify` type for that event.
174
184
  - Expecting the extension to run after install. Its hooks, schedules, workflows, and skills are off until a lead or operator enables it.
175
185
  - Expecting agents to see an extension skill after enable. Install it on each agent with `skill-install`.
176
- - Sending an inline `manifest`/`files` bundle as a worker, or without `EXTENSION_ALLOW_INLINE_INSTALL` on. Workers use a catalog `template`; with the flag off ask an operator to turn it on, or ship a catalog template.
186
+ - Sending an inline `manifest`/`files` bundle as a worker, or without `EXTENSION_ALLOW_INLINE_INSTALL` on. Workers stage the full inline bundle for a lead or operator. With the flag off, ask an operator to turn it on; a catalog PR requires a human promotion request and is a fallback only if the operator will not enable inline installs.
177
187
  - Sending both `template` and `manifest`/`files`. Pick one.
178
188
  - Blocking tasks from every origin. Check `event.origin` so schedules, workflows, and follow-ups keep working unless you mean to block them.
@@ -13,8 +13,8 @@ A swarm script is TypeScript that runs out of process with a typed Swarm SDK. On
13
13
  |---|---|
14
14
  | 1 to 9 SDK calls, result fits in context | Direct tool calls. |
15
15
  | 10 or more similar calls, bulk or fan-out | Script. Inline `script-run` for a one-off, a named script for reuse. |
16
- | Fetch, parse, and transform heavy data | Script, or `ctx_*` (context-mode) when your harness has it. |
17
- | One large web fetch | `ctx_fetch_and_index` (context-mode). |
16
+ | Fetch, parse, and transform heavy data | Script. |
17
+ | One large web fetch | Script with `ctx.stdlib.fetch`. Return only the part you need. |
18
18
  | A schedule, workflow, or API script that reads or writes drive files | Script with `ctx.fs` and `ctx.sh`. |
19
19
  | Multi-agent fan-out, parallel work, deterministic pipeline | Workflow. See `workflow-iterate`. |
20
20
  | Work that repeats on a clock | Schedule. See `scheduling`. |
@@ -68,13 +68,26 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
68
68
  - `args` can be `undefined` when a caller passes none. Guard with `argsSchema.safeParse(args ?? {})` or optional chaining.
69
69
  - Export a Zod `argsSchema` from every named script. `script-upsert` converts it to JSON Schema, so callers, schedules, and workflows see the input contract.
70
70
  - Both `zod` and `zod/mini` imports work. Use `import * as z from "zod/mini"` for smaller QuickJS bundles. Mini uses functional forms: `z.optional(z.string())`, `z._default(z.number(), 10)`, and `z.string().check(z.minLength(1))`; its schemas still have `.parse()` and `.safeParse()`.
71
- - Inline source through `script-run` runs without a typecheck. `script-upsert` typechecks before it saves. Import `ScriptContext` from `"swarm-sdk"` in inline code too, so promotion to a named script works.
71
+ - Inline source through `script-run` runs without a typecheck. `script-upsert` typechecks before it saves. Import `ScriptContext` from `"swarm-sdk"` in inline code too, so promotion to a named script works. A worker's `script-upsert` saves at agent scope; a global-scope upsert is rejected unless you are the lead. To share a script, send the lead its name and `contentHash` to promote.
72
72
  - SDK methods return `Promise<unknown>`. Responses are usually wrapped: read `res?.data ?? res`. Exception: `app_query` with a literal `appId` and `query` returns rows typed from the app's columns.
73
73
  - `agentId` is propagated through the `X-Agent-ID` header, so SDK calls run as you. `taskId` is not ambient: pass it in `args` when the script calls `task_storeProgress`.
74
74
  - A script invoked from a workflow node may run under a workflow identity. The node may also supply arguments the script needs: when you run that script directly, pass the same arguments the node maps. A script without a strict `argsSchema` then fails deeper in, often as a not-found or resource error instead of a validation error.
75
75
  - Return compact structured data. Raw logs, full HTML, big JSON arrays, and file contents stay inside the script.
76
76
  - Limits: about 30 s wall clock (up to 5 minutes where the tool exposes it), 1 MB stdout. Never sleep or loop past about 25 s. Chain `wait-for-task` calls instead. The cap also applies to a script called through `ctx.step.swarmScript`; the step's `timeoutMs` does not extend it. A long LLM call, such as a 2,000-word draft, goes in a `ctx.step.rawLlm` step inside `launch-script-run`, never in a called script. A `targetType: "script"` schedule gets 60 s; a manual `script-run` gets 30 s, so a candidate that finishes well under 30 s by hand has margin on the schedule. A nested `ctx.swarm.script_run` gets its own 30 s but runs inside its caller's remaining time: run slow children as sibling calls from the outer script, not deeper in the chain. The run ends when your default export resolves. A call you did not await gets about 2 s more and is then stopped (`quickjs` aborts it at once), so await every write that must land. That makes a `Promise.race` deadline bound the run; a nested `script_run` that lost the race keeps running on the server under its own 30 s.
77
77
 
78
+ ### Upserting a large source
79
+
80
+ A large source pasted inline into a `script-upsert` tool call overflows the call. Write the source to a local file, then send it from bash through the same route, `POST $MCP_BASE_URL/api/scripts/upsert`. The body is JSON (`name`, `source`, optional `description`, `intent`, `scope`), so wrap the file instead of sending it raw:
81
+
82
+ ```bash
83
+ jq -n --arg name my-script --rawfile source ./my-script.ts '{name: $name, source: $source}' \
84
+ | curl -sS -X POST "$MCP_BASE_URL/api/scripts/upsert" \
85
+ -H "Authorization: Bearer $API_KEY" -H "X-Agent-ID: $AGENT_ID" \
86
+ -H "Content-Type: application/json" --data-binary @-
87
+ ```
88
+
89
+ The route runs the same typecheck and scope rules as the tool.
90
+
78
91
  ### What `ctx` holds
79
92
 
80
93
  - `ctx.swarm.*`: the swarm SDK. `task_get`, `task_send`, `task_storeProgress`, `task_action`, `task_list`, `slack_reply`, `memory_search`, `memory_store`, `kv_get`, `kv_getOrNull`, `kv_set`, `kv_delete`, `kv_incr`, `kv_list`, `swarm_get`, `agent_info`, `db_query`, and more. `kv_getOrNull` returns the entry, `null` on a missing key, and throws on other errors.
@@ -82,7 +95,8 @@ export default async function (args: z.infer<typeof argsSchema>, ctx: ScriptCont
82
95
  - `ctx.swarm.config`: `apiKey`, `agentId`, `mcpBaseUrl`, and `ctx.swarm.config.get("KEY")` for swarm config values, resolved for the agent running the script (agent scope over global, the same rows `get-config` returns for that agent). A key that is not set returns `undefined`, so `config.get("KEY") ?? fallback` works. All are `Redacted` wrappers that stringify to `<redacted>`. Never unwrap one into a return value, a log line, or a request body you build by hand.
83
96
  - `ctx.api.<slug>` and `ctx.mcp.<slug>`: typed clients for registered connections. They exist only for registered connections. Introspect with `Object.keys(ctx.api ?? {})` and `Object.keys(ctx.mcp ?? {})`.
84
97
  - `ctx.fs` and `ctx.sh`: files and bash. See "Files and shell" below.
85
- - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `Redacted`.
98
+ - `ctx.stdlib`: `fetch`, `fetchJson` (retries, 30 s timeout), `grep`, `glob`, `table`, `retry`, `Redacted`.
99
+ - 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.
86
100
  - `ctx.logger`: `log`, `warn`, `error`. Keep logs short.
87
101
 
88
102
  ### Files and shell