@desplega.ai/agent-swarm 2.8.3 → 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 (491) hide show
  1. package/dist/acp-adapter-jqn86aam.js +16 -0
  2. package/dist/acp-targets-swxq55dr.js +23 -0
  3. package/dist/{actions-ewz7bp4g.js → actions-pb678g3e.js} +20 -19
  4. package/dist/agent-fs-provision-dmhnc38q.js +27 -0
  5. package/dist/{amp-adapter-f25tqhnf.js → amp-adapter-3pa66q27.js} +3 -3
  6. package/dist/{anthropic-messages-jkva0zps.js → anthropic-messages-x2cp5fvf.js} +41 -41
  7. package/dist/{app-mkptw0k7.js → app-17d12ev4.js} +6 -4
  8. package/dist/approval-notifications-h7vd9pmg.js +20 -0
  9. package/dist/{assistant-c47rfe77.js → assistant-t7k39ree.js} +54 -33
  10. package/dist/{azure-openai-responses-wgtqkbr3.js → azure-openai-responses-590s1eea.js} +10 -10
  11. package/dist/{boot-args-schema-4vb0xsat.js → boot-args-schema-0gqmkfbe.js} +1 -1
  12. package/dist/{boot-reembed-1ghy2sab.js → boot-reembed-f064w382.js} +1 -1
  13. package/dist/{boot-reembed-htr73hbs.js → boot-reembed-n6anc01d.js} +1 -1
  14. package/dist/{boot-scrub-sweep-yrytg42z.js → boot-scrub-sweep-ejd5dnrz.js} +84 -13
  15. package/dist/{boot-seeds-n2b3dx4e.js → boot-seeds-f99fjs5q.js} +4 -4
  16. package/dist/{boxd-jmfqgkqa.js → boxd-wn235q80.js} +7 -7
  17. package/dist/claude-adapter-gvznwxgc.js +28 -0
  18. package/dist/{claude-managed-adapter-hddmxjyj.js → claude-managed-adapter-pbrbvc64.js} +4 -4
  19. package/dist/{claude-managed-setup-hfvry1bd.js → claude-managed-setup-kdxttvc3.js} +10 -10
  20. package/dist/{claude-sdk-session-0hamqzc7.js → claude-sdk-session-0t2teq6n.js} +9386 -9196
  21. package/dist/{cli-yjdgea32.js → cli-1jx0srjt.js} +17 -17
  22. package/dist/{cli-s8p8hhty.js → cli-1tvdx9t5.js} +2 -2
  23. package/dist/{cli-s7zz734a.js → cli-25nstr34.js} +1 -1
  24. package/dist/{cli-kw44j53p.js → cli-2kg31ted.js} +45 -38
  25. package/dist/{cli-mwwmka77.js → cli-2tnbc3gw.js} +375 -127
  26. package/dist/{cli-4dpkjc2e.js → cli-3zxdz9r7.js} +9 -9
  27. package/dist/{cli-mdpbjnzq.js → cli-4ghh072d.js} +14 -14
  28. package/dist/{cli-54qr8mcd.js → cli-57pvhnyt.js} +4 -4
  29. package/dist/{cli-f1kwb5fc.js → cli-5a6pqy45.js} +333 -21
  30. package/dist/{cli-93t5s4zq.js → cli-5gpqgs8b.js} +2 -2
  31. package/dist/{cli-4ax9mvvg.js → cli-5gygrr67.js} +9 -9
  32. package/dist/{cli-t5ys4ebm.js → cli-5kcmxwxv.js} +3 -3
  33. package/dist/{cli-k96cecs7.js → cli-5ntc4we6.js} +2948 -316
  34. package/dist/{cli-15204js0.js → cli-6237rnyr.js} +1 -1
  35. package/dist/cli-6dp0jkfj.js +754 -0
  36. package/dist/{cli-k2rw11py.js → cli-7831nhaw.js} +5 -5
  37. package/dist/{cli-7c5tgqhf.js → cli-7cgf614g.js} +10 -10
  38. package/dist/{cli-z8cvws4c.js → cli-7fx9jyfs.js} +852 -55
  39. package/dist/{cli-pe4d96rb.js → cli-7zm3b3f5.js} +1 -1
  40. package/dist/{cli-0bcgyj5b.js → cli-812paz57.js} +69 -6
  41. package/dist/{cli-ztq5z4e1.js → cli-8axx8vnw.js} +4 -4
  42. package/dist/cli-8x8y70av.js +103 -0
  43. package/dist/{cli-6yygkr0w.js → cli-95930z69.js} +15 -7
  44. package/dist/{cli-sdvcrq5x.js → cli-9a2rtd77.js} +16 -14
  45. package/dist/cli-9ttx00s3.js +137 -0
  46. package/dist/{cli-6ek0hff4.js → cli-a9hfzg2r.js} +3 -3
  47. package/dist/{cli-am1ptset.js → cli-aa8s22gn.js} +19 -14
  48. package/dist/{cli-4e1hfbpq.js → cli-bk9v1xrv.js} +19 -19
  49. package/dist/{cli-e2w34h6z.js → cli-c07v0qfa.js} +98 -54
  50. package/dist/{cli-dpsfwh7n.js → cli-c5cspahx.js} +24 -24
  51. package/dist/{cli-gpz1d0t2.js → cli-cw7mc1je.js} +4 -4
  52. package/dist/{cli-qmqt520k.js → cli-dd37e0cm.js} +2 -2
  53. package/dist/cli-dqgnbnxs.js +132 -0
  54. package/dist/{cli-tnzebztn.js → cli-dx439zpg.js} +1 -1
  55. package/dist/{cli-q6mfk1ej.js → cli-dzzh58sy.js} +2 -2
  56. package/dist/{cli-knva3nmx.js → cli-e9973bf0.js} +8 -6
  57. package/dist/{cli-2znm3dzj.js → cli-eds5xnsz.js} +2 -2
  58. package/dist/{cli-crpf163n.js → cli-eepnpee7.js} +16 -26
  59. package/dist/{cli-nx2n3z6p.js → cli-eg437b5p.js} +1 -1
  60. package/dist/{cli-zdaypkq9.js → cli-faf46gdq.js} +285 -97
  61. package/dist/{cli-tas6ckky.js → cli-fgphc007.js} +2 -2
  62. package/dist/{cli-sg27rk2t.js → cli-fnh4b12r.js} +24 -18
  63. package/dist/{cli-fsgttth8.js → cli-g0vv9dg4.js} +13 -13
  64. package/dist/{cli-rqfvkx5t.js → cli-g3zzby8t.js} +13 -13
  65. package/dist/{cli-kd56bmk4.js → cli-gabsjg8x.js} +3 -1
  66. package/dist/{cli-tf79ryyy.js → cli-gddgcnav.js} +3 -3
  67. package/dist/{cli-rjvsf9qa.js → cli-h474mvp5.js} +11 -11
  68. package/dist/{cli-5a7szzfh.js → cli-hnamkvnc.js} +2 -2
  69. package/dist/{cli-8bpgbr8k.js → cli-j49yqpvh.js} +6 -6
  70. package/dist/{cli-awwptga4.js → cli-jd3kxppb.js} +1 -1
  71. package/dist/{cli-1m96dc36.js → cli-js8zrfyg.js} +3 -3
  72. package/dist/{cli-vx421edw.js → cli-k09cxm6m.js} +9 -7
  73. package/dist/{cli-n5t077me.js → cli-k7pt28ad.js} +10 -3
  74. package/dist/{cli-922z7gwm.js → cli-kaa4bd7x.js} +9 -6
  75. package/dist/cli-kj0hyr43.js +51 -0
  76. package/dist/{cli-c0xjnr8z.js → cli-kmvcm34h.js} +2 -2
  77. package/dist/{cli-0vksaxvr.js → cli-kqh27v2y.js} +2 -2
  78. package/dist/{cli-bj6qhgte.js → cli-m1fbz2wj.js} +30 -37
  79. package/dist/{cli-me0r8gzr.js → cli-mc1fx4xd.js} +27 -25
  80. package/dist/{cli-qps8je6j.js → cli-me4maa4j.js} +46 -6
  81. package/dist/{cli-504akrp9.js → cli-meydjstb.js} +3 -3
  82. package/dist/{cli-n30e0hcp.js → cli-mna6pmfx.js} +2 -2
  83. package/dist/{cli-yss07azk.js → cli-nhq5js1b.js} +3 -3
  84. package/dist/cli-nmcpzbty.js +296 -0
  85. package/dist/cli-nr46j5pw.js +78 -0
  86. package/dist/{cli-t4dv07kr.js → cli-pn1v1pb0.js} +1 -1
  87. package/dist/{cli-c71n3bxq.js → cli-pwsax0vp.js} +2 -2
  88. package/dist/{cli-9zmb7ptc.js → cli-pz1c00aa.js} +8 -753
  89. package/dist/{cli-emekyyhr.js → cli-q2d3e1k1.js} +1 -1
  90. package/dist/{cli-zeaehgyd.js → cli-q8cfh1t9.js} +2 -2
  91. package/dist/{cli-vqva1teb.js → cli-qe909n63.js} +2 -2
  92. package/dist/{cli-2d0cghfn.js → cli-qj39vrc6.js} +1 -1
  93. package/dist/{cli-0agcv1v5.js → cli-rqx70rcz.js} +2 -2
  94. package/dist/{cli-gn9y6fn7.js → cli-rts1qvb4.js} +2 -2
  95. package/dist/{cli-pxwtcgcp.js → cli-sn4pc4qx.js} +2 -2
  96. package/dist/{cli-98rwmcyc.js → cli-snxhtehz.js} +3 -3
  97. package/dist/{cli-d829z3xc.js → cli-spfz393q.js} +6 -6
  98. package/dist/{cli-6wj7p986.js → cli-spzkdgtg.js} +3 -3
  99. package/dist/{cli-m2z8jagn.js → cli-srtkr1h2.js} +18 -18
  100. package/dist/{cli-8476gtwf.js → cli-ssvdrk4y.js} +1 -1
  101. package/dist/{cli-c3ng0mb4.js → cli-svc803vq.js} +69 -816
  102. package/dist/{cli-500c09j9.js → cli-t9ga4qmb.js} +14 -14
  103. package/dist/{cli-j8cjdzan.js → cli-vs9vdpy0.js} +1 -1
  104. package/dist/{cli-bhsfbmk8.js → cli-vvgaz8t6.js} +93 -44
  105. package/dist/{cli-kmemts3w.js → cli-vw5x18yj.js} +39 -69
  106. package/dist/{cli-x3ex5bqf.js → cli-w16kwbzw.js} +1 -1
  107. package/dist/cli-w7dxb2fj.js +921 -0
  108. package/dist/{cli-x6t50dmw.js → cli-wr1h0k28.js} +3 -3
  109. package/dist/{cli-skmhsnqh.js → cli-x40a0w9j.js} +1 -1
  110. package/dist/{cli-k28wkapa.js → cli-xf1wn5ns.js} +2 -2
  111. package/dist/{cli-rh15cakt.js → cli-xwsm6xkr.js} +1 -1
  112. package/dist/{cli-h9yy18gy.js → cli-ymct0ycy.js} +262 -100
  113. package/dist/{cli-dtdht77h.js → cli-zg3z63x3.js} +2 -2
  114. package/dist/cli.js +27 -24
  115. package/dist/{codex-adapter-2brxx5ta.js → codex-adapter-44yq2fkn.js} +9 -8
  116. package/dist/{codex-hook-c930c3ea.js → codex-hook-h1zb7cfk.js} +6 -6
  117. package/dist/{codex-login-cbrs1h5w.js → codex-login-cdyrr5y1.js} +1 -1
  118. package/dist/{codex-session-runner-y9anfj0r.js → codex-session-runner-zbh26gbw.js} +10 -9
  119. package/dist/{commands-wn9q06qr.js → commands-54f02v5b.js} +3 -3
  120. package/dist/{controller-fw608czd.js → controller-9gpwcdek.js} +6 -6
  121. package/dist/{controllers-connect-63j5rdcm.js → controllers-connect-61re6k1n.js} +26 -25
  122. package/dist/{cursor-adapter-6mb9jme8.js → cursor-adapter-7e4g81vd.js} +2 -2
  123. package/dist/{db-y4wfrzbm.js → db-dg2gc7fd.js} +15 -13
  124. package/dist/{db-0m6v5tq4.js → db-wnh0qjy1.js} +3 -3
  125. package/dist/{devin-adapter-r0yx3gv8.js → devin-adapter-zp4tqq53.js} +1 -1
  126. package/dist/{dispatcher-9tq2zzdj.js → dispatcher-jrm24r43.js} +19 -18
  127. package/dist/{docker-j75atvpt.js → docker-9aq30pp2.js} +5 -5
  128. package/dist/{dsh-adapter-t09sv4tq.js → dsh-adapter-1yqk267c.js} +2 -2
  129. package/dist/{e2b-a7vzs2vj.js → e2b-3v1e745x.js} +6 -6
  130. package/dist/{e2b-7s9dscap.js → e2b-sm28k0k3.js} +6 -6
  131. package/dist/{easter-egg-3d-fbwvmwhe.js → easter-egg-3d-r4h9cs9m.js} +1 -1
  132. package/dist/{embedding-space-wh8de1t9.js → embedding-space-bafjr5f7.js} +6 -6
  133. package/dist/{embeddings-3hpbdtjr.js → embeddings-7xmgqe0e.js} +1 -1
  134. package/dist/{event-bus-tr6h3gv8.js → event-bus-xr83x566.js} +1 -1
  135. package/dist/{execute-4bdf8sdy.js → execute-d6jg5ns0.js} +1 -1
  136. package/dist/{external-channel-ts2fwqh0.js → external-channel-frq1xvq2.js} +2 -2
  137. package/dist/fx-adapter-0zrkfbkd.js +19 -0
  138. package/dist/{getMachineId-bsd-nfgrzarv.js → getMachineId-bsd-637a7rbk.js} +3 -3
  139. package/dist/{getMachineId-darwin-wz886dsk.js → getMachineId-darwin-9vytrcnn.js} +3 -3
  140. package/dist/{getMachineId-linux-1nng3p1p.js → getMachineId-linux-mkzsvyyz.js} +3 -3
  141. package/dist/{getMachineId-unsupported-a0428vw9.js → getMachineId-unsupported-4cfs2n11.js} +3 -3
  142. package/dist/{getMachineId-win-h45922nq.js → getMachineId-win-154s3qma.js} +3 -3
  143. package/dist/{google-generative-ai-h7s3e9kk.js → google-generative-ai-hh7strj3.js} +1 -1
  144. package/dist/{google-vertex-fhxaafzw.js → google-vertex-fy5bw2pm.js} +5 -5
  145. package/dist/grok-adapter-3db1c538.js +19 -0
  146. package/dist/handlers-k22n8mnn.js +33 -0
  147. package/dist/{heartbeat-2ze5fzpc.js → heartbeat-6bpa611t.js} +22 -21
  148. package/dist/{hook-ca54yd4s.js → hook-hvm5nf46.js} +5 -5
  149. package/dist/{hook-gaehe2w5.js → hook-w12k146y.js} +14 -14
  150. package/dist/{http-jfg8t2yk.js → http-43tthdvs.js} +1684 -509
  151. package/dist/{index-d6wkh8ar.js → index-1f0vypbg.js} +2 -2
  152. package/dist/{index-enn321kd.js → index-42jq9yy3.js} +3 -3
  153. package/dist/{index-khe3gp0k.js → index-4b1q8kan.js} +20 -20
  154. package/dist/{index-hjhfk3ra.js → index-585gyczt.js} +1 -1
  155. package/dist/index-8xcyd3mc.js +33 -0
  156. package/dist/index-9sy2bh6n.js +38 -0
  157. package/dist/{index-2skqtd76.js → index-b24j7t2m.js} +30 -28
  158. package/dist/{index-gjwaqaq8.js → index-cret47a5.js} +6 -6
  159. package/dist/{index-qwj6ntem.js → index-e3krvkh2.js} +4 -4
  160. package/dist/{index-csgrxedz.js → index-fn054vsf.js} +1 -1
  161. package/dist/{index-3yvzbhxd.js → index-ftywhyr0.js} +129 -142
  162. package/dist/{index-3gv6sc4z.js → index-mhq4sh5w.js} +1 -1
  163. package/dist/index-tx9mc2ap.js +570 -0
  164. package/dist/index-wjd56k1v.js +34 -0
  165. package/dist/{keepalive-k2a3qe73.js → keepalive-rk0j0jvh.js} +4 -4
  166. package/dist/lead-atxf3q6e.js +72 -0
  167. package/dist/{maintenance-gb5sd5nc.js → maintenance-g6z6kaxw.js} +1 -1
  168. package/dist/{node-252anz2h.js → node-jftbyawr.js} +4 -4
  169. package/dist/{node-ray25snp.js → node-zd6shky9.js} +3 -3
  170. package/dist/{oauth-refresh-sweep-y7rm6bkb.js → oauth-refresh-sweep-2k3g2q4w.js} +3 -3
  171. package/dist/{onboard-jmc5qerv.js → onboard-6fdbvh3v.js} +8 -8
  172. package/dist/{openai-codex-responses-k9gapdze.js → openai-codex-responses-bkcd8pjj.js} +9 -9
  173. package/dist/{openai-responses-4d5dx3c7.js → openai-responses-gbh0wfqe.js} +13 -13
  174. package/dist/{opencode-adapter-7eade9ev.js → opencode-adapter-fdbsvts7.js} +7 -6
  175. package/dist/{otel-impl-8j1xhxqd.js → otel-impl-rvwtc09q.js} +110 -110
  176. package/dist/pending-sqkrb836.js +80 -0
  177. package/dist/{pi-mono-adapter-yqmaf32x.js → pi-mono-adapter-asqayqcg.js} +12 -12
  178. package/dist/{pricing-refresh-1nj722h6.js → pricing-refresh-f5tkgmw2.js} +2 -2
  179. package/dist/{rbac-roles-b1mtr6dr.js → rbac-roles-06s555fa.js} +3 -3
  180. package/dist/{rbac-roles-n1f3frk1.js → rbac-roles-szxsg8t1.js} +10 -3
  181. package/dist/{render-v2-1gfpd8rj.js → render-v2-103p266q.js} +4 -4
  182. package/dist/{resume-w1s1eh5v.js → resume-v7kjewt9.js} +8 -7
  183. package/dist/{runtime-84g5egsc.js → runtime-f1gmk0b7.js} +1 -1
  184. package/dist/{session-access-y6z1txk4.js → session-access-6shev8ts.js} +4 -4
  185. package/dist/{session-source-backfill-gxxwfh12.js → session-source-backfill-bd7spzjd.js} +3 -3
  186. package/dist/{setup-r91gstyk.js → setup-kmxmztdb.js} +1 -1
  187. package/dist/thread-buffer-4yz236d0.js +36 -0
  188. package/dist/{virtual-modules-cgnj6kme.js → virtual-modules-57eje5wy.js} +5 -5
  189. package/dist/{work-objects-qcxzg61c.js → work-objects-zr47ygmf.js} +23 -21
  190. package/dist/{worker-follow-up-y2d2h7km.js → worker-follow-up-grrr3fda.js} +19 -18
  191. package/dist/worker-p4hbtcy3.js +72 -0
  192. package/dist/{x-qhxq2ama.js → x-wg164ss9.js} +2 -2
  193. package/openapi.json +1211 -155
  194. package/package.json +9 -6
  195. package/plugin/commands/create-pr.md +1 -1
  196. package/plugin/pi-skills/create-pr/SKILL.md +1 -1
  197. package/src/apps/action-runner.ts +21 -1
  198. package/src/apps/catalog.generated.json +626 -17
  199. package/src/apps/page-validator.ts +314 -8
  200. package/src/assets/key.ts +6 -0
  201. package/src/be/agent-fs-user-keys.ts +186 -0
  202. package/src/be/audit-user.ts +27 -13
  203. package/src/be/automation-preflight.test.ts +14 -14
  204. package/src/be/automation-preflight.ts +24 -16
  205. package/src/be/boot-scrub-sweep.ts +143 -14
  206. package/src/be/caller-session-group.ts +86 -0
  207. package/src/be/checklist.ts +375 -0
  208. package/src/be/db/agents.ts +12 -1
  209. package/src/be/db/approvals.ts +26 -0
  210. package/src/be/db/session-moves.ts +23 -0
  211. package/src/be/db/session-tree.ts +78 -19
  212. package/src/be/db/tasks/eligibility-scan.ts +14 -0
  213. package/src/be/db/tasks/slack-fold.ts +116 -0
  214. package/src/be/db/tasks/write.ts +34 -0
  215. package/src/be/db-queries/mcp-servers.ts +13 -0
  216. package/src/be/db-queries/oauth.ts +6 -0
  217. package/src/be/db-queries/task-artifacts.ts +10 -8
  218. package/src/be/db.ts +42 -15
  219. package/src/be/extensions/assets.ts +17 -13
  220. package/src/be/import/config.ts +54 -0
  221. package/src/be/import/dir-source.ts +372 -0
  222. package/src/be/import/index.ts +149 -0
  223. package/src/be/import/pending.ts +71 -0
  224. package/src/be/import/schema.ts +137 -0
  225. package/src/be/import/seeders.ts +462 -0
  226. package/src/be/migrations/297_import_ownership.sql +34 -0
  227. package/src/be/migrations/301_favorites_key_type.sql +36 -0
  228. package/src/be/migrations/302_checklist_items.sql +23 -0
  229. package/src/be/multi-runtime.ts +8 -1
  230. package/src/be/rbac-roles.ts +8 -1
  231. package/src/be/runtime-pools/demand.ts +20 -2
  232. package/src/be/runtime-pools/reachability.ts +31 -0
  233. package/src/be/runtime-pools/routing.ts +8 -1
  234. package/src/be/runtime-pools/supervisor.ts +6 -7
  235. package/src/be/savings/read.ts +8 -6
  236. package/src/be/script-credential-broker.ts +2 -2
  237. package/src/be/scripts/typecheck.ts +4 -4
  238. package/src/be/seed/agent-fs-provision.ts +104 -19
  239. package/src/be/seed/index.ts +1 -1
  240. package/src/be/seed/registry.ts +27 -8
  241. package/src/be/seed/runner.ts +1 -1
  242. package/src/be/seed/schedules-seeder.ts +24 -6
  243. package/src/be/seed/seed-toggle.ts +32 -0
  244. package/src/be/seed/types.ts +6 -0
  245. package/src/be/seed-scripts/catalog/dreaming-gather.ts +2 -2
  246. package/src/be/steering.ts +27 -4
  247. package/src/be/swarm-config-guard.ts +30 -0
  248. package/src/be/task-citations.ts +8 -5
  249. package/src/commands/onboard/agent-fs-version.ts +1 -1
  250. package/src/commands/runner.ts +61 -2
  251. package/src/e2b/env.ts +2 -0
  252. package/src/extensions/catalog.generated.json +17 -0
  253. package/src/extensions/contract-types.generated.ts +1 -1
  254. package/src/github/app.ts +10 -1
  255. package/src/github/handlers.ts +6 -3
  256. package/src/github/reactions.ts +12 -14
  257. package/src/heartbeat/heartbeat.ts +14 -4
  258. package/src/http/agents.ts +19 -10
  259. package/src/http/all-routes.ts +2 -0
  260. package/src/http/approval-requests.ts +24 -4
  261. package/src/http/apps.ts +69 -5
  262. package/src/http/checklist.ts +176 -0
  263. package/src/http/db-query-bounded.ts +256 -11
  264. package/src/http/db-query-shared.ts +9 -0
  265. package/src/http/favorites.ts +14 -2
  266. package/src/http/fs.ts +346 -1
  267. package/src/http/index.ts +29 -1
  268. package/src/http/kv.ts +13 -0
  269. package/src/http/mcp-oauth.ts +1 -1
  270. package/src/http/mcp-servers.ts +15 -2
  271. package/src/http/onboarding.ts +2 -9
  272. package/src/http/poll.ts +45 -0
  273. package/src/http/script-connections.ts +1 -0
  274. package/src/http/sessions.ts +17 -0
  275. package/src/http/slack-events.ts +101 -0
  276. package/src/http/status.ts +25 -7
  277. package/src/http/task-requester.ts +46 -0
  278. package/src/http/tasks.ts +64 -37
  279. package/src/http/users.ts +14 -0
  280. package/src/http/webhooks.ts +15 -0
  281. package/src/integrations/cards/index.ts +151 -0
  282. package/src/integrations/chat-sdk/outbound.ts +39 -13
  283. package/src/integrations/chat-sdk/runtime.ts +7 -1
  284. package/src/integrations/chat-sdk/status.ts +17 -0
  285. package/src/integrations/chat-sdk/telegram-api.ts +6 -1
  286. package/src/kv-reserved-namespaces.ts +17 -2
  287. package/src/oauth/presets.ts +29 -2
  288. package/src/prompts/base-prompt.ts +17 -4
  289. package/src/prompts/session-templates.ts +83 -6
  290. package/src/providers/acp-targets.ts +1 -1
  291. package/src/providers/amp-adapter.ts +1 -1
  292. package/src/providers/claude-managed-adapter.ts +5 -1
  293. package/src/providers/codex-adapter.ts +1 -1
  294. package/src/providers/codex-app-server.ts +2 -11
  295. package/src/providers/opencode-adapter.ts +7 -19
  296. package/src/providers/runtime-dependencies.ts +158 -0
  297. package/src/rbac/legacy-policy.ts +2 -0
  298. package/src/rbac/permissions.ts +10 -1
  299. package/src/scripts-runtime/credential-broker/default-bindings.ts +19 -11
  300. package/src/scripts-runtime/credential-broker/index.ts +1 -1
  301. package/src/scripts-runtime/egress-secrets.ts +2 -2
  302. package/src/scripts-runtime/swarm-sdk.ts +3 -2
  303. package/src/scripts-runtime/types/stdlib.d.ts +11 -4
  304. package/src/scripts-runtime/types/swarm-extension.d.ts +1 -1
  305. package/src/scripts-runtime/types/swarm-sdk.d.ts +11 -4
  306. package/src/server.ts +4 -4
  307. package/src/slack/app.ts +87 -46
  308. package/src/slack/assistant.ts +33 -7
  309. package/src/slack/handlers.ts +6 -4
  310. package/src/slack/http-receiver.ts +284 -0
  311. package/src/slack/inbound-dispatch.ts +43 -7
  312. package/src/slack/inbound-files.ts +33 -14
  313. package/src/slack/message-text.ts +47 -4
  314. package/src/slack/render-v2.ts +2 -1
  315. package/src/slack/socket-ack.ts +17 -10
  316. package/src/slack/steering.ts +5 -0
  317. package/src/slack/thread-buffer-store.ts +58 -0
  318. package/src/slack/thread-buffer.ts +341 -57
  319. package/src/tasks/context-key.ts +24 -0
  320. package/src/tasks/sibling-awareness.ts +13 -1
  321. package/src/tests/agent-fs-live-url.test.ts +15 -0
  322. package/src/tests/agent-fs-provision-seeder.test.ts +140 -0
  323. package/src/tests/agent-fs-user-keys.test.ts +483 -0
  324. package/src/tests/agentfs-proxy.test.ts +8 -8
  325. package/src/tests/approval-card-resolution.test.ts +396 -0
  326. package/src/tests/approval-requests-notifications.test.ts +1 -1
  327. package/src/tests/approval-respond-auth.test.ts +28 -0
  328. package/src/tests/apps-action-parent-task.test.ts +140 -0
  329. package/src/tests/apps-catalog-additions.test.ts +315 -0
  330. package/src/tests/apps-catalog-files.test.ts +114 -0
  331. package/src/tests/apps-catalog-hitl.test.ts +117 -0
  332. package/src/tests/apps-catalog-inputs.test.ts +86 -0
  333. package/src/tests/apps-catalog-table.test.ts +47 -0
  334. package/src/tests/apps-chart-shell.test.ts +1 -1
  335. package/src/tests/apps-element-assembly.test.ts +52 -3
  336. package/src/tests/apps-session-thread.test.ts +182 -0
  337. package/src/tests/asset-key-invariants.test.ts +14 -0
  338. package/src/tests/base-prompt.test.ts +107 -23
  339. package/src/tests/boot-scrub-sweep.test.ts +172 -0
  340. package/src/tests/caller-session-group.test.ts +199 -0
  341. package/src/tests/cards.test.ts +169 -0
  342. package/src/tests/chat-sdk-status-route.test.ts +16 -3
  343. package/src/tests/chat-sdk-telegram-token.test.ts +76 -0
  344. package/src/tests/chat-sdk-tools.test.ts +147 -0
  345. package/src/tests/checklist-nudge.test.ts +208 -0
  346. package/src/tests/checklist.test.ts +686 -0
  347. package/src/tests/codex-app-server.test.ts +16 -0
  348. package/src/tests/comb-config-guard.test.ts +21 -0
  349. package/src/tests/comb-default.test.ts +59 -97
  350. package/src/tests/comb-links.test.ts +86 -16
  351. package/src/tests/comb-status.test.ts +24 -27
  352. package/src/tests/create-page-tool.test.ts +101 -1
  353. package/src/tests/create-schedule-key.test.ts +105 -0
  354. package/src/tests/credential-broker.test.ts +2 -2
  355. package/src/tests/db-query.test.ts +87 -1
  356. package/src/tests/db-task-read-contract.test.ts +1 -0
  357. package/src/tests/db-task-write-contract.test.ts +2 -1
  358. package/src/tests/docs-index-footprint.test.js +3 -3
  359. package/src/tests/entrypoint-github-enterprise.test.ts +158 -0
  360. package/src/tests/extensions-assets.test.ts +7 -3
  361. package/src/tests/extensions-catalog.test.ts +1 -0
  362. package/src/tests/extensions-example-sql-admin-only.test.ts +198 -0
  363. package/src/tests/extensions-pre-task.test.ts +3 -3
  364. package/src/tests/extensions-steering.test.ts +14 -2
  365. package/src/tests/favorites-agent-fs-path.test.ts +124 -0
  366. package/src/tests/fetch-resolved-env.test.ts +68 -0
  367. package/src/tests/fixtures/import-package.ts +32 -0
  368. package/src/tests/fixtures/runner-missing-dependency.ts +129 -0
  369. package/src/tests/fs-routes.test.ts +505 -2
  370. package/src/tests/github-ghes-mock.test.ts +196 -0
  371. package/src/tests/github-host.test.ts +285 -0
  372. package/src/tests/heartbeat-supersede-resume.test.ts +73 -0
  373. package/src/tests/heartbeat.test.ts +56 -0
  374. package/src/tests/import-config.test.ts +209 -0
  375. package/src/tests/import.test.ts +464 -0
  376. package/src/tests/invites-http.test.ts +144 -1
  377. package/src/tests/kv-http.test.ts +11 -0
  378. package/src/tests/literal-matcher.test.ts +58 -0
  379. package/src/tests/mcp-oauth-manual-client.test.ts +1 -1
  380. package/src/tests/oauth-presets.test.ts +12 -0
  381. package/src/tests/pool-affinity.test.ts +50 -0
  382. package/src/tests/prompt-template-session.test.ts +52 -5
  383. package/src/tests/provider-registration.test.ts +2 -55
  384. package/src/tests/provider-runtime-dependencies.test.ts +212 -0
  385. package/src/tests/rbac-admission.test.ts +19 -0
  386. package/src/tests/rbac-charact-misc-tools.test.ts +31 -0
  387. package/src/tests/rbac-engine.test.ts +2 -0
  388. package/src/tests/rbac-roles.test.ts +2 -0
  389. package/src/tests/runner-missing-dependency.test.ts +61 -0
  390. package/src/tests/runtime-pool-reachability.test.ts +135 -1
  391. package/src/tests/runtime-pool-routing.test.ts +52 -0
  392. package/src/tests/runtime-stale-threshold.test.ts +40 -0
  393. package/src/tests/savings-fleet-slices.test.ts +122 -0
  394. package/src/tests/savings-read.test.ts +41 -0
  395. package/src/tests/savings-scripts.test.ts +9 -3
  396. package/src/tests/script-connections.test.ts +2 -0
  397. package/src/tests/script-executor-conformance.test.ts +41 -4
  398. package/src/tests/secret-scrub-gate.test.ts +257 -0
  399. package/src/tests/seed-registry.test.ts +142 -9
  400. package/src/tests/session-source-keys.test.ts +42 -1
  401. package/src/tests/sessions-move.test.ts +70 -0
  402. package/src/tests/sessions-tree.test.ts +98 -0
  403. package/src/tests/sessions.test.ts +69 -0
  404. package/src/tests/slack-config.test.ts +4 -18
  405. package/src/tests/slack-http-receiver.test.ts +472 -0
  406. package/src/tests/slack-inbound-logging.test.ts +64 -0
  407. package/src/tests/slack-leave-thread.test.ts +1 -1
  408. package/src/tests/slack-message-text.test.ts +104 -0
  409. package/src/tests/slack-mode-lifecycle.test.ts +6 -4
  410. package/src/tests/slack-render-v2.test.ts +48 -0
  411. package/src/tests/slack-skip-reaction.test.ts +2 -2
  412. package/src/tests/slack-steering.test.ts +22 -10
  413. package/src/tests/slack-thread-buffer-context.test.ts +1 -1
  414. package/src/tests/slack-thread-buffer-fold.test.ts +417 -0
  415. package/src/tests/slack-thread-buffer-restore.test.ts +198 -0
  416. package/src/tests/slack-thread-buffer-startup-restore.test.ts +86 -0
  417. package/src/tests/slack-thread-buffer.test.ts +34 -34
  418. package/src/tests/slack-thread-participants.test.ts +23 -5
  419. package/src/tests/slack-tool-blocks.test.ts +167 -0
  420. package/src/tests/status.test.ts +32 -6
  421. package/src/tests/steering-core.test.ts +13 -0
  422. package/src/tests/steering-enabled.test.ts +7 -1
  423. package/src/tests/steering-promotion.test.ts +24 -0
  424. package/src/tests/swarm-config-reserved-keys.test.ts +17 -0
  425. package/src/tests/system-one-hosts-ui-mirror.test.ts +67 -0
  426. package/src/tests/task-artifacts.test.ts +50 -0
  427. package/src/tests/task-session-prompts.test.ts +95 -1
  428. package/src/tests/workflow-system-one-extraction.test.ts +149 -1
  429. package/src/tools/chat-post.ts +19 -4
  430. package/src/tools/chat-reply.ts +20 -4
  431. package/src/tools/create-page.ts +21 -4
  432. package/src/tools/get-swarm.ts +18 -2
  433. package/src/tools/join-swarm.ts +2 -1
  434. package/src/tools/kv/kv-write-auth.ts +17 -1
  435. package/src/tools/schedules/create-schedule.ts +22 -4
  436. package/src/tools/slack-post.ts +40 -7
  437. package/src/tools/slack-reply.ts +50 -14
  438. package/src/types.ts +43 -2
  439. package/src/utils/constants.ts +60 -138
  440. package/src/utils/github-host.ts +217 -0
  441. package/src/utils/github-pull-request.ts +8 -5
  442. package/src/utils/literal-matcher.ts +118 -0
  443. package/src/utils/secret-scrubber.ts +331 -25
  444. package/src/utils/task-attachment-links.ts +9 -12
  445. package/src/vcs/index.ts +3 -0
  446. package/src/workflows/approval-notifications.ts +188 -12
  447. package/src/workflows/executors/system-one-extraction.ts +14 -7
  448. package/src/workflows/executors/system-one-providers.ts +22 -1
  449. package/templates/community/open-prompt-showreel/PLAYBOOK.md +1 -1
  450. package/templates/community/open-prompt-showreel/skills/open-prompt-showreel/SKILL.md +1 -1
  451. package/templates/extensions/README.md +1 -0
  452. package/templates/extensions/sql-admin-only/README.md +19 -0
  453. package/templates/extensions/sql-admin-only/hooks.ts +96 -0
  454. package/templates/extensions/sql-admin-only/manifest.json +8 -0
  455. package/templates/import/manifest.schema.json +136 -0
  456. package/templates/import/sources.schema.json +44 -0
  457. package/templates/skills/agent-browser/SKILL.md +1 -1
  458. package/templates/skills/agent-browser/content.md +1 -1
  459. package/templates/skills/apps/SKILL.md +122 -12
  460. package/templates/skills/apps/content.md +122 -12
  461. package/templates/skills/asset-namespaces/content.md +2 -1
  462. package/templates/skills/chat-sdk/content.md +17 -0
  463. package/templates/skills/db-query-guidance/content.md +2 -1
  464. package/templates/skills/scheduling/content.md +27 -0
  465. package/templates/skills/slack-interaction/content.md +12 -2
  466. package/templates/skills/swarm-docs/content.md +1 -0
  467. package/templates/skills/swarm-extensions/config.json +1 -1
  468. package/templates/skills/swarm-extensions/content.md +33 -23
  469. package/templates/skills/swarm-scripts/SKILL.md +13 -0
  470. package/templates/skills/swarm-scripts/content.md +13 -0
  471. package/templates/skills/work-on-task/SKILL.md +1 -1
  472. package/templates/skills/work-on-task/content.md +1 -1
  473. package/templates/skills/workflow-iterate/content.md +4 -7
  474. package/templates/workflows/dreaming/content.md +2 -2
  475. package/dist/acp-adapter-xq6s2z6t.js +0 -14
  476. package/dist/claude-adapter-r33pqnzx.js +0 -24
  477. package/dist/cli-dns0y538.js +0 -194
  478. package/dist/fx-adapter-1rnxnf56.js +0 -17
  479. package/dist/grok-adapter-efhmf1r8.js +0 -17
  480. package/dist/handlers-anrr3py9.js +0 -32
  481. package/dist/index-8w2aznds.js +0 -33
  482. package/dist/index-qnjvr362.js +0 -37
  483. package/dist/index-yzxd3sn9.js +0 -32
  484. package/dist/lead-zhxqbfdv.js +0 -69
  485. package/dist/worker-7j2907g6.js +0 -69
  486. package/src/tests/entrypoint-acp-target-binary.test.ts +0 -439
  487. package/dist/{cli-4caa1x7d.js → cli-tsa40663.js} +4 -4
  488. package/dist/{index-0rvk3vd4.js → index-bs7gw5fd.js} +3 -3
  489. package/dist/{mistral-conversations-a45tx39a.js → mistral-conversations-0c30em7t.js} +4 -4
  490. package/dist/{openai-completions-xd579js7.js → openai-completions-f3n69rep.js} +18 -18
  491. package/dist/{pi-messages-hjbv8v10.js → pi-messages-zebyt7gb.js} +5 -5
@@ -0,0 +1,136 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "$schema": {
6
+ "type": "string"
7
+ },
8
+ "version": {
9
+ "description": "Manifest format version.",
10
+ "type": "number",
11
+ "const": 1
12
+ },
13
+ "workflows": {
14
+ "type": "array",
15
+ "items": {
16
+ "type": "object",
17
+ "properties": {
18
+ "id": {
19
+ "type": "string",
20
+ "minLength": 1,
21
+ "maxLength": 200,
22
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
23
+ },
24
+ "file": {
25
+ "type": "string",
26
+ "minLength": 1,
27
+ "description": "YAML or JSON workflow file."
28
+ }
29
+ },
30
+ "required": [
31
+ "id",
32
+ "file"
33
+ ],
34
+ "additionalProperties": false
35
+ }
36
+ },
37
+ "skills": {
38
+ "type": "array",
39
+ "items": {
40
+ "type": "object",
41
+ "properties": {
42
+ "id": {
43
+ "type": "string",
44
+ "minLength": 1,
45
+ "maxLength": 200,
46
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
47
+ },
48
+ "dir": {
49
+ "type": "string",
50
+ "minLength": 1,
51
+ "description": "Directory holding SKILL.md and optional files/**."
52
+ }
53
+ },
54
+ "required": [
55
+ "id",
56
+ "dir"
57
+ ],
58
+ "additionalProperties": false
59
+ }
60
+ },
61
+ "scripts": {
62
+ "type": "array",
63
+ "items": {
64
+ "type": "object",
65
+ "properties": {
66
+ "name": {
67
+ "type": "string",
68
+ "minLength": 1,
69
+ "maxLength": 200,
70
+ "description": "Global script name."
71
+ },
72
+ "file": {
73
+ "type": "string",
74
+ "minLength": 1,
75
+ "description": "Script source file."
76
+ },
77
+ "description": {
78
+ "type": "string",
79
+ "minLength": 1
80
+ },
81
+ "intent": {
82
+ "description": "Defaults to `description`.",
83
+ "type": "string",
84
+ "minLength": 1
85
+ }
86
+ },
87
+ "required": [
88
+ "name",
89
+ "file",
90
+ "description"
91
+ ],
92
+ "additionalProperties": false
93
+ }
94
+ },
95
+ "agents": {
96
+ "type": "array",
97
+ "items": {
98
+ "type": "object",
99
+ "properties": {
100
+ "name": {
101
+ "description": "Agent name. Use `id` when names repeat.",
102
+ "type": "string",
103
+ "minLength": 1,
104
+ "maxLength": 200
105
+ },
106
+ "id": {
107
+ "description": "Agent id, as the agent registers.",
108
+ "type": "string",
109
+ "minLength": 1,
110
+ "maxLength": 200
111
+ },
112
+ "instructions": {
113
+ "description": "Markdown role instructions. Written to the agent's IDENTITY.md profile field.",
114
+ "type": "string",
115
+ "minLength": 1
116
+ },
117
+ "skills": {
118
+ "description": "Ids of skills declared in this manifest to install on the agent.",
119
+ "type": "array",
120
+ "items": {
121
+ "type": "string",
122
+ "minLength": 1,
123
+ "maxLength": 200,
124
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
125
+ }
126
+ }
127
+ },
128
+ "additionalProperties": false
129
+ }
130
+ }
131
+ },
132
+ "additionalProperties": false,
133
+ "$id": "https://github.com/desplega-ai/agent-swarm/blob/main/templates/import/manifest.schema.json",
134
+ "title": "Agent Swarm import manifest",
135
+ "description": "Optional swarm-import.{yaml,yml,json} at a package root. Item ids are source-local. Without it the directory convention applies: workflows/*.{yaml,yml,json}, skills/<id>/SKILL.md, scripts/*.ts, agents/<name>.md."
136
+ }
@@ -0,0 +1,44 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "array",
4
+ "items": {
5
+ "type": "object",
6
+ "properties": {
7
+ "id": {
8
+ "type": "string",
9
+ "minLength": 1,
10
+ "maxLength": 64,
11
+ "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
12
+ "description": "Stable source id. Owns every resource this source imports."
13
+ },
14
+ "type": {
15
+ "type": "string",
16
+ "const": "dir",
17
+ "description": "v1 ships the `dir` source only."
18
+ },
19
+ "path": {
20
+ "type": "string",
21
+ "minLength": 1,
22
+ "description": "Absolute path of the package root. Read only; mount it read-only."
23
+ },
24
+ "onConflict": {
25
+ "default": "noop",
26
+ "description": "`noop` keeps UI/API edits and skips resources this source does not own. `overwrite` makes the files win and adopts same-named resources.",
27
+ "type": "string",
28
+ "enum": [
29
+ "noop",
30
+ "overwrite"
31
+ ]
32
+ }
33
+ },
34
+ "required": [
35
+ "id",
36
+ "type",
37
+ "path"
38
+ ],
39
+ "additionalProperties": false
40
+ },
41
+ "$id": "https://github.com/desplega-ai/agent-swarm/blob/main/templates/import/sources.schema.json",
42
+ "title": "Agent Swarm import sources",
43
+ "description": "Value of SWARM_IMPORT_SOURCES (JSON) or the file SWARM_IMPORT_SOURCES_FILE names."
44
+ }
@@ -70,7 +70,7 @@ Add `--contact-sheet` to the start command for a timestamped PNG summary of visu
70
70
 
71
71
  ## Step 3: share the screenshot through agent-fs
72
72
 
73
- Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>`. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
73
+ Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the file link from the Outputs section of your system prompt (the dashboard when configured). `--file` is binary-safe. `--content` is text-only and mangles PNGs.
74
74
 
75
75
  ```bash
76
76
  agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
@@ -65,7 +65,7 @@ Add `--contact-sheet` to the start command for a timestamped PNG summary of visu
65
65
 
66
66
  ## Step 3: share the screenshot through agent-fs
67
67
 
68
- Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the live app link `${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>`. `--file` is binary-safe. `--content` is text-only and mangles PNGs.
68
+ Screenshots on the worker disk disappear with the task. Upload them to agent-fs under the qa path convention: that copy is the durable original. A person opens it through the file link from the Outputs section of your system prompt (the dashboard when configured). `--file` is binary-safe. `--content` is text-only and mangles PNGs.
69
69
 
70
70
  ```bash
71
71
  agent-fs write thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png \
@@ -531,9 +531,9 @@ The sidebar lists pages in definition order and marks the current one. Below 768
531
531
 
532
532
  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.
533
533
 
534
- 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.
534
+ 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.
535
535
 
536
- ## Component catalog (all 35)
536
+ ## Component catalog (all 45)
537
537
 
538
538
  Props reject unknown keys. A `{"$state":"..."}` binding may replace a literal prop value at any depth.
539
539
 
@@ -546,8 +546,9 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
546
546
  | `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. |
547
547
  | `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. |
548
548
  | `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. |
549
- | `Divider` | none | `label`; no children. |
549
+ | `Divider` | none | `label`, `orientation: "horizontal"` (default) or `"vertical"` (a rule between the items of a row `Stack`, as tall as the row); no children. |
550
550
  | `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. |
551
+ | `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. |
551
552
  | `Container` | none | Legacy layout primitive; prefer Stack. `direction: "row", "column"`, `gap: "none", "sm", "md", "lg"`; has the `default` child slot. |
552
553
  | `Card` | none | `title`, `description`; has the `default` child slot. |
553
554
  | `Heading` | `text` | `level: "h1", "h2", or "h3"`. |
@@ -558,8 +559,8 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
558
559
  | `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. |
559
560
  | `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. |
560
561
  | `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`. |
561
- | `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. |
562
- | `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. |
562
+ | `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. |
563
+ | `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. |
563
564
  | `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`). |
564
565
  | `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). |
565
566
  | `Icon` | `name` | `size: "sm", "md", or "lg"`, `tone: "default", "muted", "success", "warning", "error", or "info"`, `label` (accessible name; decorative without it). |
@@ -573,18 +574,25 @@ Tones: Badge, Metric and Progress `tone` take `neutral`, `success`, `active`, `e
573
574
  | `Section` | `title` | `description`, `collapsible`, `defaultOpen` (default true); has the `default` child slot. |
574
575
  | `Table` | `columns` | `data`, `loading`, `refreshing`, `error`, `emptyMessage`, `emptyState`, `rowActions`, `id`, `selectable`, `bulkActions`, `filterable`, `clearState`, `onRetry`, `onRowClick`, `selectedId`, `rowId`, `mobile`, `mobileFields`, `search`, `filters`; see below. |
575
576
  | `Form` | `id`, `fields`, `onSubmit` | `title`, `submitLabel`; see below. |
576
- | `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. |
577
+ | `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. |
578
+ | `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. |
577
579
  | `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. |
578
580
  | `CardGrid` | `titleKey` | `data`, `loading`, `error`, `emptyMessage`, `imageKey`, `fields`, `columns`, `onClick`; one card per row for record browsers; see below. |
579
581
  | `Kanban` | `columnField`, `columns`, `titleField` | `data`, `loading`, `cardFields`, `idField` (default `id`), `onMove`, `onCardClick`; see below. |
580
582
  | `Calendar` | `startField`, `titleField` | `data`, `loading`, `endField`, `idField`, `onSelect`; read-only month grid; see below. |
581
583
  | `ContributionGraph` | none | `data`, `loading`, `dateField` (default `date`), `countField`, `days` (7-730, default 365); read-only activity heatmap. |
582
584
  | `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. |
585
+ | `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. |
586
+ | `File` | `path` | `height`, `fill`; one agent-fs file (Markdown, image, PDF, text) read as the viewer; see below. |
587
+ | `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. |
588
+ | `Timeline` | `timeField`, `titleField` | `data`, `loading`, `descriptionField`, `statusField`, `tones`, `icon`, `emptyMessage`, `onSelect`; vertical event list, newest first, grouped by day; see below. |
583
589
  | `SchemaForm` | `id`, `schema` | `value`, `baseDoc`, `nodeKey`, `onChange`, `fill`; form generated from a JSON schema's `properties`, mirrored to `/ui/<id>/value`; see below. |
590
+ | `Approval` | `requestId` | `showResolved` (default true), `compact`, `onResolved`; one approval request answered in place by the viewer; see below. |
591
+ | `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. |
584
592
 
585
593
  Table details:
586
594
 
587
- - `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.
595
+ - `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.
588
596
  - `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`.
589
597
  - `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.
590
598
  - `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.
@@ -631,15 +639,97 @@ Tree details:
631
639
  - 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.
632
640
  - 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`).
633
641
 
642
+ Files and File details:
643
+
644
+ - 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.
645
+ - 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.
646
+ - `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`).
647
+ - `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" }`.
648
+ - `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".
649
+ - 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`.
650
+ - `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.
651
+ - 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.
652
+
653
+ DateRange and Timeline details:
654
+
655
+ - `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`.
656
+ - `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.
657
+
634
658
  SchemaForm details:
635
659
 
636
660
  - `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.
637
661
  - 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.
638
662
  - 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`.
639
663
 
664
+ Approval details (human-in-the-loop):
665
+
666
+ - `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.
667
+ - 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.
668
+ - 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".
669
+ - `showResolved: false` shows only the outcome line after resolution, not the answers. `compact: true` drops the card chrome.
670
+ - `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.
671
+
672
+ 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:
673
+
674
+ ```ts
675
+ export default async function run(args, ctx) {
676
+ const res: any = await ctx.swarm.request_humanInput({
677
+ title: `Deploy ${args.service}?`,
678
+ questions: [{ id: "go", type: "approval", label: "Ship it to production?" }],
679
+ detached: true,
680
+ });
681
+ return { requestId: res?.data?.requestId ?? res?.requestId };
682
+ }
683
+ ```
684
+
685
+ ```json
686
+ {
687
+ "askBtn": { "type": "Button", "props": { "label": "Request deploy", "busyWith": "requestDeploy" },
688
+ "on": { "press": { "action": "app.action", "params": { "name": "requestDeploy", "input": { "service": "api" } } } } },
689
+ "approve": {
690
+ "type": "Approval",
691
+ "props": {
692
+ "requestId": { "$state": "/actions/requestDeploy/result/requestId" },
693
+ "onResolved": [
694
+ { "action": "app.action", "params": { "name": "applyDecision",
695
+ "input": { "status": { "$chain": "status" }, "responses": { "$chain": "responses" } } } },
696
+ { "action": "ui.toast", "params": { "message": "Decision applied", "tone": "success" } }
697
+ ]
698
+ }
699
+ }
700
+ }
701
+ ```
702
+
703
+ 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.
704
+
705
+ SessionThread details — a chat on an app page, one session per viewer and `sessionKey`:
706
+
707
+ - `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.
708
+ - `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.
709
+ - 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.
710
+ - Sending a message takes one of three routes:
711
+ 1. No session yet → run `onDispatch` with `$form = { message }` and `$chain = { leafTaskId: null, newTaskId: null }`. Its `app.action` creates the session's root task.
712
+ 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.
713
+ 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.
714
+ - 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.
715
+ - "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.
716
+ - 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.
717
+ - 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.
718
+
719
+ ```json
720
+ { "type": "SessionThread", "props": {
721
+ "id": "chat",
722
+ "sessionKey": { "$state": "/route/params/screenId" },
723
+ "onDispatch": [{ "action": "app.action", "params": {
724
+ "name": "editScreen", "input": { "$form": "" }, "parentTaskId": { "$chain": "leafTaskId" } } }]
725
+ } }
726
+ ```
727
+
640
728
  Form details:
641
729
 
642
- - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, or `enum`, and enum fields need `options`.
730
+ - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, `enum`, or `file`, and enum fields need `options`.
731
+ - `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`.
732
+ - 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.
643
733
  - Values live at `/forms/<formId>/<fieldName>`. `onSubmit` is an action chain.
644
734
  - 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.
645
735
 
@@ -647,10 +737,28 @@ Drawer details:
647
737
 
648
738
  - `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.
649
739
  - `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.
740
+ - `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.
741
+
742
+ List + detail recipe (a row click opens the record beside the table):
743
+
744
+ ```json
745
+ "params": { "issue": { "kind": "string" } },
746
+ "elements": {
747
+ "root": { "type": "Stack", "props": {}, "children": ["table", "issue"] },
748
+ "table": { "type": "Table", "props": {
749
+ "data": { "$state": "/queries/issues/data" },
750
+ "columns": [{ "key": "title" }, { "key": "status", "kind": "status" }],
751
+ "selectedId": { "$state": "/route/params/issue" },
752
+ "onRowClick": [{ "action": "app.navigate", "params": { "page": "main", "params": { "issue": { "$row": "id" } } } }] } },
753
+ "issue": { "type": "Drawer", "props": { "param": "issue", "presentation": "split", "size": "md", "title": "Issue" },
754
+ "children": ["issueDetail"] },
755
+ "issueDetail": { "type": "DetailList", "props": { "data": { "$state": "/queries/issue/data/0" }, "fields": [{ "key": "title" }] } }
756
+ }
757
+ ```
650
758
 
651
759
  DetailList details:
652
760
 
653
- - `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`.
761
+ - `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`.
654
762
 
655
763
  Motion details:
656
764
 
@@ -736,7 +844,7 @@ Valid `$state` roots are:
736
844
 
737
845
  `/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.
738
846
 
739
- 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:
847
+ 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:
740
848
 
741
849
  | Sentinel | Resolves to |
742
850
  |---|---|
@@ -746,7 +854,7 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `
746
854
  | `{ "$form": "title" }` | One current Form value. |
747
855
  | `{ "$form": "" }` | All current Form values. |
748
856
  | `{ "$state": "/queries/allIdeas/data" }` | Current value at a valid app state path, including action state such as `/actions/refreshIssues/status`. |
749
- | `{ "$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. |
857
+ | `{ "$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`. |
750
858
  | `{ "$chain": "" }` | The whole chain scope. |
751
859
 
752
860
  Each sentinel object must contain exactly the single key shown.
@@ -755,12 +863,14 @@ An action-chain step is `{ "action": "<type>", "params": {...} }`. Available act
755
863
 
756
864
  - `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.
757
865
  - `app.refresh`: `{ query? }`; omit `query` to refetch all, or name a declared query.
758
- - `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.
866
+ - `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.
759
867
  - `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.
760
868
  - `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.
761
869
  - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.
762
870
  - `swarm.call`: `{ method, endpoint: "/api/...", body? }`, where `method` is `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, or `"PATCH"`; raw authenticated API call.
763
871
 
872
+ 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.
873
+
764
874
  ## Patch semantics
765
875
 
766
876
  `app-patch.definition` is RFC 7396 JSON Merge Patch applied to the stored definition: