@desplega.ai/agent-swarm 2.8.3 → 2.9.1

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 (597) hide show
  1. package/dist/acp-adapter-g909b5hw.js +16 -0
  2. package/dist/acp-targets-ny75x1qy.js +23 -0
  3. package/dist/{actions-ewz7bp4g.js → actions-b9qgrmeq.js} +82 -21
  4. package/dist/agent-fs-provision-b5dhdsbd.js +27 -0
  5. package/dist/{amp-adapter-f25tqhnf.js → amp-adapter-vtax2c9s.js} +3 -3
  6. package/dist/{anthropic-messages-jkva0zps.js → anthropic-messages-r5xf5hqw.js} +37 -37
  7. package/dist/{app-mkptw0k7.js → app-g2z15hax.js} +9 -4
  8. package/dist/approval-notifications-yt13wp8r.js +23 -0
  9. package/dist/{assistant-c47rfe77.js → assistant-2cgfxsgk.js} +56 -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-3gwy0f60.js} +1 -1
  12. package/dist/{boot-reembed-htr73hbs.js → boot-reembed-92g7s5zp.js} +1 -1
  13. package/dist/{boot-reembed-1ghy2sab.js → boot-reembed-mywmyp4s.js} +1 -1
  14. package/dist/{boot-scrub-sweep-yrytg42z.js → boot-scrub-sweep-7dkdzqxx.js} +84 -13
  15. package/dist/{boot-seeds-n2b3dx4e.js → boot-seeds-ce7rvgq1.js} +4 -4
  16. package/dist/{boxd-jmfqgkqa.js → boxd-wn235q80.js} +7 -7
  17. package/dist/claude-adapter-3m4q7735.js +28 -0
  18. package/dist/{claude-managed-adapter-hddmxjyj.js → claude-managed-adapter-t8nfgcgz.js} +4 -4
  19. package/dist/{claude-managed-setup-hfvry1bd.js → claude-managed-setup-c217draw.js} +10 -10
  20. package/dist/{claude-sdk-session-0hamqzc7.js → claude-sdk-session-7fbqm51z.js} +9386 -9196
  21. package/dist/{cli-yjdgea32.js → cli-1jx0srjt.js} +17 -17
  22. package/dist/{cli-sdvcrq5x.js → cli-1jykg0py.js} +18 -14
  23. package/dist/{cli-k96cecs7.js → cli-2czxfnvj.js} +1221 -357
  24. package/dist/{cli-qmqt520k.js → cli-2dq9yv8p.js} +2 -2
  25. package/dist/{cli-e2w34h6z.js → cli-2xs8tsf7.js} +132 -85
  26. package/dist/{cli-z8cvws4c.js → cli-2yjj3e31.js} +907 -56
  27. package/dist/{cli-mdpbjnzq.js → cli-32djehja.js} +42 -42
  28. package/dist/{cli-gpz1d0t2.js → cli-3j873zxq.js} +4 -4
  29. package/dist/cli-43ms35q9.js +270 -0
  30. package/dist/cli-47hz21se.js +25584 -0
  31. package/dist/{cli-n515ex5z.js → cli-4ymxrwg5.js} +16 -16
  32. package/dist/{cli-f1kwb5fc.js → cli-5a6pqy45.js} +333 -21
  33. package/dist/{cli-93t5s4zq.js → cli-5gpqgs8b.js} +2 -2
  34. package/dist/{cli-15204js0.js → cli-6237rnyr.js} +1 -1
  35. package/dist/{cli-4ax9mvvg.js → cli-67mwzr35.js} +9 -9
  36. package/dist/{cli-t5ys4ebm.js → cli-6945ywhr.js} +3 -3
  37. package/dist/{cli-0bcgyj5b.js → cli-6ehs4mta.js} +87 -8
  38. package/dist/{cli-6yygkr0w.js → cli-6ym4jhzp.js} +15 -7
  39. package/dist/{cli-8bpgbr8k.js → cli-7evph51z.js} +5 -5
  40. package/dist/{cli-dtdht77h.js → cli-7mv4h3sn.js} +2 -2
  41. package/dist/{cli-nx2n3z6p.js → cli-7sf9sb0w.js} +3 -2
  42. package/dist/{cli-pe4d96rb.js → cli-7zm3b3f5.js} +1 -1
  43. package/dist/cli-8zh9nrew.js +78 -0
  44. package/dist/cli-9ttx00s3.js +137 -0
  45. package/dist/{cli-x6t50dmw.js → cli-9w8712tq.js} +620 -281
  46. package/dist/{cli-8476gtwf.js → cli-b6px1k1q.js} +1 -1
  47. package/dist/{cli-k2rw11py.js → cli-b91nz213.js} +5 -5
  48. package/dist/{cli-7c5tgqhf.js → cli-bg63qmsx.js} +10 -10
  49. package/dist/{cli-qps8je6j.js → cli-bkjdknnp.js} +54 -10
  50. package/dist/{cli-gn9y6fn7.js → cli-bnqncekd.js} +2 -2
  51. package/dist/{cli-s7zz734a.js → cli-br0924pw.js} +1 -1
  52. package/dist/{cli-h9yy18gy.js → cli-ctx0b85j.js} +5484 -5078
  53. package/dist/{cli-0vksaxvr.js → cli-dgs10ttj.js} +2 -2
  54. package/dist/cli-dqgnbnxs.js +132 -0
  55. package/dist/{cli-q6mfk1ej.js → cli-dzzh58sy.js} +2 -2
  56. package/dist/{cli-2znm3dzj.js → cli-eds5xnsz.js} +2 -2
  57. package/dist/{cli-c0xjnr8z.js → cli-f3jyzq4g.js} +2 -2
  58. package/dist/cli-f8x9drqr.js +84 -0
  59. package/dist/{cli-ztq5z4e1.js → cli-f9gz2vyj.js} +6 -6
  60. package/dist/{cli-bhsfbmk8.js → cli-fh97xn30.js} +93 -44
  61. package/dist/cli-fkef327x.js +103 -0
  62. package/dist/{cli-fsgttth8.js → cli-g0vv9dg4.js} +13 -13
  63. package/dist/{cli-kd56bmk4.js → cli-gabsjg8x.js} +3 -1
  64. package/dist/{cli-1m96dc36.js → cli-gfy38pvt.js} +3 -3
  65. package/dist/{cli-922z7gwm.js → cli-h9yqfzx9.js} +15 -11
  66. package/dist/{cli-5a7szzfh.js → cli-hnamkvnc.js} +2 -2
  67. package/dist/{cli-c3ng0mb4.js → cli-j7svy295.js} +71 -818
  68. package/dist/{cli-yss07azk.js → cli-jaw5v1sy.js} +3 -3
  69. package/dist/cli-jkw6ptfw.js +921 -0
  70. package/dist/{cli-s8p8hhty.js → cli-jm0hvmz2.js} +2 -2
  71. package/dist/{cli-knva3nmx.js → cli-jwampxxq.js} +8 -6
  72. package/dist/cli-kj0hyr43.js +51 -0
  73. package/dist/{cli-tnzebztn.js → cli-kpgcm7xy.js} +13 -1
  74. package/dist/{cli-9zmb7ptc.js → cli-kxx4k2jw.js} +8 -753
  75. package/dist/{cli-am1ptset.js → cli-m7c2380k.js} +208 -194
  76. package/dist/{cli-kw44j53p.js → cli-m7zvgt57.js} +45 -38
  77. package/dist/{cli-504akrp9.js → cli-meydjstb.js} +3 -3
  78. package/dist/{cli-54qr8mcd.js → cli-mhapr559.js} +4 -4
  79. package/dist/{cli-tf79ryyy.js → cli-mjw0yf82.js} +3 -3
  80. package/dist/{cli-rjvsf9qa.js → cli-mkwkwq81.js} +14 -11
  81. package/dist/{cli-n30e0hcp.js → cli-mna6pmfx.js} +2 -2
  82. package/dist/{cli-awwptga4.js → cli-mw620q3n.js} +1 -1
  83. package/dist/{cli-6wj7p986.js → cli-n3qe7tyr.js} +172 -168
  84. package/dist/{cli-4dpkjc2e.js → cli-nafvvsp8.js} +9 -9
  85. package/dist/{cli-sg27rk2t.js → cli-nbt14he0.js} +25 -19
  86. package/dist/{cli-7akn6ze9.js → cli-nh7x3133.js} +7 -28
  87. package/dist/{cli-zdaypkq9.js → cli-p4kckx1z.js} +285 -97
  88. package/dist/{cli-n5t077me.js → cli-pb2ay3sh.js} +10 -3
  89. package/dist/{cli-t4dv07kr.js → cli-psffsanb.js} +4 -3
  90. package/dist/{cli-mwwmka77.js → cli-pyjn0qhk.js} +2712 -268
  91. package/dist/{cli-emekyyhr.js → cli-q2d3e1k1.js} +1 -1
  92. package/dist/{cli-vqva1teb.js → cli-qe909n63.js} +2 -2
  93. package/dist/{cli-2d0cghfn.js → cli-qj39vrc6.js} +1 -1
  94. package/dist/{cli-tas6ckky.js → cli-rq5rpv6k.js} +2 -2
  95. package/dist/{cli-0agcv1v5.js → cli-rqx70rcz.js} +2 -2
  96. package/dist/{cli-kmemts3w.js → cli-sn650d7x.js} +39 -69
  97. package/dist/{cli-98rwmcyc.js → cli-snxhtehz.js} +3 -3
  98. package/dist/{cli-d829z3xc.js → cli-spfz393q.js} +6 -6
  99. package/dist/{cli-500c09j9.js → cli-t9ga4qmb.js} +14 -14
  100. package/dist/{cli-me0r8gzr.js → cli-td9tb872.js} +27 -25
  101. package/dist/cli-tvc4jag9.js +754 -0
  102. package/dist/{cli-6ek0hff4.js → cli-ty3gha1p.js} +4 -4
  103. package/dist/{cli-c71n3bxq.js → cli-v57d7fmm.js} +2 -2
  104. package/dist/{cli-j8cjdzan.js → cli-vs9vdpy0.js} +1 -1
  105. package/dist/cli-vt89089n.js +296 -0
  106. package/dist/{cli-pxwtcgcp.js → cli-vyff45ve.js} +2 -2
  107. package/dist/{cli-x3ex5bqf.js → cli-w16kwbzw.js} +1 -1
  108. package/dist/{cli-bj6qhgte.js → cli-w4n323t3.js} +197 -45
  109. package/dist/{cli-rqfvkx5t.js → cli-wn13hhdt.js} +13 -13
  110. package/dist/{cli-skmhsnqh.js → cli-x40a0w9j.js} +1 -1
  111. package/dist/{cli-zeaehgyd.js → cli-xag7btpe.js} +2 -2
  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-dpsfwh7n.js → cli-y2ewxhth.js} +56 -31
  115. package/dist/{cli-vx421edw.js → cli-ysvspf5e.js} +9 -7
  116. package/dist/{cli-crpf163n.js → cli-zh0e5x7p.js} +16 -26
  117. package/dist/{cli-4e1hfbpq.js → cli-zr6qy15y.js} +24 -24
  118. package/dist/cli.js +33 -29
  119. package/dist/{codex-adapter-2brxx5ta.js → codex-adapter-n656pvb8.js} +9 -8
  120. package/dist/{codex-hook-c930c3ea.js → codex-hook-59atdwd8.js} +6 -6
  121. package/dist/{codex-login-cbrs1h5w.js → codex-login-a239g1ah.js} +1 -1
  122. package/dist/{codex-session-runner-y9anfj0r.js → codex-session-runner-p0fbv5y9.js} +10 -9
  123. package/dist/{commands-wn9q06qr.js → commands-gwea8z5p.js} +3 -3
  124. package/dist/{controller-fw608czd.js → controller-t67c3grh.js} +9 -6
  125. package/dist/{controllers-connect-63j5rdcm.js → controllers-connect-ks155r0h.js} +28 -25
  126. package/dist/{cursor-adapter-6mb9jme8.js → cursor-adapter-ygwrtmkv.js} +2 -2
  127. package/dist/{db-y4wfrzbm.js → db-kpmx06s9.js} +21 -13
  128. package/dist/{db-0m6v5tq4.js → db-rb2xqdb1.js} +3 -3
  129. package/dist/{devin-adapter-r0yx3gv8.js → devin-adapter-zp4tqq53.js} +1 -1
  130. package/dist/{dispatcher-9tq2zzdj.js → dispatcher-31sm0ej2.js} +21 -18
  131. package/dist/{docker-j75atvpt.js → docker-09tkkg0n.js} +47 -8
  132. package/dist/{dsh-adapter-t09sv4tq.js → dsh-adapter-qyxh0w31.js} +2 -2
  133. package/dist/{e2b-a7vzs2vj.js → e2b-3v1e745x.js} +6 -6
  134. package/dist/{e2b-7s9dscap.js → e2b-sm28k0k3.js} +6 -6
  135. package/dist/{easter-egg-3d-fbwvmwhe.js → easter-egg-3d-00wjscn6.js} +1 -1
  136. package/dist/{embedding-space-wh8de1t9.js → embedding-space-qhw4g68n.js} +6 -6
  137. package/dist/{embeddings-3hpbdtjr.js → embeddings-zdv9ke6x.js} +1 -1
  138. package/dist/{event-bus-tr6h3gv8.js → event-bus-xr83x566.js} +1 -1
  139. package/dist/{execute-4bdf8sdy.js → execute-zna8wwr7.js} +1 -1
  140. package/dist/{external-channel-ts2fwqh0.js → external-channel-1ac6t56s.js} +2 -2
  141. package/dist/fx-adapter-sk7n0fzc.js +19 -0
  142. package/dist/{getMachineId-bsd-nfgrzarv.js → getMachineId-bsd-637a7rbk.js} +3 -3
  143. package/dist/{getMachineId-darwin-wz886dsk.js → getMachineId-darwin-9vytrcnn.js} +3 -3
  144. package/dist/{getMachineId-linux-1nng3p1p.js → getMachineId-linux-mkzsvyyz.js} +3 -3
  145. package/dist/{getMachineId-unsupported-a0428vw9.js → getMachineId-unsupported-4cfs2n11.js} +3 -3
  146. package/dist/{getMachineId-win-h45922nq.js → getMachineId-win-154s3qma.js} +3 -3
  147. package/dist/{google-generative-ai-h7s3e9kk.js → google-generative-ai-maq6c9bf.js} +1 -1
  148. package/dist/{google-vertex-fhxaafzw.js → google-vertex-2jgsw2nb.js} +5 -5
  149. package/dist/grok-adapter-sjbcm5ew.js +19 -0
  150. package/dist/handlers-yzy0c87x.js +35 -0
  151. package/dist/{heartbeat-2ze5fzpc.js → heartbeat-2f6z4kdx.js} +24 -21
  152. package/dist/{hook-gaehe2w5.js → hook-8y0gvtp1.js} +14 -14
  153. package/dist/{hook-ca54yd4s.js → hook-w1skzaqc.js} +5 -5
  154. package/dist/{http-jfg8t2yk.js → http-wghxvpef.js} +2333 -589
  155. package/dist/{index-d6wkh8ar.js → index-0h6qd4p1.js} +34 -24
  156. package/dist/index-25pvya7q.js +40 -0
  157. package/dist/index-2t4859r5.js +35 -0
  158. package/dist/{index-enn321kd.js → index-42jq9yy3.js} +3 -3
  159. package/dist/{index-khe3gp0k.js → index-4k7m5dgj.js} +645 -370
  160. package/dist/index-620y7jzq.js +15 -0
  161. package/dist/{index-gjwaqaq8.js → index-8p0j4h4j.js} +506 -43
  162. package/dist/{index-3gv6sc4z.js → index-8zn8nxn5.js} +1 -1
  163. package/dist/{index-m5gx1xd6.js → index-9myfj74s.js} +40 -40
  164. package/dist/{index-3yvzbhxd.js → index-9zkchs9t.js} +336 -193
  165. package/dist/{index-0rvk3vd4.js → index-b5wgnm78.js} +47 -47
  166. package/dist/index-cxca2t8y.js +36 -0
  167. package/dist/{index-qwj6ntem.js → index-e3krvkh2.js} +4 -4
  168. package/dist/{index-hjhfk3ra.js → index-pe3d8jfy.js} +3 -3
  169. package/dist/index-rv89fvzf.js +572 -0
  170. package/dist/{index-csgrxedz.js → index-s71ez27v.js} +1 -1
  171. package/dist/{keepalive-k2a3qe73.js → keepalive-sh02349h.js} +4 -4
  172. package/dist/lead-gk4h5eg7.js +74 -0
  173. package/dist/{maintenance-gb5sd5nc.js → maintenance-yj0dcjja.js} +1 -1
  174. package/dist/{node-252anz2h.js → node-dqm4xgxw.js} +4 -4
  175. package/dist/{node-ray25snp.js → node-zd6shky9.js} +3 -3
  176. package/dist/{oauth-refresh-sweep-y7rm6bkb.js → oauth-refresh-sweep-d9xedk66.js} +3 -3
  177. package/dist/{onboard-jmc5qerv.js → onboard-dpgjn03r.js} +8 -8
  178. package/dist/{openai-codex-responses-k9gapdze.js → openai-codex-responses-bkcd8pjj.js} +9 -9
  179. package/dist/{openai-responses-4d5dx3c7.js → openai-responses-gbh0wfqe.js} +13 -13
  180. package/dist/{opencode-adapter-7eade9ev.js → opencode-adapter-2d31cpjc.js} +7 -6
  181. package/dist/{otel-impl-8j1xhxqd.js → otel-impl-1skarpfq.js} +110 -110
  182. package/dist/pending-bfmxtx0g.js +82 -0
  183. package/dist/{pi-mono-adapter-yqmaf32x.js → pi-mono-adapter-gvppnasy.js} +43 -16
  184. package/dist/{pricing-refresh-1nj722h6.js → pricing-refresh-c6b325mk.js} +2 -2
  185. package/dist/{rbac-roles-b1mtr6dr.js → rbac-roles-h80qbdbs.js} +3 -3
  186. package/dist/{rbac-roles-n1f3frk1.js → rbac-roles-zfcx68tx.js} +10 -3
  187. package/dist/{render-v2-1gfpd8rj.js → render-v2-nx20t3rb.js} +7 -4
  188. package/dist/{resume-w1s1eh5v.js → resume-5ep8agan.js} +11 -7
  189. package/dist/{runtime-84g5egsc.js → runtime-r3pj4mce.js} +1 -1
  190. package/dist/{session-access-y6z1txk4.js → session-access-n7p3m15b.js} +4 -4
  191. package/dist/{session-source-backfill-gxxwfh12.js → session-source-backfill-v8mt0zwn.js} +4 -4
  192. package/dist/{setup-r91gstyk.js → setup-z1psaqhe.js} +1 -1
  193. package/dist/thread-buffer-a1re2r9r.js +38 -0
  194. package/dist/{virtual-modules-cgnj6kme.js → virtual-modules-rrbjdpxn.js} +5 -5
  195. package/dist/{work-objects-qcxzg61c.js → work-objects-4aghh73z.js} +31 -23
  196. package/dist/worker-3dyyb8ev.js +74 -0
  197. package/dist/{worker-follow-up-y2d2h7km.js → worker-follow-up-166zmex1.js} +21 -18
  198. package/dist/{x-qhxq2ama.js → x-wg164ss9.js} +2 -2
  199. package/openapi.json +2561 -131
  200. package/package.json +15 -11
  201. package/plugin/commands/create-pr.md +1 -1
  202. package/plugin/pi-skills/create-pr/SKILL.md +1 -1
  203. package/src/apps/action-runner.ts +21 -1
  204. package/src/apps/catalog.generated.json +667 -18
  205. package/src/apps/page-validator.ts +341 -8
  206. package/src/assets/key.ts +6 -0
  207. package/src/be/agent-fs-user-keys.ts +186 -0
  208. package/src/be/audit-user.ts +27 -13
  209. package/src/be/automation-preflight.test.ts +14 -14
  210. package/src/be/automation-preflight.ts +24 -16
  211. package/src/be/boot-scrub-sweep.ts +143 -14
  212. package/src/be/caller-session-group.ts +86 -0
  213. package/src/be/checklist.ts +375 -0
  214. package/src/be/db/agents.ts +12 -1
  215. package/src/be/db/approvals.ts +26 -0
  216. package/src/be/db/model-profiles.ts +4 -1
  217. package/src/be/db/session-costs.ts +219 -0
  218. package/src/be/db/session-log-reasoning.ts +36 -0
  219. package/src/be/db/session-moves.ts +23 -0
  220. package/src/be/db/session-tree.ts +78 -19
  221. package/src/be/db/tasks/eligibility-scan.ts +14 -0
  222. package/src/be/db/tasks/read.ts +7 -3
  223. package/src/be/db/tasks/slack-fold.ts +116 -0
  224. package/src/be/db/tasks/write.ts +67 -1
  225. package/src/be/db-queries/mcp-servers.ts +13 -0
  226. package/src/be/db-queries/oauth.ts +6 -0
  227. package/src/be/db-queries/task-artifacts.ts +10 -8
  228. package/src/be/db.ts +242 -319
  229. package/src/be/extensions/assets.ts +17 -13
  230. package/src/be/import/config.ts +54 -0
  231. package/src/be/import/dir-source.ts +372 -0
  232. package/src/be/import/index.ts +149 -0
  233. package/src/be/import/pending.ts +71 -0
  234. package/src/be/import/schema.ts +137 -0
  235. package/src/be/import/seeders.ts +462 -0
  236. package/src/be/key-window-usage.ts +385 -0
  237. package/src/be/migrations/297_import_ownership.sql +34 -0
  238. package/src/be/migrations/301_favorites_key_type.sql +36 -0
  239. package/src/be/migrations/302_checklist_items.sql +23 -0
  240. package/src/be/migrations/303_task_ui_specs.sql +28 -0
  241. package/src/be/migrations/306_provider_account_telemetry.sql +1 -0
  242. package/src/be/migrations/307_session_cost_credential_attribution.sql +23 -0
  243. package/src/be/migrations/310_session_logs_reasoning.sql +12 -0
  244. package/src/be/multi-runtime.ts +8 -1
  245. package/src/be/rbac-roles.ts +8 -1
  246. package/src/be/runtime-pools/db.ts +3 -0
  247. package/src/be/runtime-pools/demand.ts +20 -2
  248. package/src/be/runtime-pools/reachability.ts +31 -0
  249. package/src/be/runtime-pools/routing.ts +8 -1
  250. package/src/be/runtime-pools/supervisor.ts +6 -7
  251. package/src/be/savings/read.ts +8 -6
  252. package/src/be/script-credential-broker.ts +2 -2
  253. package/src/be/scripts/typecheck.ts +4 -4
  254. package/src/be/seed/agent-fs-provision.ts +104 -19
  255. package/src/be/seed/index.ts +1 -1
  256. package/src/be/seed/registry.ts +27 -8
  257. package/src/be/seed/runner.ts +1 -1
  258. package/src/be/seed/schedules-seeder.ts +24 -6
  259. package/src/be/seed/seed-toggle.ts +32 -0
  260. package/src/be/seed/types.ts +6 -0
  261. package/src/be/seed-scripts/catalog/boot-triage.inline.ts +1 -0
  262. package/src/be/seed-scripts/catalog/boot-triage.ts +1 -0
  263. package/src/be/seed-scripts/catalog/dreaming-gather.ts +2 -2
  264. package/src/be/seed-scripts/catalog/wait-for-task.ts +5 -1
  265. package/src/be/seed-skills/index.ts +3 -0
  266. package/src/be/steering.ts +27 -4
  267. package/src/be/swarm-config-guard.ts +54 -1
  268. package/src/be/task-citations.ts +8 -5
  269. package/src/be/task-ui-spec.ts +158 -0
  270. package/src/commands/controller.ts +3 -0
  271. package/src/commands/credential-outcome-report.ts +13 -3
  272. package/src/commands/onboard/agent-fs-version.ts +1 -1
  273. package/src/commands/rate-limit-outcome.ts +6 -0
  274. package/src/commands/runner.ts +95 -55
  275. package/src/e2b/env.ts +2 -0
  276. package/src/extensions/catalog.generated.json +17 -0
  277. package/src/extensions/contract-types.generated.ts +1 -1
  278. package/src/github/app.ts +10 -1
  279. package/src/github/handlers.ts +6 -3
  280. package/src/github/reactions.ts +12 -14
  281. package/src/heartbeat/heartbeat.ts +14 -4
  282. package/src/http/agents.ts +19 -10
  283. package/src/http/all-routes.ts +2 -0
  284. package/src/http/api-keys.ts +258 -30
  285. package/src/http/approval-requests.ts +24 -4
  286. package/src/http/apps.ts +69 -5
  287. package/src/http/checklist.ts +176 -0
  288. package/src/http/db-query-bounded.ts +256 -11
  289. package/src/http/db-query-shared.ts +9 -0
  290. package/src/http/favorites.ts +14 -2
  291. package/src/http/fs.ts +346 -1
  292. package/src/http/index.ts +29 -1
  293. package/src/http/kv.ts +13 -0
  294. package/src/http/mcp-oauth.ts +1 -1
  295. package/src/http/mcp-servers.ts +15 -2
  296. package/src/http/onboarding.ts +2 -9
  297. package/src/http/poll.ts +45 -0
  298. package/src/http/script-connections.ts +1 -0
  299. package/src/http/session-data.ts +74 -23
  300. package/src/http/sessions.ts +23 -2
  301. package/src/http/slack-events.ts +101 -0
  302. package/src/http/status.ts +25 -7
  303. package/src/http/task-requester.ts +46 -0
  304. package/src/http/tasks.ts +169 -42
  305. package/src/http/users.ts +14 -0
  306. package/src/http/webhooks.ts +15 -0
  307. package/src/integrations/cards/index.ts +151 -0
  308. package/src/integrations/chat-sdk/outbound.ts +39 -13
  309. package/src/integrations/chat-sdk/relay.ts +87 -0
  310. package/src/integrations/chat-sdk/runtime.ts +7 -1
  311. package/src/integrations/chat-sdk/status.ts +17 -0
  312. package/src/integrations/chat-sdk/telegram-api.ts +6 -1
  313. package/src/jira/outbound.ts +5 -3
  314. package/src/kv-reserved-namespaces.ts +17 -2
  315. package/src/linear/outbound.ts +5 -1
  316. package/src/oauth/presets.ts +29 -2
  317. package/src/prompts/base-prompt.ts +25 -4
  318. package/src/prompts/session-templates.ts +102 -8
  319. package/src/providers/acp-targets.ts +1 -1
  320. package/src/providers/amp-adapter.ts +1 -1
  321. package/src/providers/claude-adapter.ts +27 -4
  322. package/src/providers/claude-flag-settings.ts +39 -1
  323. package/src/providers/claude-managed-adapter.ts +5 -1
  324. package/src/providers/codex-adapter.ts +86 -4
  325. package/src/providers/codex-app-server.ts +11 -16
  326. package/src/providers/codex-oauth/auth-json.ts +1 -0
  327. package/src/providers/opencode-adapter.ts +7 -19
  328. package/src/providers/pi-mono-adapter.ts +35 -2
  329. package/src/providers/pricing-sources.md +32 -0
  330. package/src/providers/runtime-dependencies.ts +158 -0
  331. package/src/providers/types.ts +11 -0
  332. package/src/rbac/legacy-policy.ts +2 -0
  333. package/src/rbac/permissions.ts +10 -1
  334. package/src/runtime-providers/docker.ts +65 -1
  335. package/src/scheduler/deferred-task-waits.ts +18 -5
  336. package/src/scripts-runtime/credential-broker/default-bindings.ts +19 -11
  337. package/src/scripts-runtime/credential-broker/index.ts +1 -1
  338. package/src/scripts-runtime/egress-secrets.ts +2 -2
  339. package/src/scripts-runtime/swarm-sdk.ts +3 -2
  340. package/src/scripts-runtime/types/stdlib.d.ts +11 -4
  341. package/src/scripts-runtime/types/swarm-extension.d.ts +9 -9
  342. package/src/scripts-runtime/types/swarm-sdk.d.ts +11 -4
  343. package/src/server.ts +4 -4
  344. package/src/slack/actions.ts +56 -0
  345. package/src/slack/app.ts +107 -59
  346. package/src/slack/assistant.ts +33 -7
  347. package/src/slack/handlers.ts +6 -4
  348. package/src/slack/http-receiver.ts +284 -0
  349. package/src/slack/inbound-dispatch.ts +43 -7
  350. package/src/slack/inbound-files.ts +35 -14
  351. package/src/slack/message-text.ts +47 -4
  352. package/src/slack/render-v2.ts +109 -24
  353. package/src/slack/responses.ts +3 -2
  354. package/src/slack/socket-ack.ts +17 -10
  355. package/src/slack/steering.ts +5 -0
  356. package/src/slack/thread-buffer-store.ts +58 -0
  357. package/src/slack/thread-buffer.ts +341 -57
  358. package/src/slack/work-objects.ts +4 -1
  359. package/src/tasks/context-key.ts +24 -0
  360. package/src/tasks/errors.ts +5 -0
  361. package/src/tasks/sibling-awareness.ts +13 -1
  362. package/src/tests/acp-adapter.test.ts +4 -6
  363. package/src/tests/agent-fs-live-url.test.ts +15 -0
  364. package/src/tests/agent-fs-provision-seeder.test.ts +140 -0
  365. package/src/tests/agent-fs-user-keys.test.ts +483 -0
  366. package/src/tests/agentfs-proxy.test.ts +8 -8
  367. package/src/tests/api-key-tracking.test.ts +0 -72
  368. package/src/tests/api-keys-status-model-limits.test.ts +93 -1
  369. package/src/tests/api-keys-validation.test.ts +42 -0
  370. package/src/tests/approval-card-resolution.test.ts +402 -0
  371. package/src/tests/approval-requests-notifications.test.ts +12 -2
  372. package/src/tests/approval-respond-auth.test.ts +28 -0
  373. package/src/tests/apps-action-parent-task.test.ts +140 -0
  374. package/src/tests/apps-catalog-additions.test.ts +315 -0
  375. package/src/tests/apps-catalog-files.test.ts +114 -0
  376. package/src/tests/apps-catalog-hitl.test.ts +117 -0
  377. package/src/tests/apps-catalog-inputs.test.ts +86 -0
  378. package/src/tests/apps-catalog-page-frame.test.ts +49 -0
  379. package/src/tests/apps-catalog-table.test.ts +47 -0
  380. package/src/tests/apps-chart-shell.test.ts +1 -1
  381. package/src/tests/apps-element-assembly.test.ts +52 -3
  382. package/src/tests/apps-session-thread.test.ts +261 -0
  383. package/src/tests/asset-key-invariants.test.ts +14 -0
  384. package/src/tests/base-prompt.test.ts +213 -23
  385. package/src/tests/boot-scrub-sweep.test.ts +172 -0
  386. package/src/tests/caller-session-group.test.ts +199 -0
  387. package/src/tests/cards.test.ts +169 -0
  388. package/src/tests/chat-sdk-relay.test.ts +149 -1
  389. package/src/tests/chat-sdk-status-route.test.ts +16 -3
  390. package/src/tests/chat-sdk-telegram-token.test.ts +76 -0
  391. package/src/tests/chat-sdk-tools.test.ts +147 -0
  392. package/src/tests/checklist-nudge.test.ts +208 -0
  393. package/src/tests/checklist.test.ts +686 -0
  394. package/src/tests/claude-adapter-binary.test.ts +67 -6
  395. package/src/tests/claude-flag-settings.test.ts +29 -0
  396. package/src/tests/claude-sdk-lifecycle.test.ts +5 -0
  397. package/src/tests/codex-adapter.test.ts +340 -2
  398. package/src/tests/codex-app-server.test.ts +32 -0
  399. package/src/tests/codex-oauth.test.ts +3 -1
  400. package/src/tests/codex-rate-limits.test.ts +384 -0
  401. package/src/tests/comb-config-guard.test.ts +21 -0
  402. package/src/tests/comb-default.test.ts +59 -97
  403. package/src/tests/comb-links.test.ts +86 -16
  404. package/src/tests/comb-status.test.ts +24 -27
  405. package/src/tests/create-page-tool.test.ts +101 -1
  406. package/src/tests/create-schedule-key.test.ts +105 -0
  407. package/src/tests/credential-broker.test.ts +2 -2
  408. package/src/tests/credential-outcome-report.test.ts +20 -0
  409. package/src/tests/db-query.test.ts +87 -1
  410. package/src/tests/db-task-read-contract.test.ts +4 -0
  411. package/src/tests/db-task-write-contract.test.ts +6 -1
  412. package/src/tests/deferred-task-wake.test.ts +63 -1
  413. package/src/tests/docker-isolation-config-guard.test.ts +29 -0
  414. package/src/tests/docs-index-footprint.test.js +11 -3
  415. package/src/tests/e2e-visuals-comment.test.ts +82 -0
  416. package/src/tests/e2e-visuals-verify-pr.test.ts +138 -0
  417. package/src/tests/entrypoint-github-enterprise.test.ts +158 -0
  418. package/src/tests/extensions-assets.test.ts +7 -3
  419. package/src/tests/extensions-catalog.test.ts +1 -0
  420. package/src/tests/extensions-example-sql-admin-only.test.ts +201 -0
  421. package/src/tests/extensions-pre-task.test.ts +3 -3
  422. package/src/tests/extensions-steering.test.ts +14 -2
  423. package/src/tests/favorites-agent-fs-path.test.ts +124 -0
  424. package/src/tests/fetch-resolved-env.test.ts +68 -0
  425. package/src/tests/fixtures/import-package.ts +32 -0
  426. package/src/tests/fixtures/runner-missing-dependency.ts +129 -0
  427. package/src/tests/fixtures/ui-spec-slack/deploys.json +121 -0
  428. package/src/tests/fixtures/ui-spec-slack/incident.json +183 -0
  429. package/src/tests/fixtures/ui-spec-slack/three-charts-stale.json +196 -0
  430. package/src/tests/fixtures/ui-spec-slack/video-rejected-by-slack.json +183 -0
  431. package/src/tests/fixtures/ui-spec-slack/video.json +446 -0
  432. package/src/tests/fs-routes.test.ts +505 -2
  433. package/src/tests/github-ghes-mock.test.ts +196 -0
  434. package/src/tests/github-host.test.ts +285 -0
  435. package/src/tests/gitleaks-download-retry.test.ts +85 -0
  436. package/src/tests/heartbeat-supersede-resume.test.ts +73 -0
  437. package/src/tests/heartbeat.test.ts +56 -0
  438. package/src/tests/human-thread-routing.test.ts +187 -0
  439. package/src/tests/import-config.test.ts +209 -0
  440. package/src/tests/import.test.ts +464 -0
  441. package/src/tests/invites-http.test.ts +144 -1
  442. package/src/tests/jira-outbound-sync.test.ts +33 -1
  443. package/src/tests/key-window-usage.test.ts +831 -0
  444. package/src/tests/kv-http.test.ts +11 -0
  445. package/src/tests/linear-outbound-sync.test.ts +30 -1
  446. package/src/tests/literal-matcher.test.ts +58 -0
  447. package/src/tests/mcp-oauth-manual-client.test.ts +1 -1
  448. package/src/tests/oauth-presets.test.ts +12 -0
  449. package/src/tests/pi-mono-adapter.test.ts +79 -0
  450. package/src/tests/pool-affinity.test.ts +50 -0
  451. package/src/tests/preload-env.test.ts +2 -0
  452. package/src/tests/preload.ts +3 -1
  453. package/src/tests/prompt-template-session.test.ts +53 -5
  454. package/src/tests/provider-quota-persistence.test.ts +362 -0
  455. package/src/tests/provider-registration.test.ts +2 -55
  456. package/src/tests/provider-runtime-dependencies.test.ts +212 -0
  457. package/src/tests/rate-limit-event.test.ts +22 -0
  458. package/src/tests/rbac-admission.test.ts +19 -0
  459. package/src/tests/rbac-charact-misc-tools.test.ts +31 -0
  460. package/src/tests/rbac-engine.test.ts +2 -0
  461. package/src/tests/rbac-roles.test.ts +2 -0
  462. package/src/tests/reasoning-events.test.ts +164 -0
  463. package/src/tests/routing-affinity-inventory.test.ts +22 -0
  464. package/src/tests/runner-missing-dependency.test.ts +61 -0
  465. package/src/tests/runtime-pool-reachability.test.ts +135 -1
  466. package/src/tests/runtime-pool-routing.test.ts +52 -0
  467. package/src/tests/runtime-providers-docker.test.ts +91 -0
  468. package/src/tests/runtime-stale-threshold.test.ts +40 -0
  469. package/src/tests/savings-fleet-slices.test.ts +122 -0
  470. package/src/tests/savings-read.test.ts +41 -0
  471. package/src/tests/savings-scripts.test.ts +9 -3
  472. package/src/tests/script-connections.test.ts +7 -0
  473. package/src/tests/script-executor-conformance.test.ts +41 -4
  474. package/src/tests/secret-canary-sweep.test.ts +41 -5
  475. package/src/tests/secret-scrub-gate.test.ts +257 -0
  476. package/src/tests/seed-registry.test.ts +142 -9
  477. package/src/tests/seed-scripts.test.ts +23 -0
  478. package/src/tests/session-cost-attribution.test.ts +748 -0
  479. package/src/tests/session-costs.test.ts +14 -15
  480. package/src/tests/session-logs.test.ts +83 -0
  481. package/src/tests/session-source-keys.test.ts +42 -1
  482. package/src/tests/sessions-detail-batch.test.ts +7 -0
  483. package/src/tests/sessions-move.test.ts +70 -0
  484. package/src/tests/sessions-tree.test.ts +98 -0
  485. package/src/tests/sessions.test.ts +69 -0
  486. package/src/tests/slack-config.test.ts +4 -18
  487. package/src/tests/slack-http-receiver.test.ts +472 -0
  488. package/src/tests/slack-inbound-logging.test.ts +64 -0
  489. package/src/tests/slack-leave-thread.test.ts +1 -1
  490. package/src/tests/slack-message-text.test.ts +104 -0
  491. package/src/tests/slack-mode-lifecycle.test.ts +6 -4
  492. package/src/tests/slack-render-v2.test.ts +405 -0
  493. package/src/tests/slack-skip-reaction.test.ts +2 -2
  494. package/src/tests/slack-start-reload-race.test.ts +67 -0
  495. package/src/tests/slack-steering.test.ts +22 -10
  496. package/src/tests/slack-thread-buffer-context.test.ts +1 -1
  497. package/src/tests/slack-thread-buffer-fold.test.ts +417 -0
  498. package/src/tests/slack-thread-buffer-restore.test.ts +198 -0
  499. package/src/tests/slack-thread-buffer-startup-restore.test.ts +86 -0
  500. package/src/tests/slack-thread-buffer.test.ts +34 -34
  501. package/src/tests/slack-thread-participants.test.ts +23 -5
  502. package/src/tests/slack-tool-blocks.test.ts +167 -0
  503. package/src/tests/status.test.ts +32 -6
  504. package/src/tests/steering-core.test.ts +13 -0
  505. package/src/tests/steering-enabled.test.ts +7 -1
  506. package/src/tests/steering-promotion.test.ts +24 -0
  507. package/src/tests/subscription-plans.test.ts +20 -1
  508. package/src/tests/swarm-config-reserved-keys.test.ts +17 -0
  509. package/src/tests/system-one-hosts-ui-mirror.test.ts +67 -0
  510. package/src/tests/task-artifacts.test.ts +50 -0
  511. package/src/tests/task-session-prompts.test.ts +95 -1
  512. package/src/tests/task-ui-action-route.test.ts +191 -0
  513. package/src/tests/task-ui-actions.test.ts +195 -0
  514. package/src/tests/task-ui-spec-fallback.test.ts +65 -0
  515. package/src/tests/task-ui-spec.test.ts +368 -0
  516. package/src/tests/workflow-agent-task-retry.test.ts +34 -1
  517. package/src/tests/workflow-system-one-extraction.test.ts +149 -1
  518. package/src/tools/chat-post.ts +19 -4
  519. package/src/tools/chat-reply.ts +20 -4
  520. package/src/tools/create-page.ts +21 -4
  521. package/src/tools/defer-task.ts +1 -1
  522. package/src/tools/get-swarm.ts +18 -2
  523. package/src/tools/join-swarm.ts +2 -1
  524. package/src/tools/kv/kv-write-auth.ts +17 -1
  525. package/src/tools/schedules/create-schedule.ts +22 -4
  526. package/src/tools/slack-post.ts +40 -7
  527. package/src/tools/slack-reply.ts +50 -14
  528. package/src/tools/store-progress.ts +69 -3
  529. package/src/types.ts +50 -4
  530. package/src/ui-spec/actions.ts +86 -0
  531. package/src/ui-spec/fallback.ts +19 -0
  532. package/src/ui-spec/slack.ts +17 -0
  533. package/src/ui-spec/validate.ts +169 -0
  534. package/src/utils/codex-rate-limits.ts +159 -0
  535. package/src/utils/constants.ts +60 -138
  536. package/src/utils/credentials.ts +2 -0
  537. package/src/utils/error-tracker.ts +19 -0
  538. package/src/utils/github-host.ts +217 -0
  539. package/src/utils/github-pull-request.ts +8 -5
  540. package/src/utils/literal-matcher.ts +118 -0
  541. package/src/utils/provider-account-telemetry.ts +331 -0
  542. package/src/utils/reasoning-events.ts +107 -0
  543. package/src/utils/secret-scrubber.ts +331 -25
  544. package/src/utils/subscription-plans.ts +11 -59
  545. package/src/utils/task-attachment-links.ts +9 -12
  546. package/src/utils/task-ui-spec.ts +67 -0
  547. package/src/vcs/index.ts +3 -0
  548. package/src/workflows/approval-notifications.ts +188 -12
  549. package/src/workflows/executors/system-one-extraction.ts +14 -7
  550. package/src/workflows/executors/system-one-providers.ts +22 -1
  551. package/src/workflows/task-step-routing.ts +8 -3
  552. package/templates/community/open-prompt-showreel/PLAYBOOK.md +1 -1
  553. package/templates/community/open-prompt-showreel/skills/open-prompt-showreel/SKILL.md +1 -1
  554. package/templates/extensions/README.md +1 -0
  555. package/templates/extensions/sql-admin-only/README.md +20 -0
  556. package/templates/extensions/sql-admin-only/hooks.ts +100 -0
  557. package/templates/extensions/sql-admin-only/manifest.json +8 -0
  558. package/templates/import/manifest.schema.json +136 -0
  559. package/templates/import/sources.schema.json +44 -0
  560. package/templates/skills/agent-browser/SKILL.md +1 -1
  561. package/templates/skills/agent-browser/content.md +1 -1
  562. package/templates/skills/apps/SKILL.md +151 -14
  563. package/templates/skills/apps/content.md +151 -14
  564. package/templates/skills/asset-namespaces/content.md +2 -1
  565. package/templates/skills/chat-sdk/content.md +17 -0
  566. package/templates/skills/db-query-guidance/content.md +2 -1
  567. package/templates/skills/scheduling/content.md +27 -0
  568. package/templates/skills/slack-interaction/content.md +12 -2
  569. package/templates/skills/swarm-docs/content.md +1 -0
  570. package/templates/skills/swarm-extensions/config.json +1 -1
  571. package/templates/skills/swarm-extensions/content.md +33 -23
  572. package/templates/skills/swarm-scripts/SKILL.md +13 -0
  573. package/templates/skills/swarm-scripts/content.md +13 -0
  574. package/templates/skills/ui-spec/config.json +14 -0
  575. package/templates/skills/ui-spec/content.md +127 -0
  576. package/templates/skills/work-on-task/SKILL.md +1 -1
  577. package/templates/skills/work-on-task/content.md +1 -1
  578. package/templates/skills/workflow-iterate/content.md +4 -7
  579. package/templates/workflows/dreaming/content.md +2 -2
  580. package/dist/acp-adapter-xq6s2z6t.js +0 -14
  581. package/dist/claude-adapter-r33pqnzx.js +0 -24
  582. package/dist/cli-dns0y538.js +0 -194
  583. package/dist/cli-m2z8jagn.js +0 -12078
  584. package/dist/fx-adapter-1rnxnf56.js +0 -17
  585. package/dist/grok-adapter-efhmf1r8.js +0 -17
  586. package/dist/handlers-anrr3py9.js +0 -32
  587. package/dist/index-2skqtd76.js +0 -12795
  588. package/dist/index-8w2aznds.js +0 -33
  589. package/dist/index-qnjvr362.js +0 -37
  590. package/dist/index-yzxd3sn9.js +0 -32
  591. package/dist/lead-zhxqbfdv.js +0 -69
  592. package/dist/worker-7j2907g6.js +0 -69
  593. package/src/tests/entrypoint-acp-target-binary.test.ts +0 -439
  594. package/dist/{cli-4caa1x7d.js → cli-tsa40663.js} +4 -4
  595. package/dist/{mistral-conversations-a45tx39a.js → mistral-conversations-0c30em7t.js} +4 -4
  596. package/dist/{openai-completions-xd579js7.js → openai-completions-f3n69rep.js} +18 -18
  597. package/dist/{pi-messages-hjbv8v10.js → pi-messages-zebyt7gb.js} +5 -5
@@ -0,0 +1,100 @@
1
+ import { block, type SwarmExtension } from "swarm-extension";
2
+ import { z } from "zod";
3
+
4
+ export const config = z.object({});
5
+
6
+ /** MCP tools that run raw SQL. db-query is the only one today. */
7
+ const SQL_TOOLS = new Set(["db-query"]);
8
+
9
+ const manifest = {
10
+ name: "sql-admin-only",
11
+ description: "Blocks db-query tool calls on tasks created by a non-admin user",
12
+ version: "1.1.0",
13
+ runtime: "api",
14
+ assets: { hooks: "hooks.ts" },
15
+ config,
16
+ } as const;
17
+
18
+ /**
19
+ * The task's creator and that user's `users.role`, the role the swarm shows for a
20
+ * requester (for example "Alice (admin)"). RBAC roles do not work here: every user is
21
+ * created with the RBAC `admin` role.
22
+ */
23
+ export const CREATOR_SQL = `SELECT t.requestedByUserId, u.role
24
+ FROM agent_tasks t
25
+ LEFT JOIN users u ON u.id = t.requestedByUserId
26
+ WHERE t.id = ?`;
27
+
28
+ type Envelope = { success?: boolean; data?: { rows?: unknown[] }; rows?: unknown[] } | null;
29
+
30
+ const cell = (row: unknown, i: number, key: string): unknown =>
31
+ Array.isArray(row) ? row[i] : (row as Record<string, unknown> | null)?.[key];
32
+
33
+ /**
34
+ * The dispatcher fails a pre hook OPEN when it runs past
35
+ * EXTENSION_HANDLER_TIMEOUT_MS (default 5s). Give the lookup a shorter budget so
36
+ * a slow lookup ends in our own block, not in a silent allow.
37
+ */
38
+ const lookupBudgetMs = (): number => {
39
+ const raw = Number(process.env.EXTENSION_HANDLER_TIMEOUT_MS);
40
+ const handlerMs = Number.isFinite(raw) && raw > 0 ? raw : 5_000;
41
+ return Math.floor(handlerMs * 0.6);
42
+ };
43
+
44
+ const withDeadline = async <T>(work: Promise<T>, ms: number): Promise<T> => {
45
+ let timer: ReturnType<typeof setTimeout> | undefined;
46
+ try {
47
+ return await Promise.race([
48
+ work,
49
+ new Promise<never>((_, reject) => {
50
+ timer = setTimeout(() => reject(new Error(`lookup timed out after ${ms}ms`)), ms);
51
+ }),
52
+ ]);
53
+ } finally {
54
+ if (timer) clearTimeout(timer);
55
+ }
56
+ };
57
+
58
+ const extension: SwarmExtension<typeof manifest> = (api) => {
59
+ api.on("pre.tool.call", async (event, ctx) => {
60
+ const tool = event.tool;
61
+ if (!SQL_TOOLS.has(tool)) return;
62
+
63
+ // No task context means no task creator: allow.
64
+ const taskId = event.requestInfo?.sourceTaskId;
65
+ if (!taskId) return;
66
+
67
+ // Creator lookup. A failed lookup blocks this SQL call only (fail closed).
68
+ let creator: string;
69
+ let role: string;
70
+ try {
71
+ const q = (await withDeadline(
72
+ ctx.swarm.db_query({ sql: CREATOR_SQL, params: [taskId] }),
73
+ lookupBudgetMs(),
74
+ )) as Envelope;
75
+ if (q?.success === false) throw new Error("db-query lookup returned success=false");
76
+ const row = (q?.data?.rows ?? q?.rows ?? [])[0];
77
+ // A successful lookup with no row: the id is not a task. The runner sends a
78
+ // random correlation id for sessions with no task (pool or channel-message
79
+ // triggers, src/commands/runner.ts effectiveTaskId). No task means no creator:
80
+ // allow, the same as a missing header. Errors and timeouts above still block.
81
+ if (!row) return;
82
+ creator = String(cell(row, 0, "requestedByUserId") ?? "");
83
+ role = String(cell(row, 1, "role") ?? "");
84
+ } catch (err) {
85
+ const message = err instanceof Error ? err.message : String(err);
86
+ const reason = `${tool} is restricted to admin task creators, and the creator of task ${taskId} could not be verified (${message}).`;
87
+ ctx.log.warn(reason, { tool, taskId });
88
+ return block(reason);
89
+ }
90
+
91
+ if (!creator) return;
92
+ if (role.trim().toLowerCase() === "admin") return;
93
+
94
+ const reason = `${tool} is restricted to admin task creators. Task ${taskId} was created by user ${creator}, whose role is ${role ? `"${role}"` : "not set"}.`;
95
+ ctx.log.warn(reason, { tool, taskId, requestedByUserId: creator });
96
+ return block(reason);
97
+ });
98
+ };
99
+
100
+ export default extension;
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "../manifest.schema.json",
3
+ "name": "sql-admin-only",
4
+ "description": "Blocks db-query tool calls on tasks created by a non-admin user",
5
+ "version": "1.1.0",
6
+ "runtime": "api",
7
+ "assets": { "hooks": "hooks.ts" }
8
+ }
@@ -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,20 +546,21 @@ 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"`. |
554
555
  | `Text` | `content` | `tone: "default" or "muted"`. |
555
556
  | `Markdown` | `content` | Rendered Markdown for help, instructions, and rich prose; no children. A link to a GitHub PR, issue, commit or repo, a dashboard task, agent, session or app, or an agent-fs file renders as a chip (icon plus short label), like agent output in a session; `[text](url)` keeps its text. |
556
557
  | `SearchInput` | `id` | `placeholder`, `label`, `shortcut` (one key, usually `"/"`: shows a keycap and focuses the field); writes debounced text to `/ui/<id>/value`; no children. |
557
- | `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`, `defaultValue` (seeds `/ui/<id>/value` once, before any interaction; a one-entry array with `multiple`); writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |
558
+ | `Select` | `id`, `options` | `options` are strings or `{ value, label?, icon?, hint? }`; `placeholder`, `label`, `clearable`, `searchable` (type to filter; on by default past 8 options), `searchPlaceholder`, `multiple`, `defaultValue` (seeds `/ui/<id>/value` once, before any interaction; a one-entry array with `multiple`; a value bound to a query that is still loading seeds when it arrives, unless the viewer already picked); writes a string or null to `/ui/<id>/value`, or with `multiple` a string array (empty = nothing picked); no children. |
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,26 @@ 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. |
592
+ | `PageFrame` | `pageId` | `device` (`desktop` default, or `mobile`: a 390 px wide frame), `height` (default `640px`), `fill`; a live, clickable swarm Page that reloads when the page changes; see below. |
584
593
 
585
594
  Table details:
586
595
 
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.
596
+ - `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
597
  - `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
598
  - `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
599
  - `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 +640,113 @@ Tree details:
631
640
  - 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
641
  - 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
642
 
643
+ Files and File details:
644
+
645
+ - 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.
646
+ - 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.
647
+ - `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`).
648
+ - `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" }`.
649
+ - `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".
650
+ - 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`.
651
+ - `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.
652
+ - 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.
653
+
654
+ DateRange and Timeline details:
655
+
656
+ - `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`.
657
+ - `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.
658
+
634
659
  SchemaForm details:
635
660
 
636
661
  - `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
662
  - 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
663
  - 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
664
 
665
+ Approval details (human-in-the-loop):
666
+
667
+ - `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.
668
+ - 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.
669
+ - 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".
670
+ - `showResolved: false` shows only the outcome line after resolution, not the answers. `compact: true` drops the card chrome.
671
+ - `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.
672
+
673
+ 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:
674
+
675
+ ```ts
676
+ export default async function run(args, ctx) {
677
+ const res: any = await ctx.swarm.request_humanInput({
678
+ title: `Deploy ${args.service}?`,
679
+ questions: [{ id: "go", type: "approval", label: "Ship it to production?" }],
680
+ detached: true,
681
+ });
682
+ return { requestId: res?.data?.requestId ?? res?.requestId };
683
+ }
684
+ ```
685
+
686
+ ```json
687
+ {
688
+ "askBtn": { "type": "Button", "props": { "label": "Request deploy", "busyWith": "requestDeploy" },
689
+ "on": { "press": { "action": "app.action", "params": { "name": "requestDeploy", "input": { "service": "api" } } } } },
690
+ "approve": {
691
+ "type": "Approval",
692
+ "props": {
693
+ "requestId": { "$state": "/actions/requestDeploy/result/requestId" },
694
+ "onResolved": [
695
+ { "action": "app.action", "params": { "name": "applyDecision",
696
+ "input": { "status": { "$chain": "status" }, "responses": { "$chain": "responses" } } } },
697
+ { "action": "ui.toast", "params": { "message": "Decision applied", "tone": "success" } }
698
+ ]
699
+ }
700
+ }
701
+ }
702
+ ```
703
+
704
+ 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.
705
+
706
+ SessionThread details — a chat on an app page, one session per viewer and `sessionKey`:
707
+
708
+ - `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.
709
+ - `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.
710
+ - 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.
711
+ - Sending a message takes one of three routes:
712
+ 1. No session yet → run `onDispatch` with `$form = { message }` and `$chain = { leafTaskId: null, newTaskId: null }`. Its `app.action` creates the session's root task.
713
+ 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.
714
+ 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.
715
+ - 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.
716
+ - "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.
717
+ - 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.
718
+ - Without `fill` the thread is 420 px tall; `fill: true` fills a `fill`-aware parent, and keeps at least 420 px on a phone, where a `Split` or `Grid` stacks its panes. Inside an element instance, `id` is namespaced per instance, so two instances keep separate drafts.
719
+
720
+ ```json
721
+ { "type": "SessionThread", "props": {
722
+ "id": "chat",
723
+ "sessionKey": { "$state": "/route/params/screenId" },
724
+ "onDispatch": [{ "action": "app.action", "params": {
725
+ "name": "editScreen", "input": { "$form": "" }, "parentTaskId": { "$chain": "leafTaskId" } } }]
726
+ } }
727
+ ```
728
+
729
+ PageFrame details — a live swarm Page inside the app, for a preview pane next to a `SessionThread`:
730
+
731
+ - It renders the body `/pages/<pageId>` shows: an HTML page in a sandboxed iframe (scripts, forms and popups; never top navigation), a JSON page inline. The viewer can click and scroll it.
732
+ - It checks the page every 3 s and reloads by itself when the page's `updatedAt` moves: a new version, a restore, a theme switch. A reload resets scroll and any state inside the page.
733
+ - `pageId` is a page id (32 hex characters), usually bound: `{ "$state": "/queries/project/data/0/pageId" }`. A literal slug is rejected; an empty id shows "No page selected".
734
+ - The viewer needs read access to the page: an authed page launches a page session for them, a password page asks for its password.
735
+ - `device: "mobile"` centers a 390 px wide frame, so the page's own media queries see a phone. A JSON page follows the dashboard viewport instead. Switch devices with two `PageFrame`s in `Tabs`, or bind `device` to a `Select`.
736
+
737
+ ```json
738
+ { "type": "PageFrame", "props": {
739
+ "pageId": { "$state": "/queries/project/data/0/pageId" },
740
+ "device": { "$state": "/ui/device/value" },
741
+ "fill": true
742
+ } }
743
+ ```
744
+
640
745
  Form details:
641
746
 
642
- - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, or `enum`, and enum fields need `options`.
747
+ - `fields[]`: `{ name, label?, kind?, options?: string[], placeholder?, required? }`; `kind` is `string`, `text`, `number`, `boolean`, `date`, `enum`, or `file`, and enum fields need `options`.
748
+ - `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`.
749
+ - 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
750
  - Values live at `/forms/<formId>/<fieldName>`. `onSubmit` is an action chain.
644
751
  - 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
752
 
@@ -647,10 +754,28 @@ Drawer details:
647
754
 
648
755
  - `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
756
  - `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.
757
+ - `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.
758
+
759
+ List + detail recipe (a row click opens the record beside the table):
760
+
761
+ ```json
762
+ "params": { "issue": { "kind": "string" } },
763
+ "elements": {
764
+ "root": { "type": "Stack", "props": {}, "children": ["table", "issue"] },
765
+ "table": { "type": "Table", "props": {
766
+ "data": { "$state": "/queries/issues/data" },
767
+ "columns": [{ "key": "title" }, { "key": "status", "kind": "status" }],
768
+ "selectedId": { "$state": "/route/params/issue" },
769
+ "onRowClick": [{ "action": "app.navigate", "params": { "page": "main", "params": { "issue": { "$row": "id" } } } }] } },
770
+ "issue": { "type": "Drawer", "props": { "param": "issue", "presentation": "split", "size": "md", "title": "Issue" },
771
+ "children": ["issueDetail"] },
772
+ "issueDetail": { "type": "DetailList", "props": { "data": { "$state": "/queries/issue/data/0" }, "fields": [{ "key": "title" }] } }
773
+ }
774
+ ```
650
775
 
651
776
  DetailList details:
652
777
 
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`.
778
+ - `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
779
 
655
780
  Motion details:
656
781
 
@@ -736,7 +861,7 @@ Valid `$state` roots are:
736
861
 
737
862
  `/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
863
 
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:
864
+ 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
865
 
741
866
  | Sentinel | Resolves to |
742
867
  |---|---|
@@ -746,21 +871,33 @@ Only inside action-chain `params` (`on.<event>`, `Table.rowActions[].actions`, `
746
871
  | `{ "$form": "title" }` | One current Form value. |
747
872
  | `{ "$form": "" }` | All current Form values. |
748
873
  | `{ "$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. |
874
+ | `{ "$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`; `Form.onSubmit` carries `createdRowId` (the row its newest `app.mutate` create step made). 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), 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
875
  | `{ "$chain": "" }` | The whole chain scope. |
751
876
 
752
877
  Each sentinel object must contain exactly the single key shown.
753
878
 
754
879
  An action-chain step is `{ "action": "<type>", "params": {...} }`. Available action types:
755
880
 
756
- - `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.
881
+ - `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. In a `Form.onSubmit` chain, steps after a `create` read the new row's id as `{ "$chain": "createdRowId" }`, e.g. to navigate to the new row (not `$state`: the renderer resolves a chain's `$state` reads when the form renders, before the row exists).
757
882
  - `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.
883
+ - `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? }` keys a task-kind action's task into the viewer's `SessionThread` session for that key; the server builds the key, never the page. SessionThread sets it on its own `onDispatch` steps (replacing any value there). Any other chain can set it to start a session: `key` is a literal plain token (validated like `sessionKey`) or a binding; a key that does not resolve to a token fails the step instead of creating a task outside the session, `scope: "shared"` is rejected, and a session step defaults to `followUp: false`. Example, a create form that sends the idea as the chat's first message:
884
+
885
+ ```json
886
+ "onSubmit": [
887
+ { "action": "app.mutate", "params": { "model": "project", "op": "create", "values": { "name": { "$form": "name" } } } },
888
+ { "action": "app.action", "params": { "name": "build", "input": { "message": { "$form": "idea" } }, "session": { "key": { "$chain": "createdRowId" } } } },
889
+ { "action": "app.navigate", "params": { "page": "studio", "params": { "projectId": { "$chain": "createdRowId" } } } }
890
+ ]
891
+ ```
892
+
893
+ The `studio` page's `SessionThread` with `"sessionKey": { "$state": "/route/params/projectId" }` then shows the idea as its first message and the running task, with no second send.
759
894
  - `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
895
  - `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
896
  - `swarm.sdk`: `{ sdk, args? }`; invokes a catalog-supported Swarm browser SDK method with the viewer's bearer.
762
897
  - `swarm.call`: `{ method, endpoint: "/api/...", body? }`, where `method` is `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, or `"PATCH"`; raw authenticated API call.
763
898
 
899
+ 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.
900
+
764
901
  ## Patch semantics
765
902
 
766
903
  `app-patch.definition` is RFC 7396 JSON Merge Patch applied to the stored definition: