@desplega.ai/agent-swarm 2.8.1 → 2.8.3

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 (318) hide show
  1. package/dist/acp-adapter-xq6s2z6t.js +14 -0
  2. package/dist/{actions-pwjpn0j6.js → actions-ewz7bp4g.js} +20 -19
  3. package/dist/{amp-adapter-cq9jgj6x.js → amp-adapter-f25tqhnf.js} +3 -3
  4. package/dist/{app-cnfffgwg.js → app-mkptw0k7.js} +4 -4
  5. package/dist/{assistant-kpn317y1.js → assistant-c47rfe77.js} +23 -22
  6. package/dist/{boot-args-schema-pbbnhmc3.js → boot-args-schema-4vb0xsat.js} +1 -1
  7. package/dist/{boot-reembed-9m0ysxma.js → boot-reembed-1ghy2sab.js} +1 -1
  8. package/dist/{boot-reembed-majbn53m.js → boot-reembed-htr73hbs.js} +1 -1
  9. package/dist/{boot-scrub-sweep-app8g8ym.js → boot-scrub-sweep-yrytg42z.js} +4 -4
  10. package/dist/{boot-seeds-pbtmvcjm.js → boot-seeds-n2b3dx4e.js} +4 -4
  11. package/dist/{boxd-qbkxy6ap.js → boxd-jmfqgkqa.js} +2 -2
  12. package/dist/{claude-adapter-wn1g3qp5.js → claude-adapter-r33pqnzx.js} +8 -9
  13. package/dist/{claude-managed-adapter-jh6c523j.js → claude-managed-adapter-hddmxjyj.js} +4 -4
  14. package/dist/{claude-managed-setup-pd47nzch.js → claude-managed-setup-hfvry1bd.js} +5 -5
  15. package/dist/{claude-sdk-session-3a2a6589.js → claude-sdk-session-0hamqzc7.js} +10 -11
  16. package/dist/{cli-v1dv1r37.js → cli-0bcgyj5b.js} +74 -3
  17. package/dist/{cli-a3b239vq.js → cli-0vksaxvr.js} +2 -2
  18. package/dist/{cli-mrt48bx7.js → cli-15204js0.js} +1 -1
  19. package/dist/{cli-8aes17e4.js → cli-1m96dc36.js} +3 -3
  20. package/dist/{cli-2r0jcc3k.js → cli-2d0cghfn.js} +1 -1
  21. package/dist/{cli-wk18cm92.js → cli-4ax9mvvg.js} +4 -4
  22. package/dist/{cli-9wngrawf.js → cli-4dpkjc2e.js} +6 -6
  23. package/dist/{cli-x1wa213s.js → cli-4e1hfbpq.js} +5 -5
  24. package/dist/{cli-7349va39.js → cli-500c09j9.js} +921 -431
  25. package/dist/{cli-m4dqmnbp.js → cli-54qr8mcd.js} +2 -2
  26. package/dist/{cli-m88rpzkh.js → cli-5a7szzfh.js} +2 -2
  27. package/dist/{cli-bst1vp7e.js → cli-5y2fvw4z.js} +13 -5
  28. package/dist/{cli-vj75tyaw.js → cli-6yygkr0w.js} +7 -7
  29. package/dist/{cli-7b8sbmag.js → cli-7c5tgqhf.js} +5 -5
  30. package/dist/{cli-2gxeg5gr.js → cli-8476gtwf.js} +1 -1
  31. package/dist/{cli-yncmerje.js → cli-922z7gwm.js} +4 -4
  32. package/dist/{cli-jrzkw01m.js → cli-93t5s4zq.js} +2 -2
  33. package/dist/{cli-sn7rtnj4.js → cli-9zmb7ptc.js} +9 -9
  34. package/dist/{cli-tk7cjj8h.js → cli-am1ptset.js} +3 -3
  35. package/dist/{cli-cyhbbd1z.js → cli-awwptga4.js} +1 -1
  36. package/dist/{cli-89cqnasv.js → cli-bhsfbmk8.js} +19 -7
  37. package/dist/{cli-9vhebtjz.js → cli-bj6qhgte.js} +15 -32
  38. package/dist/{cli-g70vxtjh.js → cli-c0xjnr8z.js} +2 -2
  39. package/dist/{cli-vqptjbr7.js → cli-c3ng0mb4.js} +14 -14
  40. package/dist/{cli-re4raaj0.js → cli-c71n3bxq.js} +11 -6
  41. package/dist/{cli-7p1kvkck.js → cli-crpf163n.js} +25 -18
  42. package/dist/{cli-k0wwfqbg.js → cli-dns0y538.js} +4 -0
  43. package/dist/{cli-d3p5vwbk.js → cli-dpsfwh7n.js} +13 -21
  44. package/dist/{cli-xzm9vcfg.js → cli-dtdht77h.js} +2 -2
  45. package/dist/{cli-bb431xey.js → cli-e2w34h6z.js} +231 -68
  46. package/dist/{cli-eddnyg3t.js → cli-emekyyhr.js} +1 -1
  47. package/dist/{cli-d84byzn8.js → cli-f1kwb5fc.js} +109 -33
  48. package/dist/{cli-0jzra9ad.js → cli-gn9y6fn7.js} +2 -2
  49. package/dist/{cli-tqegb8eq.js → cli-gpz1d0t2.js} +4 -4
  50. package/dist/{cli-7w69ne2f.js → cli-h9yy18gy.js} +239 -67
  51. package/dist/{cli-m5akxq8q.js → cli-j8cjdzan.js} +1 -1
  52. package/dist/{cli-m9s2qff2.js → cli-jg5txpm6.js} +187 -93
  53. package/dist/{cli-k26bkr9t.js → cli-k2rw11py.js} +3 -3
  54. package/dist/{cli-93k32c37.js → cli-k96cecs7.js} +377 -61
  55. package/dist/{cli-3vjhs18n.js → cli-kd56bmk4.js} +1 -1
  56. package/dist/{cli-k0615eh8.js → cli-kmemts3w.js} +13 -13
  57. package/dist/{cli-pcad4cb1.js → cli-knva3nmx.js} +2 -2
  58. package/dist/{cli-b085njxz.js → cli-kw44j53p.js} +15 -14
  59. package/dist/{cli-bsywb58a.js → cli-mdpbjnzq.js} +10 -10
  60. package/dist/{cli-syybb0p1.js → cli-me0r8gzr.js} +35 -76
  61. package/dist/{cli-4r05hnqa.js → cli-mwwmka77.js} +15 -15
  62. package/dist/{cli-1xh9a7hn.js → cli-n5t077me.js} +2 -2
  63. package/dist/{cli-rvhdmjvt.js → cli-nx2n3z6p.js} +1 -1
  64. package/dist/{cli-28fq781p.js → cli-pe4d96rb.js} +1 -1
  65. package/dist/{cli-3rkdne1h.js → cli-pxwtcgcp.js} +2 -2
  66. package/dist/{cli-zcsw143p.js → cli-qmqt520k.js} +2 -2
  67. package/dist/{cli-2zp0et3v.js → cli-qps8je6j.js} +70 -19
  68. package/dist/{cli-xae4g51r.js → cli-rh15cakt.js} +1 -1
  69. package/dist/{cli-k93bq1wq.js → cli-rjvsf9qa.js} +5 -5
  70. package/dist/{cli-6mma83xa.js → cli-rqfvkx5t.js} +7 -7
  71. package/dist/{cli-dy32zecz.js → cli-s7zz734a.js} +1 -1
  72. package/dist/{cli-yn2bbre9.js → cli-s8p8hhty.js} +2 -2
  73. package/dist/{cli-vbh10fqa.js → cli-sdvcrq5x.js} +5 -5
  74. package/dist/{cli-b5rs97a6.js → cli-sg27rk2t.js} +5 -5
  75. package/dist/{cli-d6521kb5.js → cli-skmhsnqh.js} +1 -1
  76. package/dist/{cli-5mrq3ake.js → cli-t4dv07kr.js} +1 -1
  77. package/dist/{cli-hxpyc9sn.js → cli-t5ys4ebm.js} +3 -3
  78. package/dist/{cli-qmqk2yc2.js → cli-tas6ckky.js} +2 -2
  79. package/dist/{cli-p1w18yhx.js → cli-tf79ryyy.js} +1 -1
  80. package/dist/{cli-kc7v1nfv.js → cli-tnzebztn.js} +1 -1
  81. package/dist/{cli-gax7fk3t.js → cli-vx421edw.js} +3 -3
  82. package/dist/{cli-kchjb7qy.js → cli-x3ex5bqf.js} +1 -1
  83. package/dist/cli-yss07azk.js +142 -0
  84. package/dist/{cli-0ntbxyaa.js → cli-z8cvws4c.js} +363 -47
  85. package/dist/{cli-tacge1w0.js → cli-zdaypkq9.js} +146 -52
  86. package/dist/{cli-b8e9nb04.js → cli-zeaehgyd.js} +2 -2
  87. package/dist/{cli-jcpr5smb.js → cli-ztq5z4e1.js} +4 -4
  88. package/dist/cli.js +21 -21
  89. package/dist/{codex-adapter-nha71q3n.js → codex-adapter-2brxx5ta.js} +7 -8
  90. package/dist/{codex-hook-h3vk6xzr.js → codex-hook-c930c3ea.js} +2 -2
  91. package/dist/{codex-login-bcda78ge.js → codex-login-cbrs1h5w.js} +1 -1
  92. package/dist/{codex-session-runner-ak9x1k1h.js → codex-session-runner-y9anfj0r.js} +8 -9
  93. package/dist/{commands-f587qpq8.js → commands-wn9q06qr.js} +3 -3
  94. package/dist/{controller-hxx8wwy1.js → controller-fw608czd.js} +4 -4
  95. package/dist/{controllers-connect-k5sg9m9h.js → controllers-connect-63j5rdcm.js} +20 -20
  96. package/dist/{cursor-adapter-n5nc3mfe.js → cursor-adapter-6mb9jme8.js} +2 -2
  97. package/dist/{db-nzf8zb5z.js → db-0m6v5tq4.js} +3 -3
  98. package/dist/{db-amm8w15a.js → db-y4wfrzbm.js} +4 -2
  99. package/dist/{devin-adapter-xedz98zv.js → devin-adapter-r0yx3gv8.js} +1 -1
  100. package/dist/{dispatcher-89zrts8f.js → dispatcher-9tq2zzdj.js} +17 -17
  101. package/dist/{docker-866qpzt9.js → docker-j75atvpt.js} +2 -2
  102. package/dist/{dsh-adapter-nrhbrjz8.js → dsh-adapter-t09sv4tq.js} +2 -2
  103. package/dist/{e2b-s16txnpx.js → e2b-7s9dscap.js} +3 -3
  104. package/dist/{e2b-jkwfhbcv.js → e2b-a7vzs2vj.js} +3 -3
  105. package/dist/{easter-egg-3d-533knw22.js → easter-egg-3d-fbwvmwhe.js} +1 -1
  106. package/dist/{embedding-space-ezwenjmj.js → embedding-space-wh8de1t9.js} +6 -6
  107. package/dist/{embeddings-np74ht6g.js → embeddings-3hpbdtjr.js} +1 -1
  108. package/dist/{event-bus-e66gh7cc.js → event-bus-tr6h3gv8.js} +1 -1
  109. package/dist/{execute-b3mrb1mv.js → execute-4bdf8sdy.js} +1 -1
  110. package/dist/{external-channel-z46yx9d7.js → external-channel-ts2fwqh0.js} +2 -2
  111. package/dist/fx-adapter-1rnxnf56.js +17 -0
  112. package/dist/grok-adapter-efhmf1r8.js +17 -0
  113. package/dist/handlers-anrr3py9.js +32 -0
  114. package/dist/{heartbeat-dt9qw9c8.js → heartbeat-2ze5fzpc.js} +20 -20
  115. package/dist/{hook-8k6fbz9b.js → hook-ca54yd4s.js} +5 -5
  116. package/dist/{hook-jgcgygex.js → hook-gaehe2w5.js} +8 -8
  117. package/dist/{http-haw4r8ne.js → http-jfg8t2yk.js} +3839 -122
  118. package/dist/{index-tvfafeyy.js → index-3gv6sc4z.js} +1 -1
  119. package/dist/{index-tez78qj3.js → index-3yvzbhxd.js} +100 -23
  120. package/dist/index-8w2aznds.js +33 -0
  121. package/dist/{index-5gk12my8.js → index-csgrxedz.js} +1 -1
  122. package/dist/index-qnjvr362.js +37 -0
  123. package/dist/index-yzxd3sn9.js +32 -0
  124. package/dist/{keepalive-xn6s7rmg.js → keepalive-k2a3qe73.js} +4 -4
  125. package/dist/lead-zhxqbfdv.js +69 -0
  126. package/dist/{maintenance-vdts800b.js → maintenance-gb5sd5nc.js} +1 -1
  127. package/dist/{node-4c5jqxr3.js → node-7qsx5kvm.js} +1 -1
  128. package/dist/{oauth-refresh-sweep-094c8wfk.js → oauth-refresh-sweep-y7rm6bkb.js} +3 -3
  129. package/dist/{onboard-v99eh56m.js → onboard-jmc5qerv.js} +4 -4
  130. package/dist/{opencode-adapter-dsagkhtw.js → opencode-adapter-7eade9ev.js} +6 -7
  131. package/dist/{otel-impl-q7yr9yp0.js → otel-impl-8j1xhxqd.js} +2 -2
  132. package/dist/{pi-mono-adapter-546cd1cc.js → pi-mono-adapter-yqmaf32x.js} +14 -13
  133. package/dist/{pricing-refresh-7dh2yase.js → pricing-refresh-1nj722h6.js} +2 -2
  134. package/dist/{rbac-roles-mdmc96p4.js → rbac-roles-b1mtr6dr.js} +3 -3
  135. package/dist/{rbac-roles-npbmdh77.js → rbac-roles-n1f3frk1.js} +2 -2
  136. package/dist/{render-v2-twhhwmms.js → render-v2-1gfpd8rj.js} +4 -4
  137. package/dist/{resume-5gsrjd5e.js → resume-w1s1eh5v.js} +7 -7
  138. package/dist/{runtime-1hv06jsn.js → runtime-84g5egsc.js} +1 -1
  139. package/dist/{session-access-m191x30x.js → session-access-y6z1txk4.js} +4 -4
  140. package/dist/{session-source-backfill-nt923ask.js → session-source-backfill-gxxwfh12.js} +3 -3
  141. package/dist/{setup-wv467afy.js → setup-r91gstyk.js} +1 -1
  142. package/dist/{virtual-modules-gazyapte.js → virtual-modules-cgnj6kme.js} +3 -3
  143. package/dist/{work-objects-8zkrpy13.js → work-objects-qcxzg61c.js} +20 -20
  144. package/dist/worker-7j2907g6.js +69 -0
  145. package/dist/{worker-follow-up-cecqszem.js → worker-follow-up-y2d2h7km.js} +19 -17
  146. package/dist/{x-2fyrt5pp.js → x-qhxq2ama.js} +2 -2
  147. package/openapi.json +2908 -351
  148. package/package.json +4 -4
  149. package/src/apps/catalog.generated.json +120 -1
  150. package/src/apps/definition.ts +38 -11
  151. package/src/apps/page-validator.ts +88 -0
  152. package/src/be/db/model-profiles.ts +110 -11
  153. package/src/be/db/tasks/read.ts +53 -0
  154. package/src/be/db/workflow-run-definitions.ts +19 -8
  155. package/src/be/db-client.ts +43 -5
  156. package/src/be/db.ts +40 -9
  157. package/src/be/migrations/284_model_profile_fallbacks.sql +9 -0
  158. package/src/be/migrations/289_automation_savings_daily.sql +47 -0
  159. package/src/be/migrations/291_task_slack_participants.sql +4 -0
  160. package/src/be/migrations/293_savings_component_links.sql +58 -0
  161. package/src/be/migrations/296_automation_savings_daily_read_index.sql +6 -0
  162. package/src/be/model-profile-check.ts +53 -20
  163. package/src/be/runtime-pools/routing.ts +1 -0
  164. package/src/be/savings/calibrate.ts +468 -0
  165. package/src/be/savings/compute.ts +677 -0
  166. package/src/be/savings/model.ts +674 -0
  167. package/src/be/savings/read.ts +1500 -0
  168. package/src/be/savings/rollup.ts +571 -0
  169. package/src/be/scripts/run-credential.ts +15 -3
  170. package/src/be/scripts/typecheck.ts +91 -4
  171. package/src/be/seed/agent-fs-provision.ts +48 -11
  172. package/src/be/seed/workflows-seeder.ts +67 -23
  173. package/src/be/seed-scripts/catalog/dreaming-learnings.ts +10 -2
  174. package/src/be/seed-scripts/catalog/dreaming-memtax-create.ts +70 -4
  175. package/src/be/skill-parser.ts +19 -7
  176. package/src/be/swarm-config-guard.ts +8 -0
  177. package/src/be/users.ts +29 -2
  178. package/src/commands/onboard/agent-fs-version.ts +1 -1
  179. package/src/commands/provider-error-class.ts +97 -0
  180. package/src/commands/runner.ts +258 -58
  181. package/src/extensions/contract-types.generated.ts +1 -1
  182. package/src/http/all-routes.ts +2 -0
  183. package/src/http/fs.ts +8 -2
  184. package/src/http/index.ts +11 -0
  185. package/src/http/model-profiles.ts +43 -10
  186. package/src/http/poll.ts +15 -1
  187. package/src/http/requested-by.ts +97 -1
  188. package/src/http/savings-calibration.ts +277 -0
  189. package/src/http/savings.ts +849 -0
  190. package/src/http/scripts.ts +26 -15
  191. package/src/http/tasks.ts +89 -9
  192. package/src/http/trackers/authorize-gate.ts +41 -0
  193. package/src/http/trackers/jira.ts +26 -4
  194. package/src/http/trackers/linear.ts +26 -4
  195. package/src/integrations/chat-sdk/limits.ts +6 -1
  196. package/src/jira/oauth.ts +7 -1
  197. package/src/linear/README.md +2 -1
  198. package/src/linear/oauth.ts +7 -1
  199. package/src/prompts/session-templates.ts +80 -3
  200. package/src/providers/acp-targets.ts +1 -1
  201. package/src/providers/amp-adapter.ts +1 -1
  202. package/src/providers/claude-adapter.ts +0 -20
  203. package/src/providers/claude-flag-settings.ts +12 -10
  204. package/src/providers/codex-adapter.ts +12 -34
  205. package/src/providers/opencode-adapter.ts +34 -12
  206. package/src/providers/pi-mono-adapter.ts +6 -5
  207. package/src/providers/types.ts +7 -0
  208. package/src/scheduler/scheduler.ts +20 -14
  209. package/src/scripts-runtime/ctx.ts +1 -1
  210. package/src/scripts-runtime/executors/quickjs-bundle.ts +1 -0
  211. package/src/scripts-runtime/executors/quickjs-prelude.ts +162 -2
  212. package/src/scripts-runtime/executors/quickjs-runner.ts +4 -1
  213. package/src/scripts-runtime/sdk-allowlist.ts +11 -1
  214. package/src/scripts-runtime/stdlib/fetch.ts +113 -15
  215. package/src/scripts-runtime/stdlib/index.ts +3 -1
  216. package/src/scripts-runtime/stdlib/retry.ts +174 -0
  217. package/src/scripts-runtime/swarm-sdk.ts +192 -17
  218. package/src/scripts-runtime/types/stdlib.d.ts +95 -4
  219. package/src/scripts-runtime/types/swarm-extension.d.ts +60 -0
  220. package/src/scripts-runtime/types/swarm-sdk.d.ts +69 -2
  221. package/src/slack/actions.ts +1 -0
  222. package/src/slack/assistant.ts +2 -0
  223. package/src/slack/enrich.ts +144 -50
  224. package/src/slack/handlers.ts +37 -95
  225. package/src/slack/templates.ts +9 -0
  226. package/src/slack/thread-buffer.ts +45 -71
  227. package/src/slack/thread-participants.ts +187 -0
  228. package/src/tasks/worker-follow-up.ts +142 -3
  229. package/src/tests/agent-fs-provision-seeder.test.ts +81 -0
  230. package/src/tests/apps-chart-shell.test.ts +170 -0
  231. package/src/tests/apps-icon.test.ts +156 -2
  232. package/src/tests/base-prompt.test.ts +5 -4
  233. package/src/tests/chat-sdk-relay.test.ts +12 -0
  234. package/src/tests/claude-adapter-binary.test.ts +7 -1
  235. package/src/tests/claude-adapter.test.ts +10 -64
  236. package/src/tests/claude-flag-settings.test.ts +15 -11
  237. package/src/tests/claude-hook-credentials.test.ts +0 -1
  238. package/src/tests/claude-sdk-lifecycle.test.ts +5 -1
  239. package/src/tests/codex-adapter.test.ts +28 -78
  240. package/src/tests/comb-default.test.ts +6 -0
  241. package/src/tests/core-auth.test.ts +7 -6
  242. package/src/tests/create-task-vcs-repo.test.ts +136 -0
  243. package/src/tests/db-client-busy-retry.test.ts +58 -6
  244. package/src/tests/db-task-read-contract.test.ts +2 -0
  245. package/src/tests/db-task-write-contract.test.ts +1 -0
  246. package/src/tests/deploy-guard.test.ts +154 -0
  247. package/src/tests/docs-index-footprint.test.js +3 -3
  248. package/src/tests/dreaming-learnings.test.ts +104 -0
  249. package/src/tests/extensions-pre-task.test.ts +4 -2
  250. package/src/tests/fetch-resolved-env.test.ts +47 -1
  251. package/src/tests/fixtures/app-shell-charts-definition.json.txt +180 -0
  252. package/src/tests/model-profile-fallbacks.test.ts +482 -0
  253. package/src/tests/model-profiles-api.test.ts +1 -0
  254. package/src/tests/opencode-adapter.test.ts +53 -6
  255. package/src/tests/pi-mono-session-cost-on-abort.test.ts +115 -0
  256. package/src/tests/prompt-template-session.test.ts +17 -1
  257. package/src/tests/provider-error-class.test.ts +174 -0
  258. package/src/tests/runner-provider-fallback.test.ts +197 -0
  259. package/src/tests/runner-requester-profile.test.ts +139 -1
  260. package/src/tests/savings-calibration-api.test.ts +264 -0
  261. package/src/tests/savings-calibration.test.ts +201 -0
  262. package/src/tests/savings-compound.test.ts +774 -0
  263. package/src/tests/savings-compute.test.ts +215 -0
  264. package/src/tests/savings-fleet-latency.test.ts +143 -0
  265. package/src/tests/savings-fleet-read.test.ts +195 -0
  266. package/src/tests/savings-fleet-scale.test.ts +222 -0
  267. package/src/tests/savings-model.test.ts +499 -0
  268. package/src/tests/savings-read.test.ts +367 -0
  269. package/src/tests/savings-rollup.test.ts +766 -0
  270. package/src/tests/savings-scripts.test.ts +611 -0
  271. package/src/tests/script-connections.test.ts +4 -0
  272. package/src/tests/script-executor-conformance.test.ts +444 -0
  273. package/src/tests/scripts-http.test.ts +55 -0
  274. package/src/tests/scripts-runtime-fetch.test.ts +2 -2
  275. package/src/tests/sdk-allowlist.test.ts +40 -0
  276. package/src/tests/secret-rules.test.ts +124 -1
  277. package/src/tests/secret-scrubber.test.ts +1 -1
  278. package/src/tests/seed-workflows.test.ts +167 -11
  279. package/src/tests/skill-parser.test.ts +45 -0
  280. package/src/tests/slack-dm-implicit-mention.test.ts +20 -1
  281. package/src/tests/slack-identity-resolution.test.ts +23 -0
  282. package/src/tests/slack-inbound-files.test.ts +2 -1
  283. package/src/tests/slack-thread-participants.test.ts +429 -0
  284. package/src/tests/tool-annotations.test.ts +30 -0
  285. package/src/tests/tracker-oauth-authorize-auth.test.ts +262 -0
  286. package/src/tests/workflow-definition-pinning.test.ts +128 -3
  287. package/src/tests/workflow-script-principal.test.ts +94 -4
  288. package/src/tools/app-upsert.ts +1 -1
  289. package/src/tools/model-profiles/list-model-profiles.ts +4 -2
  290. package/src/tools/update-profile.ts +1 -1
  291. package/src/types.ts +146 -33
  292. package/src/utils/constants.ts +2 -0
  293. package/src/utils/mcp-server-fetcher.test.ts +89 -0
  294. package/src/utils/mcp-server-fetcher.ts +13 -5
  295. package/src/utils/request-auth-context.ts +24 -0
  296. package/src/utils/secret-rules.generated.ts +1 -1
  297. package/src/utils/secret-scrubber.ts +154 -29
  298. package/src/workflows/executors/swarm-script.ts +23 -19
  299. package/templates/skills/apps/SKILL.md +62 -3
  300. package/templates/skills/apps/content.md +62 -3
  301. package/templates/skills/swarm-docs/content.md +2 -0
  302. package/templates/skills/swarm-scripts/SKILL.md +5 -4
  303. package/templates/skills/swarm-scripts/content.md +5 -4
  304. package/templates/skills/work-on-task/SKILL.md +1 -1
  305. package/templates/skills/work-on-task/content.md +1 -1
  306. package/templates/workflows/dreaming/content.md +1 -1
  307. package/dist/acp-adapter-pdy3qsvg.js +0 -15
  308. package/dist/cli-4bd1rck6.js +0 -4
  309. package/dist/cli-jywyhqws.js +0 -104
  310. package/dist/fx-adapter-3q12snn6.js +0 -18
  311. package/dist/grok-adapter-ahb1w033.js +0 -18
  312. package/dist/handlers-vbww69re.js +0 -32
  313. package/dist/index-4xwaf5th.js +0 -32
  314. package/dist/index-f0hcrs8e.js +0 -33
  315. package/dist/index-s4ewdma4.js +0 -37
  316. package/dist/lead-6ygbfhbh.js +0 -70
  317. package/dist/worker-mz5z7kj0.js +0 -70
  318. package/src/providers/ctx-mode-env.ts +0 -10
package/openapi.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "openapi": "3.1.0",
3
3
  "info": {
4
4
  "title": "Agent Swarm API",
5
- "version": "2.8.1",
5
+ "version": "2.8.3",
6
6
  "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
7
7
  },
8
8
  "servers": [
@@ -279,6 +279,54 @@
279
279
  "slackUserId": {
280
280
  "type": "string"
281
281
  },
282
+ "slackParticipants": {
283
+ "type": "object",
284
+ "properties": {
285
+ "people": {
286
+ "type": "array",
287
+ "items": {
288
+ "type": "object",
289
+ "properties": {
290
+ "slackUserId": {
291
+ "type": "string"
292
+ },
293
+ "userId": {
294
+ "type": "string"
295
+ },
296
+ "trust": {
297
+ "type": "string",
298
+ "enum": [
299
+ "internal",
300
+ "external",
301
+ "unknown"
302
+ ]
303
+ },
304
+ "starter": {
305
+ "type": "boolean"
306
+ },
307
+ "newest": {
308
+ "type": "boolean"
309
+ },
310
+ "asked": {
311
+ "type": "boolean"
312
+ }
313
+ },
314
+ "required": [
315
+ "slackUserId",
316
+ "trust"
317
+ ]
318
+ }
319
+ },
320
+ "more": {
321
+ "type": "integer",
322
+ "minimum": 0
323
+ }
324
+ },
325
+ "required": [
326
+ "people",
327
+ "more"
328
+ ]
329
+ },
282
330
  "slackReplySent": {
283
331
  "type": "boolean",
284
332
  "default": false
@@ -399,6 +447,60 @@
399
447
  "resolvedProfile": {
400
448
  "type": "string"
401
449
  },
450
+ "fallbackHops": {
451
+ "type": "array",
452
+ "items": {
453
+ "type": "object",
454
+ "properties": {
455
+ "from": {
456
+ "type": "string"
457
+ },
458
+ "profile": {
459
+ "type": "string"
460
+ },
461
+ "errorClass": {
462
+ "type": "string",
463
+ "enum": [
464
+ "rate_limit",
465
+ "model_window",
466
+ "seat",
467
+ "credits",
468
+ "overloaded",
469
+ "server_error",
470
+ "auth",
471
+ "pool_empty"
472
+ ]
473
+ },
474
+ "at": {
475
+ "type": "string"
476
+ },
477
+ "skipped": {
478
+ "type": "array",
479
+ "items": {
480
+ "type": "object",
481
+ "properties": {
482
+ "profile": {
483
+ "type": "string"
484
+ },
485
+ "reason": {
486
+ "type": "string"
487
+ }
488
+ },
489
+ "required": [
490
+ "profile",
491
+ "reason"
492
+ ]
493
+ }
494
+ }
495
+ },
496
+ "required": [
497
+ "from",
498
+ "profile",
499
+ "errorClass",
500
+ "at"
501
+ ]
502
+ }
503
+ },
402
504
  "scheduleId": {
403
505
  "type": "string"
404
506
  },
@@ -1253,6 +1355,54 @@
1253
1355
  "type",
1254
1356
  "icon"
1255
1357
  ]
1358
+ },
1359
+ {
1360
+ "type": "object",
1361
+ "properties": {
1362
+ "type": {
1363
+ "type": "string",
1364
+ "enum": [
1365
+ "url"
1366
+ ]
1367
+ },
1368
+ "url": {
1369
+ "type": "string",
1370
+ "maxLength": 2048,
1371
+ "format": "uri"
1372
+ }
1373
+ },
1374
+ "required": [
1375
+ "type",
1376
+ "url"
1377
+ ]
1378
+ },
1379
+ {
1380
+ "type": "object",
1381
+ "properties": {
1382
+ "type": {
1383
+ "type": "string",
1384
+ "enum": [
1385
+ "agent-fs"
1386
+ ]
1387
+ },
1388
+ "path": {
1389
+ "type": "string",
1390
+ "minLength": 2,
1391
+ "maxLength": 1024
1392
+ },
1393
+ "orgId": {
1394
+ "type": "string",
1395
+ "minLength": 1
1396
+ },
1397
+ "driveId": {
1398
+ "type": "string",
1399
+ "minLength": 1
1400
+ }
1401
+ },
1402
+ "required": [
1403
+ "type",
1404
+ "path"
1405
+ ]
1256
1406
  }
1257
1407
  ]
1258
1408
  },
@@ -7593,6 +7743,54 @@
7593
7743
  "type",
7594
7744
  "icon"
7595
7745
  ]
7746
+ },
7747
+ {
7748
+ "type": "object",
7749
+ "properties": {
7750
+ "type": {
7751
+ "type": "string",
7752
+ "enum": [
7753
+ "url"
7754
+ ]
7755
+ },
7756
+ "url": {
7757
+ "type": "string",
7758
+ "maxLength": 2048,
7759
+ "format": "uri"
7760
+ }
7761
+ },
7762
+ "required": [
7763
+ "type",
7764
+ "url"
7765
+ ]
7766
+ },
7767
+ {
7768
+ "type": "object",
7769
+ "properties": {
7770
+ "type": {
7771
+ "type": "string",
7772
+ "enum": [
7773
+ "agent-fs"
7774
+ ]
7775
+ },
7776
+ "path": {
7777
+ "type": "string",
7778
+ "minLength": 2,
7779
+ "maxLength": 1024
7780
+ },
7781
+ "orgId": {
7782
+ "type": "string",
7783
+ "minLength": 1
7784
+ },
7785
+ "driveId": {
7786
+ "type": "string",
7787
+ "minLength": 1
7788
+ }
7789
+ },
7790
+ "required": [
7791
+ "type",
7792
+ "path"
7793
+ ]
7596
7794
  }
7597
7795
  ]
7598
7796
  },
@@ -12070,6 +12268,54 @@
12070
12268
  "icon"
12071
12269
  ]
12072
12270
  },
12271
+ {
12272
+ "type": "object",
12273
+ "properties": {
12274
+ "type": {
12275
+ "type": "string",
12276
+ "enum": [
12277
+ "url"
12278
+ ]
12279
+ },
12280
+ "url": {
12281
+ "type": "string",
12282
+ "maxLength": 2048,
12283
+ "format": "uri"
12284
+ }
12285
+ },
12286
+ "required": [
12287
+ "type",
12288
+ "url"
12289
+ ]
12290
+ },
12291
+ {
12292
+ "type": "object",
12293
+ "properties": {
12294
+ "type": {
12295
+ "type": "string",
12296
+ "enum": [
12297
+ "agent-fs"
12298
+ ]
12299
+ },
12300
+ "path": {
12301
+ "type": "string",
12302
+ "minLength": 2,
12303
+ "maxLength": 1024
12304
+ },
12305
+ "orgId": {
12306
+ "type": "string",
12307
+ "minLength": 1
12308
+ },
12309
+ "driveId": {
12310
+ "type": "string",
12311
+ "minLength": 1
12312
+ }
12313
+ },
12314
+ "required": [
12315
+ "type",
12316
+ "path"
12317
+ ]
12318
+ },
12073
12319
  {
12074
12320
  "type": "null"
12075
12321
  }
@@ -22818,7 +23064,7 @@
22818
23064
  "/api/fs/members/invite": {
22819
23065
  "post": {
22820
23066
  "summary": "Invite an external member into the agent-fs shared org",
22821
- "description": "The API server performs the invite with its own bootstrap credentials (which are API-only and never served over HTTP), provisioning the shared org/drive first when needed. Intended for the cloud control plane's Connect-to-Drive flow. An email with an agent-fs account is added directly (status added). An email without one gets a pending invite (status pending) with an acceptUrl when agent-fs returns one; agent-fs sends no email, so the caller must hand the link to the invitee. No keys are returned; the invitee obtains their own key via agent-fs registration.",
23067
+ "description": "The API server performs the invite with its own bootstrap credentials (which are API-only and never served over HTTP), provisioning the shared org/drive first when needed. Intended for the cloud control plane's Connect-to-Drive flow. An email already in the org gets the grant directly (status added). Any other email gets a pending invite (status pending) with its accept token, and an acceptUrl when agent-fs returns one; agent-fs sends no email, so the caller must hand the link to the invitee, or accept with the invitee's own key. No keys are returned; the invitee obtains their own key via agent-fs registration.",
22822
23068
  "tags": [
22823
23069
  "FS"
22824
23070
  ],
@@ -22876,7 +23122,7 @@
22876
23122
  "added",
22877
23123
  "pending"
22878
23124
  ],
22879
- "description": "already_member: no change. added: an existing agent-fs account joined the org. pending: the email has no account, so agent-fs created an invite the person must accept."
23125
+ "description": "already_member: no change. added: the email was already in the org and holds the role now. pending: agent-fs created an invite the person must accept (agent-fs >= 0.18.19 does this for every email not yet in the org, with or without an account)."
22880
23126
  },
22881
23127
  "inviteId": {
22882
23128
  "type": "string",
@@ -22889,6 +23135,10 @@
22889
23135
  "acceptUrl": {
22890
23136
  "type": "string",
22891
23137
  "description": "Link the invitee opens to accept (status pending). agent-fs sends no email, so hand it to the person. Absent when agent-fs has no app URL configured."
23138
+ },
23139
+ "token": {
23140
+ "type": "string",
23141
+ "description": "Accept token (status pending). Only the invited account can redeem it, with its own key: agent-fs POST /invites/{token}/accept."
22892
23142
  }
22893
23143
  },
22894
23144
  "required": [
@@ -28380,6 +28630,12 @@
28380
28630
  "minItems": 1
28381
28631
  }
28382
28632
  },
28633
+ "fallbacks": {
28634
+ "type": "array",
28635
+ "items": {
28636
+ "type": "string"
28637
+ }
28638
+ },
28383
28639
  "createdAt": {
28384
28640
  "type": "string"
28385
28641
  },
@@ -28397,6 +28653,7 @@
28397
28653
  "description",
28398
28654
  "seededFrom",
28399
28655
  "credentials",
28656
+ "fallbacks",
28400
28657
  "createdAt",
28401
28658
  "lastUpdatedAt"
28402
28659
  ]
@@ -28414,7 +28671,7 @@
28414
28671
  },
28415
28672
  "post": {
28416
28673
  "summary": "Create a model profile",
28417
- "description": "A profile runs on one harness. `model` must run on that harness and be in the model catalog unless `allowCustomModel` is true (a gateway id, a fresh launch); a `latest:` alias is accepted and resolves at claim. `effort` must be a level the harness and model support. `credentials` pins which pooled keys the profile uses: per credential var of the harness, the last 5 characters of each allowed key (`CODEX_OAUTH` is not supported). Operator only (the shared API key).",
28674
+ "description": "A profile runs on one harness. `model` must run on that harness and be in the model catalog unless `allowCustomModel` is true (a gateway id, a fresh launch); a `latest:` alias is accepted and resolves at claim. `effort` must be a level the harness and model support. `credentials` pins which pooled keys the profile uses: per credential var of the harness, the last 5 characters of each allowed key (`CODEX_OAUTH` is not supported). `fallbacks` lists profiles on the same harness, in order, that a task on this profile hops to when a provider error (rate limit, seat, overload, auth, empty key pool) ends it; no repeats, no self, no cycle. Operator only (the shared API key).",
28418
28675
  "tags": [
28419
28676
  "Models"
28420
28677
  ],
@@ -28494,6 +28751,14 @@
28494
28751
  },
28495
28752
  "minItems": 1
28496
28753
  }
28754
+ },
28755
+ "fallbacks": {
28756
+ "type": "array",
28757
+ "items": {
28758
+ "type": "string",
28759
+ "pattern": "^[a-z0-9][a-z0-9._-]{0,99}$"
28760
+ },
28761
+ "maxItems": 10
28497
28762
  }
28498
28763
  },
28499
28764
  "required": [
@@ -28584,6 +28849,12 @@
28584
28849
  "minItems": 1
28585
28850
  }
28586
28851
  },
28852
+ "fallbacks": {
28853
+ "type": "array",
28854
+ "items": {
28855
+ "type": "string"
28856
+ }
28857
+ },
28587
28858
  "createdAt": {
28588
28859
  "type": "string"
28589
28860
  },
@@ -28601,6 +28872,7 @@
28601
28872
  "description",
28602
28873
  "seededFrom",
28603
28874
  "credentials",
28875
+ "fallbacks",
28604
28876
  "createdAt",
28605
28877
  "lastUpdatedAt"
28606
28878
  ]
@@ -28741,6 +29013,12 @@
28741
29013
  "minItems": 1
28742
29014
  }
28743
29015
  },
29016
+ "fallbacks": {
29017
+ "type": "array",
29018
+ "items": {
29019
+ "type": "string"
29020
+ }
29021
+ },
28744
29022
  "createdAt": {
28745
29023
  "type": "string"
28746
29024
  },
@@ -28758,6 +29036,7 @@
28758
29036
  "description",
28759
29037
  "seededFrom",
28760
29038
  "credentials",
29039
+ "fallbacks",
28761
29040
  "createdAt",
28762
29041
  "lastUpdatedAt"
28763
29042
  ]
@@ -28779,7 +29058,7 @@
28779
29058
  },
28780
29059
  "patch": {
28781
29060
  "summary": "Update a model profile",
28782
- "description": "Changes the model, effort, custom-model flag, description or credential allowlist; the name and harness are fixed. Omit a field to keep it; `effort: null` and `credentials: null` clear it. Applies to tasks claimed after the change. Operator only (the shared API key).",
29061
+ "description": "Changes the model, effort, custom-model flag, description, credential allowlist or fallbacks; the name and harness are fixed. Omit a field to keep it; `effort: null` and `credentials: null` clear it, and `fallbacks: []` empties the list. Applies to tasks claimed after the change. Operator only (the shared API key).",
28783
29062
  "tags": [
28784
29063
  "Models"
28785
29064
  ],
@@ -28847,6 +29126,14 @@
28847
29126
  },
28848
29127
  "minItems": 1
28849
29128
  }
29129
+ },
29130
+ "fallbacks": {
29131
+ "type": "array",
29132
+ "items": {
29133
+ "type": "string",
29134
+ "pattern": "^[a-z0-9][a-z0-9._-]{0,99}$"
29135
+ },
29136
+ "maxItems": 10
28850
29137
  }
28851
29138
  }
28852
29139
  }
@@ -28932,6 +29219,12 @@
28932
29219
  "minItems": 1
28933
29220
  }
28934
29221
  },
29222
+ "fallbacks": {
29223
+ "type": "array",
29224
+ "items": {
29225
+ "type": "string"
29226
+ }
29227
+ },
28935
29228
  "createdAt": {
28936
29229
  "type": "string"
28937
29230
  },
@@ -28949,6 +29242,7 @@
28949
29242
  "description",
28950
29243
  "seededFrom",
28951
29244
  "credentials",
29245
+ "fallbacks",
28952
29246
  "createdAt",
28953
29247
  "lastUpdatedAt"
28954
29248
  ]
@@ -28990,7 +29284,7 @@
28990
29284
  },
28991
29285
  "delete": {
28992
29286
  "summary": "Delete a model profile",
28993
- "description": "Refused (409) for a shipped `<harness>-<tier>` seed (edit it instead; it would come back at the next boot), and while an agent has the profile as its default, a schedule names it, or a task holds it (unfinished, or superseded and still owed its resume). Operator only (the shared API key).",
29287
+ "description": "Refused (409) for a shipped `<harness>-<tier>` seed (edit it instead; it would come back at the next boot), and while an agent has the profile as its default, a schedule names it, another profile lists it as a fallback, or a task holds it (unfinished, or superseded and still owed its resume). Operator only (the shared API key).",
28994
29288
  "tags": [
28995
29289
  "Models"
28996
29290
  ],
@@ -34833,6 +35127,11 @@
34833
35127
  "dir": {
34834
35128
  "type": "string"
34835
35129
  },
35130
+ "vcsRepo": {
35131
+ "type": "string",
35132
+ "minLength": 1,
35133
+ "description": "A registered repo (`swarm_repos`), as `owner/repo` or its URL. The worker clones or refreshes it and loads its `CLAUDE.md`. Stored as the registered repo's URL; an unregistered or ambiguous repo is a 400."
35134
+ },
34836
35135
  "parentTaskId": {
34837
35136
  "type": "string"
34838
35137
  },
@@ -34927,7 +35226,7 @@
34927
35226
  }
34928
35227
  },
34929
35228
  "400": {
34930
- "description": "Validation error, an unknown `model` (set `allowCustomModel` to store a custom id), or agentId/offeredTo targets an extension identity",
35229
+ "description": "Validation error, an unknown `model` (set `allowCustomModel` to store a custom id), a `vcsRepo` that is not exactly one registered repo, or agentId/offeredTo targets an extension identity",
34931
35230
  "content": {
34932
35231
  "application/json": {
34933
35232
  "schema": {
@@ -36623,6 +36922,87 @@
36623
36922
  "name"
36624
36923
  ]
36625
36924
  },
36925
+ "threadParticipants": {
36926
+ "type": "object",
36927
+ "properties": {
36928
+ "total": {
36929
+ "type": "integer"
36930
+ },
36931
+ "more": {
36932
+ "type": "integer"
36933
+ },
36934
+ "people": {
36935
+ "type": "array",
36936
+ "items": {
36937
+ "type": "object",
36938
+ "properties": {
36939
+ "label": {
36940
+ "type": "string"
36941
+ },
36942
+ "trust": {
36943
+ "type": "string",
36944
+ "enum": [
36945
+ "internal",
36946
+ "external",
36947
+ "unknown"
36948
+ ]
36949
+ },
36950
+ "starter": {
36951
+ "type": "boolean"
36952
+ },
36953
+ "newest": {
36954
+ "type": "boolean"
36955
+ },
36956
+ "asked": {
36957
+ "type": "boolean"
36958
+ },
36959
+ "language": {
36960
+ "type": "string"
36961
+ },
36962
+ "verbosity": {
36963
+ "type": "string"
36964
+ }
36965
+ },
36966
+ "required": [
36967
+ "label",
36968
+ "trust"
36969
+ ]
36970
+ }
36971
+ },
36972
+ "starterProfile": {
36973
+ "type": "object",
36974
+ "properties": {
36975
+ "id": {
36976
+ "type": "string"
36977
+ },
36978
+ "name": {
36979
+ "type": "string",
36980
+ "minLength": 1
36981
+ },
36982
+ "email": {
36983
+ "type": "string"
36984
+ },
36985
+ "role": {
36986
+ "type": "string"
36987
+ },
36988
+ "notes": {
36989
+ "type": "string"
36990
+ },
36991
+ "comms": {
36992
+ "$ref": "#/components/schemas/UserCommsPrefs"
36993
+ }
36994
+ },
36995
+ "required": [
36996
+ "name"
36997
+ ]
36998
+ }
36999
+ },
37000
+ "required": [
37001
+ "total",
37002
+ "more",
37003
+ "people"
37004
+ ]
37005
+ },
36626
37006
  "credentialAllowlist": {
36627
37007
  "type": "object",
36628
37008
  "additionalProperties": {
@@ -36817,7 +37197,7 @@
36817
37197
  "/api/tasks/{id}/supersede": {
36818
37198
  "post": {
36819
37199
  "summary": "Supersede an in-progress task (terminate + spawn resume follow-up)",
36820
- "description": "Marks the original task `superseded` (terminal) and creates a fresh `taskType=\"resume\"` follow-up so a worker can pick up the work in a new provider session. Workflow-step tasks (those with `workflowRunStepId`) are carved out: the original is marked `failed` with reason `superseded_workflow_task` and no follow-up is created — the workflow engine's retry/failure policy applies.",
37200
+ "description": "Marks the original task `superseded` (terminal) and creates a fresh `taskType=\"resume\"` follow-up so a worker can pick up the work in a new provider session. Workflow-step tasks (those with `workflowRunStepId`) are carved out: the original is marked `failed` with reason `superseded_workflow_task` and no follow-up is created — the workflow engine's retry/failure policy applies. With `reason: provider_fallback` (and its `errorClass`), the resume runs on the same agent with the next fallback profile that passes the profile check; when none is left, or the task is a workflow step, nothing changes and `kind: noFallback` tells the worker to fail the task itself, led by `failureReason` when set.",
36821
37201
  "tags": [
36822
37202
  "Tasks"
36823
37203
  ],
@@ -36848,7 +37228,21 @@
36848
37228
  "graceful_shutdown",
36849
37229
  "context_limits",
36850
37230
  "manual_supersede",
36851
- "crash_recovery"
37231
+ "crash_recovery",
37232
+ "provider_fallback"
37233
+ ]
37234
+ },
37235
+ "errorClass": {
37236
+ "type": "string",
37237
+ "enum": [
37238
+ "rate_limit",
37239
+ "model_window",
37240
+ "seat",
37241
+ "credits",
37242
+ "overloaded",
37243
+ "server_error",
37244
+ "auth",
37245
+ "pool_empty"
36852
37246
  ]
36853
37247
  }
36854
37248
  },
@@ -36878,7 +37272,8 @@
36878
37272
  "enum": [
36879
37273
  "alreadyFinished",
36880
37274
  "workflow-failed",
36881
- "resumed"
37275
+ "resumed",
37276
+ "noFallback"
36882
37277
  ]
36883
37278
  },
36884
37279
  "task": {
@@ -36914,6 +37309,12 @@
36914
37309
  "superseded",
36915
37310
  "skipped"
36916
37311
  ]
37312
+ },
37313
+ "failureReason": {
37314
+ "type": [
37315
+ "string",
37316
+ "null"
37317
+ ]
36917
37318
  }
36918
37319
  },
36919
37320
  "required": [
@@ -39396,6 +39797,87 @@
39396
39797
  "required": [
39397
39798
  "name"
39398
39799
  ]
39800
+ },
39801
+ "threadParticipants": {
39802
+ "type": "object",
39803
+ "properties": {
39804
+ "total": {
39805
+ "type": "integer"
39806
+ },
39807
+ "more": {
39808
+ "type": "integer"
39809
+ },
39810
+ "people": {
39811
+ "type": "array",
39812
+ "items": {
39813
+ "type": "object",
39814
+ "properties": {
39815
+ "label": {
39816
+ "type": "string"
39817
+ },
39818
+ "trust": {
39819
+ "type": "string",
39820
+ "enum": [
39821
+ "internal",
39822
+ "external",
39823
+ "unknown"
39824
+ ]
39825
+ },
39826
+ "starter": {
39827
+ "type": "boolean"
39828
+ },
39829
+ "newest": {
39830
+ "type": "boolean"
39831
+ },
39832
+ "asked": {
39833
+ "type": "boolean"
39834
+ },
39835
+ "language": {
39836
+ "type": "string"
39837
+ },
39838
+ "verbosity": {
39839
+ "type": "string"
39840
+ }
39841
+ },
39842
+ "required": [
39843
+ "label",
39844
+ "trust"
39845
+ ]
39846
+ }
39847
+ },
39848
+ "starterProfile": {
39849
+ "type": "object",
39850
+ "properties": {
39851
+ "id": {
39852
+ "type": "string"
39853
+ },
39854
+ "name": {
39855
+ "type": "string",
39856
+ "minLength": 1
39857
+ },
39858
+ "email": {
39859
+ "type": "string"
39860
+ },
39861
+ "role": {
39862
+ "type": "string"
39863
+ },
39864
+ "notes": {
39865
+ "type": "string"
39866
+ },
39867
+ "comms": {
39868
+ "$ref": "#/components/schemas/UserCommsPrefs"
39869
+ }
39870
+ },
39871
+ "required": [
39872
+ "name"
39873
+ ]
39874
+ }
39875
+ },
39876
+ "required": [
39877
+ "total",
39878
+ "more",
39879
+ "people"
39880
+ ]
39399
39881
  }
39400
39882
  },
39401
39883
  "required": [
@@ -39498,6 +39980,87 @@
39498
39980
  "required": [
39499
39981
  "name"
39500
39982
  ]
39983
+ },
39984
+ "threadParticipants": {
39985
+ "type": "object",
39986
+ "properties": {
39987
+ "total": {
39988
+ "type": "integer"
39989
+ },
39990
+ "more": {
39991
+ "type": "integer"
39992
+ },
39993
+ "people": {
39994
+ "type": "array",
39995
+ "items": {
39996
+ "type": "object",
39997
+ "properties": {
39998
+ "label": {
39999
+ "type": "string"
40000
+ },
40001
+ "trust": {
40002
+ "type": "string",
40003
+ "enum": [
40004
+ "internal",
40005
+ "external",
40006
+ "unknown"
40007
+ ]
40008
+ },
40009
+ "starter": {
40010
+ "type": "boolean"
40011
+ },
40012
+ "newest": {
40013
+ "type": "boolean"
40014
+ },
40015
+ "asked": {
40016
+ "type": "boolean"
40017
+ },
40018
+ "language": {
40019
+ "type": "string"
40020
+ },
40021
+ "verbosity": {
40022
+ "type": "string"
40023
+ }
40024
+ },
40025
+ "required": [
40026
+ "label",
40027
+ "trust"
40028
+ ]
40029
+ }
40030
+ },
40031
+ "starterProfile": {
40032
+ "type": "object",
40033
+ "properties": {
40034
+ "id": {
40035
+ "type": "string"
40036
+ },
40037
+ "name": {
40038
+ "type": "string",
40039
+ "minLength": 1
40040
+ },
40041
+ "email": {
40042
+ "type": "string"
40043
+ },
40044
+ "role": {
40045
+ "type": "string"
40046
+ },
40047
+ "notes": {
40048
+ "type": "string"
40049
+ },
40050
+ "comms": {
40051
+ "$ref": "#/components/schemas/UserCommsPrefs"
40052
+ }
40053
+ },
40054
+ "required": [
40055
+ "name"
40056
+ ]
40057
+ }
40058
+ },
40059
+ "required": [
40060
+ "total",
40061
+ "more",
40062
+ "people"
40063
+ ]
39501
40064
  }
39502
40065
  },
39503
40066
  "required": [
@@ -51161,111 +51724,12 @@
51161
51724
  }
51162
51725
  }
51163
51726
  },
51164
- "/api/sessions/tokens": {
51165
- "post": {
51166
- "summary": "Mint an ephemeral task or runtime token",
51167
- "description": "Operators can mint task or runtime tokens. Runtime and agent tokens can mint task tokens for their own assigned tasks. A child token never outlives its parent and is revoked with it.",
51168
- "tags": [
51169
- "Sessions"
51170
- ],
51171
- "security": [
51172
- {
51173
- "bearerAuth": []
51174
- }
51175
- ],
51176
- "requestBody": {
51177
- "content": {
51178
- "application/json": {
51179
- "schema": {
51180
- "type": "object",
51181
- "properties": {
51182
- "agentId": {
51183
- "type": "string",
51184
- "minLength": 1
51185
- },
51186
- "taskId": {
51187
- "type": "string",
51188
- "minLength": 1
51189
- },
51190
- "runtimeId": {
51191
- "type": "string",
51192
- "minLength": 1
51193
- },
51194
- "ttlMs": {
51195
- "type": "integer",
51196
- "exclusiveMinimum": 0,
51197
- "maximum": 604800000
51198
- }
51199
- },
51200
- "required": [
51201
- "agentId"
51202
- ]
51203
- }
51204
- }
51205
- }
51206
- },
51207
- "responses": {
51208
- "200": {
51209
- "description": "Minted token plaintext (returned once) and its stable token ID",
51210
- "content": {
51211
- "application/json": {
51212
- "schema": {
51213
- "type": "object",
51214
- "properties": {
51215
- "tokenId": {
51216
- "type": "string"
51217
- },
51218
- "plaintext": {
51219
- "type": "string"
51220
- }
51221
- },
51222
- "required": [
51223
- "tokenId",
51224
- "plaintext"
51225
- ]
51226
- }
51227
- }
51228
- }
51229
- },
51230
- "400": {
51231
- "description": "Validation error",
51232
- "content": {
51233
- "application/json": {
51234
- "schema": {
51235
- "$ref": "#/components/schemas/ErrorResponse"
51236
- }
51237
- }
51238
- }
51239
- },
51240
- "401": {
51241
- "description": "Unauthorized",
51242
- "content": {
51243
- "application/json": {
51244
- "schema": {
51245
- "$ref": "#/components/schemas/ErrorResponse"
51246
- }
51247
- }
51248
- }
51249
- },
51250
- "403": {
51251
- "description": "Token cannot mint for this agent or task",
51252
- "content": {
51253
- "application/json": {
51254
- "schema": {
51255
- "$ref": "#/components/schemas/ErrorResponse"
51256
- }
51257
- }
51258
- }
51259
- }
51260
- }
51261
- }
51262
- },
51263
- "/api/sessions/tokens/{tokenId}": {
51264
- "delete": {
51265
- "summary": "Revoke an ephemeral session token",
51266
- "description": "Operators can revoke any ephemeral token. Agent tokens, and runtime tokens when runtime pools are enabled, can revoke their own child task tokens. Repeated revocation has no effect.",
51727
+ "/api/savings/jobs": {
51728
+ "get": {
51729
+ "summary": "Estimated automation savings per workflow or script",
51730
+ "description": "What the workflows' or scripts' runs in the window would have cost as agent tasks, minus what they cost, read from the hourly savings rollup. With `workflowId` and `components=true`, also returns the workflow's components (child workflow runs, nested script runs and tasks its runs caused, recursively) priced as on their own rows, and `withComponents`, own runs plus those; lists and schedule reads reject `components=true`. `measuredUsd` is the measured spend and `estimatedLlmUsd` the LLM spend estimated where none was recorded; `actualUsd` is their sum scaled to the substituted share of runs, the estimate the saving subtracts. Modelled at the chosen tier, with an 80% range (p10 to p90). Pass `workflowId` for one workflow, `scriptName` for one script, or `kind=workflow` / `kind=script` for every workflow or script with runs. Scheduled scripts are priced as standalone agent tasks; other scripts as the extra turns they add to the calling agent's session. Scripts record no LLM spend, so their spend fields are 0. Pass `scheduleId` for one schedule, or `kind=schedule` for every schedule: a workflow or script target returns the target's row (`scope: target-job`, with `scheduleId`), because runs carry no schedule link, so schedules of one target show the same row, and `total` is null for schedule reads; an agent-task target returns a measured row (`basis` measured) with the recorded cost of its tasks and `savingUsd: null`. A disabled schedule is priced from its target's runs and flagged by `scheduleEnabled`. `valid` is false until the rollup has computed every day of the window, and when there were no runs.",
51267
51731
  "tags": [
51268
- "Sessions"
51732
+ "Savings"
51269
51733
  ],
51270
51734
  "security": [
51271
51735
  {
@@ -51275,270 +51739,2273 @@
51275
51739
  "parameters": [
51276
51740
  {
51277
51741
  "schema": {
51278
- "type": "string"
51742
+ "type": "string",
51743
+ "minLength": 1
51279
51744
  },
51280
- "required": true,
51281
- "name": "tokenId",
51282
- "in": "path"
51283
- }
51284
- ],
51285
- "responses": {
51286
- "204": {
51287
- "description": "Token revoked (or was already revoked)"
51288
- },
51289
- "401": {
51290
- "description": "Unauthorized",
51291
- "content": {
51292
- "application/json": {
51293
- "schema": {
51294
- "$ref": "#/components/schemas/ErrorResponse"
51295
- }
51296
- }
51297
- }
51745
+ "required": false,
51746
+ "name": "workflowId",
51747
+ "in": "query"
51298
51748
  },
51299
- "403": {
51300
- "description": "Token cannot revoke this child",
51301
- "content": {
51302
- "application/json": {
51303
- "schema": {
51304
- "$ref": "#/components/schemas/ErrorResponse"
51305
- }
51306
- }
51307
- }
51308
- }
51309
- }
51310
- }
51311
- },
51312
- "/api/agents/{id}/token": {
51313
- "post": {
51314
- "operationId": "agents_mintWorkerToken",
51315
- "summary": "Mint an agent-bound worker token",
51316
- "description": "Returns the token once. A worker runs on it in place of the swarm API key and acts only as this agent. Creates the agent when it does not exist and `name` is given. Fails with 409 when the agent already holds an active token.",
51317
- "tags": [
51318
- "Sessions"
51319
- ],
51320
- "security": [
51321
- {
51322
- "bearerAuth": []
51323
- }
51324
- ],
51325
- "parameters": [
51326
51749
  {
51327
51750
  "schema": {
51328
51751
  "type": "string",
51329
51752
  "minLength": 1
51330
51753
  },
51331
- "required": true,
51332
- "name": "id",
51333
- "in": "path"
51334
- }
51335
- ],
51336
- "requestBody": {
51337
- "content": {
51338
- "application/json": {
51339
- "schema": {
51340
- "type": "object",
51341
- "properties": {
51342
- "name": {
51343
- "type": "string",
51344
- "minLength": 1
51345
- },
51346
- "ttlMs": {
51347
- "type": "integer",
51348
- "exclusiveMinimum": 0,
51349
- "description": "Token lifetime in ms. Omit for the default (no expiry)."
51350
- }
51351
- },
51352
- "additionalProperties": false
51353
- }
51354
- }
51355
- }
51356
- },
51357
- "responses": {
51358
- "200": {
51359
- "description": "Minted worker token",
51360
- "content": {
51361
- "application/json": {
51362
- "schema": {
51363
- "type": "object",
51364
- "properties": {
51365
- "agentId": {
51366
- "type": "string"
51367
- },
51368
- "tokenId": {
51369
- "type": "string"
51370
- },
51371
- "plaintext": {
51372
- "type": "string"
51373
- },
51374
- "expiresAt": {
51375
- "type": [
51376
- "string",
51377
- "null"
51378
- ],
51379
- "description": "null when the token does not expire"
51380
- },
51381
- "agentCreated": {
51382
- "type": "boolean"
51383
- }
51384
- },
51385
- "required": [
51386
- "agentId",
51387
- "tokenId",
51388
- "plaintext",
51389
- "expiresAt",
51390
- "agentCreated"
51391
- ]
51392
- }
51393
- }
51394
- }
51395
- },
51396
- "403": {
51397
- "description": "Operator or user credentials required",
51398
- "content": {
51399
- "application/json": {
51400
- "schema": {
51401
- "$ref": "#/components/schemas/ErrorResponse"
51402
- }
51403
- }
51404
- }
51754
+ "required": false,
51755
+ "name": "scriptName",
51756
+ "in": "query"
51405
51757
  },
51406
- "404": {
51407
- "description": "Agent not found and no name given",
51408
- "content": {
51409
- "application/json": {
51410
- "schema": {
51411
- "$ref": "#/components/schemas/ErrorResponse"
51412
- }
51413
- }
51414
- }
51758
+ {
51759
+ "schema": {
51760
+ "type": "string",
51761
+ "minLength": 1
51762
+ },
51763
+ "required": false,
51764
+ "name": "scheduleId",
51765
+ "in": "query"
51415
51766
  },
51416
- "409": {
51417
- "description": "Agent already holds an active token",
51418
- "content": {
51419
- "application/json": {
51420
- "schema": {
51421
- "$ref": "#/components/schemas/ErrorResponse"
51422
- }
51423
- }
51424
- }
51425
- }
51426
- }
51427
- },
51428
- "delete": {
51429
- "operationId": "agents_revokeWorkerToken",
51430
- "summary": "Revoke an agent-bound worker token",
51431
- "description": "Revokes every active worker token of the agent and the task tokens they minted. Open realtime connections on them close.",
51432
- "tags": [
51433
- "Sessions"
51434
- ],
51435
- "security": [
51436
51767
  {
51437
- "bearerAuth": []
51438
- }
51439
- ],
51440
- "parameters": [
51768
+ "schema": {
51769
+ "type": "string",
51770
+ "enum": [
51771
+ "workflow",
51772
+ "script",
51773
+ "schedule"
51774
+ ]
51775
+ },
51776
+ "required": false,
51777
+ "name": "kind",
51778
+ "in": "query"
51779
+ },
51441
51780
  {
51442
51781
  "schema": {
51443
51782
  "type": "string",
51444
- "minLength": 1
51783
+ "enum": [
51784
+ "true",
51785
+ "false"
51786
+ ],
51787
+ "default": "false"
51445
51788
  },
51446
- "required": true,
51447
- "name": "id",
51448
- "in": "path"
51449
- }
51450
- ],
51451
- "responses": {
51452
- "200": {
51453
- "description": "Number of worker tokens revoked (0 when none was active)",
51454
- "content": {
51455
- "application/json": {
51456
- "schema": {
51457
- "type": "object",
51458
- "properties": {
51459
- "revoked": {
51460
- "type": "integer"
51461
- }
51462
- },
51463
- "required": [
51464
- "revoked"
51465
- ]
51466
- }
51467
- }
51468
- }
51789
+ "required": false,
51790
+ "name": "components",
51791
+ "in": "query"
51469
51792
  },
51470
- "403": {
51471
- "description": "Operator or user credentials required",
51472
- "content": {
51473
- "application/json": {
51474
- "schema": {
51475
- "$ref": "#/components/schemas/ErrorResponse"
51476
- }
51477
- }
51478
- }
51479
- }
51480
- }
51481
- }
51482
- },
51483
- "/api/agents/{id}/token/rotate": {
51484
- "post": {
51485
- "operationId": "agents_rotateWorkerToken",
51486
- "summary": "Rotate an agent-bound worker token",
51487
- "description": "Returns a new token once. The previous token keeps working for `graceSec` (default 300), then expires. Use revoke for a token that must stop now.",
51488
- "tags": [
51489
- "Sessions"
51490
- ],
51491
- "security": [
51492
51793
  {
51493
- "bearerAuth": []
51494
- }
51495
- ],
51496
- "parameters": [
51794
+ "schema": {
51795
+ "type": "string",
51796
+ "enum": [
51797
+ "7",
51798
+ "30",
51799
+ "90"
51800
+ ],
51801
+ "default": "30"
51802
+ },
51803
+ "required": false,
51804
+ "name": "days",
51805
+ "in": "query"
51806
+ },
51497
51807
  {
51498
51808
  "schema": {
51499
51809
  "type": "string",
51500
- "minLength": 1
51810
+ "enum": [
51811
+ "smol",
51812
+ "regular",
51813
+ "smart",
51814
+ "ultra"
51815
+ ],
51816
+ "default": "smart"
51501
51817
  },
51502
- "required": true,
51503
- "name": "id",
51504
- "in": "path"
51818
+ "required": false,
51819
+ "name": "tier",
51820
+ "in": "query"
51505
51821
  }
51506
51822
  ],
51507
- "requestBody": {
51508
- "content": {
51509
- "application/json": {
51510
- "schema": {
51511
- "type": "object",
51512
- "properties": {
51513
- "graceSec": {
51514
- "type": "integer",
51515
- "minimum": 0,
51516
- "maximum": 86400
51517
- },
51518
- "ttlMs": {
51519
- "type": "integer",
51520
- "exclusiveMinimum": 0,
51521
- "description": "Token lifetime in ms. Omit for the default (no expiry)."
51522
- }
51523
- },
51524
- "additionalProperties": false
51525
- }
51526
- }
51527
- }
51528
- },
51529
51823
  "responses": {
51530
51824
  "200": {
51531
- "description": "New worker token",
51825
+ "description": "Savings rows",
51532
51826
  "content": {
51533
51827
  "application/json": {
51534
51828
  "schema": {
51535
51829
  "type": "object",
51536
51830
  "properties": {
51537
- "agentId": {
51538
- "type": "string"
51539
- },
51540
- "tokenId": {
51541
- "type": "string"
51831
+ "window": {
51832
+ "type": "object",
51833
+ "properties": {
51834
+ "start": {
51835
+ "type": "string"
51836
+ },
51837
+ "end": {
51838
+ "type": "string"
51839
+ },
51840
+ "days": {
51841
+ "type": "integer"
51842
+ }
51843
+ },
51844
+ "required": [
51845
+ "start",
51846
+ "end",
51847
+ "days"
51848
+ ]
51849
+ },
51850
+ "tier": {
51851
+ "type": "string",
51852
+ "enum": [
51853
+ "smol",
51854
+ "regular",
51855
+ "smart",
51856
+ "ultra"
51857
+ ]
51858
+ },
51859
+ "calibrationModel": {
51860
+ "type": "string"
51861
+ },
51862
+ "calibratedAt": {
51863
+ "type": "string"
51864
+ },
51865
+ "calibrationSource": {
51866
+ "type": "string",
51867
+ "enum": [
51868
+ "shipped",
51869
+ "deployment"
51870
+ ]
51871
+ },
51872
+ "computedAt": {
51873
+ "type": [
51874
+ "string",
51875
+ "null"
51876
+ ]
51877
+ },
51878
+ "valid": {
51879
+ "type": "boolean"
51880
+ },
51881
+ "reason": {
51882
+ "type": [
51883
+ "string",
51884
+ "null"
51885
+ ],
51886
+ "enum": [
51887
+ "not-computed",
51888
+ "no-runs",
51889
+ "target-missing",
51890
+ null
51891
+ ]
51892
+ },
51893
+ "boundaryEstimated": {
51894
+ "type": "boolean",
51895
+ "description": "The window is rolling, so its first UTC day is partial and its runs are scanned live. True when that scan could not run (too many runs, or a busy database) and the day's bucket was scaled to the part inside the window instead."
51896
+ },
51897
+ "rows": {
51898
+ "type": "array",
51899
+ "items": {
51900
+ "anyOf": [
51901
+ {
51902
+ "type": "object",
51903
+ "properties": {
51904
+ "kind": {
51905
+ "type": "string",
51906
+ "enum": [
51907
+ "workflow",
51908
+ "script-scheduled",
51909
+ "script-agent-invoked"
51910
+ ]
51911
+ },
51912
+ "workflowId": {
51913
+ "type": "string"
51914
+ },
51915
+ "scriptName": {
51916
+ "type": "string"
51917
+ },
51918
+ "name": {
51919
+ "type": "string"
51920
+ },
51921
+ "basis": {
51922
+ "type": "string",
51923
+ "enum": [
51924
+ "modelled"
51925
+ ]
51926
+ },
51927
+ "scheduleId": {
51928
+ "type": "string"
51929
+ },
51930
+ "scheduleName": {
51931
+ "type": "string"
51932
+ },
51933
+ "scheduleEnabled": {
51934
+ "type": "boolean"
51935
+ },
51936
+ "scope": {
51937
+ "type": "string",
51938
+ "enum": [
51939
+ "target-job"
51940
+ ]
51941
+ },
51942
+ "enabledOnlyRule": {
51943
+ "type": "boolean"
51944
+ },
51945
+ "runs": {
51946
+ "type": "integer"
51947
+ },
51948
+ "substitutedRuns": {
51949
+ "type": "integer"
51950
+ },
51951
+ "effectRuns": {
51952
+ "type": "integer"
51953
+ },
51954
+ "enabledOnlyRuns": {
51955
+ "type": "integer"
51956
+ },
51957
+ "capApplied": {
51958
+ "type": "boolean"
51959
+ },
51960
+ "opsPerRun": {
51961
+ "type": "number"
51962
+ },
51963
+ "measuredUsd": {
51964
+ "type": "number",
51965
+ "description": "Measured spend of every run in the window: agent tasks, their reviews, recorded LLM cost."
51966
+ },
51967
+ "estimatedLlmUsd": {
51968
+ "type": "number",
51969
+ "description": "LLM spend estimated from tokens and output size, not measured. 0 when the runs recorded their LLM cost."
51970
+ },
51971
+ "actualUsd": {
51972
+ "type": "number",
51973
+ "description": "Scaled estimate, not a measurement: `measuredUsd + estimatedLlmUsd` times `substitutedRuns / runs`. The saving subtracts this."
51974
+ },
51975
+ "agentOnlyUsd": {
51976
+ "type": "object",
51977
+ "properties": {
51978
+ "p10": {
51979
+ "type": "number"
51980
+ },
51981
+ "p50": {
51982
+ "type": "number"
51983
+ },
51984
+ "p90": {
51985
+ "type": "number"
51986
+ }
51987
+ },
51988
+ "required": [
51989
+ "p10",
51990
+ "p50",
51991
+ "p90"
51992
+ ]
51993
+ },
51994
+ "savingUsd": {
51995
+ "type": "object",
51996
+ "properties": {
51997
+ "p10": {
51998
+ "type": "number"
51999
+ },
52000
+ "p50": {
52001
+ "type": "number"
52002
+ },
52003
+ "p90": {
52004
+ "type": "number"
52005
+ }
52006
+ },
52007
+ "required": [
52008
+ "p10",
52009
+ "p50",
52010
+ "p90"
52011
+ ]
52012
+ },
52013
+ "actualHours": {
52014
+ "type": "number",
52015
+ "description": "Scaled estimate: measured hours times `substitutedRuns / runs`. Always 0 for scripts, which keep no agent active."
52016
+ },
52017
+ "agentOnlyHours": {
52018
+ "type": "object",
52019
+ "properties": {
52020
+ "p10": {
52021
+ "type": "number"
52022
+ },
52023
+ "p50": {
52024
+ "type": "number"
52025
+ },
52026
+ "p90": {
52027
+ "type": "number"
52028
+ }
52029
+ },
52030
+ "required": [
52031
+ "p10",
52032
+ "p50",
52033
+ "p90"
52034
+ ]
52035
+ },
52036
+ "hoursSaved": {
52037
+ "type": "object",
52038
+ "properties": {
52039
+ "p10": {
52040
+ "type": "number"
52041
+ },
52042
+ "p50": {
52043
+ "type": "number"
52044
+ },
52045
+ "p90": {
52046
+ "type": "number"
52047
+ }
52048
+ },
52049
+ "required": [
52050
+ "p10",
52051
+ "p50",
52052
+ "p90"
52053
+ ]
52054
+ },
52055
+ "agentOnlyUsdPerRun": {
52056
+ "type": "number"
52057
+ }
52058
+ },
52059
+ "required": [
52060
+ "kind",
52061
+ "name",
52062
+ "basis",
52063
+ "enabledOnlyRule",
52064
+ "runs",
52065
+ "substitutedRuns",
52066
+ "effectRuns",
52067
+ "enabledOnlyRuns",
52068
+ "capApplied",
52069
+ "opsPerRun",
52070
+ "measuredUsd",
52071
+ "estimatedLlmUsd",
52072
+ "actualUsd",
52073
+ "agentOnlyUsd",
52074
+ "savingUsd",
52075
+ "actualHours",
52076
+ "agentOnlyHours",
52077
+ "hoursSaved",
52078
+ "agentOnlyUsdPerRun"
52079
+ ]
52080
+ },
52081
+ {
52082
+ "type": "object",
52083
+ "properties": {
52084
+ "kind": {
52085
+ "type": "string",
52086
+ "enum": [
52087
+ "agent-task-schedule"
52088
+ ]
52089
+ },
52090
+ "scheduleId": {
52091
+ "type": "string"
52092
+ },
52093
+ "scheduleName": {
52094
+ "type": "string"
52095
+ },
52096
+ "scheduleEnabled": {
52097
+ "type": "boolean"
52098
+ },
52099
+ "name": {
52100
+ "type": "string"
52101
+ },
52102
+ "basis": {
52103
+ "type": "string",
52104
+ "enum": [
52105
+ "measured"
52106
+ ]
52107
+ },
52108
+ "runs": {
52109
+ "type": "integer",
52110
+ "description": "Agent tasks the schedule created in the window."
52111
+ },
52112
+ "actualUsd": {
52113
+ "type": "number",
52114
+ "description": "Recorded cost of those tasks. A floor: review tasks and follow-ups are not linked to the schedule."
52115
+ },
52116
+ "actualHours": {
52117
+ "type": "number"
52118
+ },
52119
+ "savingUsd": {
52120
+ "type": "null"
52121
+ }
52122
+ },
52123
+ "required": [
52124
+ "kind",
52125
+ "scheduleId",
52126
+ "scheduleName",
52127
+ "scheduleEnabled",
52128
+ "name",
52129
+ "basis",
52130
+ "runs",
52131
+ "actualUsd",
52132
+ "actualHours",
52133
+ "savingUsd"
52134
+ ]
52135
+ }
52136
+ ]
52137
+ }
52138
+ },
52139
+ "total": {
52140
+ "type": [
52141
+ "object",
52142
+ "null"
52143
+ ],
52144
+ "properties": {
52145
+ "runs": {
52146
+ "type": "integer"
52147
+ },
52148
+ "substitutedRuns": {
52149
+ "type": "integer"
52150
+ },
52151
+ "enabledOnlyRuns": {
52152
+ "type": "integer"
52153
+ },
52154
+ "measuredUsd": {
52155
+ "type": "number"
52156
+ },
52157
+ "estimatedLlmUsd": {
52158
+ "type": "number"
52159
+ },
52160
+ "actualUsd": {
52161
+ "type": "number"
52162
+ },
52163
+ "agentOnlyUsd": {
52164
+ "type": "object",
52165
+ "properties": {
52166
+ "p10": {
52167
+ "type": "number"
52168
+ },
52169
+ "p50": {
52170
+ "type": "number"
52171
+ },
52172
+ "p90": {
52173
+ "type": "number"
52174
+ }
52175
+ },
52176
+ "required": [
52177
+ "p10",
52178
+ "p50",
52179
+ "p90"
52180
+ ]
52181
+ },
52182
+ "savingUsd": {
52183
+ "type": "object",
52184
+ "properties": {
52185
+ "p10": {
52186
+ "type": "number"
52187
+ },
52188
+ "p50": {
52189
+ "type": "number"
52190
+ },
52191
+ "p90": {
52192
+ "type": "number"
52193
+ }
52194
+ },
52195
+ "required": [
52196
+ "p10",
52197
+ "p50",
52198
+ "p90"
52199
+ ]
52200
+ },
52201
+ "actualHours": {
52202
+ "type": "number"
52203
+ },
52204
+ "hoursSaved": {
52205
+ "type": "object",
52206
+ "properties": {
52207
+ "p10": {
52208
+ "type": "number"
52209
+ },
52210
+ "p50": {
52211
+ "type": "number"
52212
+ },
52213
+ "p90": {
52214
+ "type": "number"
52215
+ }
52216
+ },
52217
+ "required": [
52218
+ "p10",
52219
+ "p50",
52220
+ "p90"
52221
+ ]
52222
+ }
52223
+ },
52224
+ "required": [
52225
+ "runs",
52226
+ "substitutedRuns",
52227
+ "enabledOnlyRuns",
52228
+ "measuredUsd",
52229
+ "estimatedLlmUsd",
52230
+ "actualUsd",
52231
+ "agentOnlyUsd",
52232
+ "savingUsd",
52233
+ "actualHours",
52234
+ "hoursSaved"
52235
+ ]
52236
+ },
52237
+ "components": {
52238
+ "type": "array",
52239
+ "items": {
52240
+ "type": "object",
52241
+ "properties": {
52242
+ "kind": {
52243
+ "type": "string",
52244
+ "enum": [
52245
+ "workflow",
52246
+ "script",
52247
+ "task"
52248
+ ]
52249
+ },
52250
+ "workflowId": {
52251
+ "type": "string"
52252
+ },
52253
+ "scriptName": {
52254
+ "type": "string"
52255
+ },
52256
+ "name": {
52257
+ "type": "string"
52258
+ },
52259
+ "linkKind": {
52260
+ "type": "string",
52261
+ "enum": [
52262
+ "sub-workflow",
52263
+ "step-workflow",
52264
+ "step-script",
52265
+ "step-task",
52266
+ "descendant-task"
52267
+ ]
52268
+ },
52269
+ "depth": {
52270
+ "type": "integer"
52271
+ },
52272
+ "runs": {
52273
+ "type": "number",
52274
+ "description": "Runs (tasks for a task component) in this tree. Fractional below the first level."
52275
+ },
52276
+ "actualUsd": {
52277
+ "type": "number"
52278
+ },
52279
+ "agentOnlyUsd": {
52280
+ "type": "object",
52281
+ "properties": {
52282
+ "p10": {
52283
+ "type": "number"
52284
+ },
52285
+ "p50": {
52286
+ "type": "number"
52287
+ },
52288
+ "p90": {
52289
+ "type": "number"
52290
+ }
52291
+ },
52292
+ "required": [
52293
+ "p10",
52294
+ "p50",
52295
+ "p90"
52296
+ ]
52297
+ },
52298
+ "savingUsd": {
52299
+ "type": "object",
52300
+ "properties": {
52301
+ "p10": {
52302
+ "type": "number"
52303
+ },
52304
+ "p50": {
52305
+ "type": "number"
52306
+ },
52307
+ "p90": {
52308
+ "type": "number"
52309
+ }
52310
+ },
52311
+ "required": [
52312
+ "p10",
52313
+ "p50",
52314
+ "p90"
52315
+ ]
52316
+ },
52317
+ "hoursSaved": {
52318
+ "type": "object",
52319
+ "properties": {
52320
+ "p10": {
52321
+ "type": "number"
52322
+ },
52323
+ "p50": {
52324
+ "type": "number"
52325
+ },
52326
+ "p90": {
52327
+ "type": "number"
52328
+ }
52329
+ },
52330
+ "required": [
52331
+ "p10",
52332
+ "p50",
52333
+ "p90"
52334
+ ]
52335
+ },
52336
+ "inOwnRow": {
52337
+ "type": "boolean",
52338
+ "description": "True for unowned tasks: their spend is already in the workflow's own row, on both sides, and adds nothing to `withComponents`."
52339
+ }
52340
+ },
52341
+ "required": [
52342
+ "kind",
52343
+ "name",
52344
+ "linkKind",
52345
+ "depth",
52346
+ "runs",
52347
+ "actualUsd",
52348
+ "agentOnlyUsd",
52349
+ "savingUsd",
52350
+ "hoursSaved",
52351
+ "inOwnRow"
52352
+ ]
52353
+ }
52354
+ },
52355
+ "withComponents": {
52356
+ "type": [
52357
+ "object",
52358
+ "null"
52359
+ ],
52360
+ "properties": {
52361
+ "runs": {
52362
+ "type": "integer"
52363
+ },
52364
+ "substitutedRuns": {
52365
+ "type": "integer"
52366
+ },
52367
+ "enabledOnlyRuns": {
52368
+ "type": "integer"
52369
+ },
52370
+ "measuredUsd": {
52371
+ "type": "number"
52372
+ },
52373
+ "estimatedLlmUsd": {
52374
+ "type": "number"
52375
+ },
52376
+ "actualUsd": {
52377
+ "type": "number"
52378
+ },
52379
+ "agentOnlyUsd": {
52380
+ "type": "object",
52381
+ "properties": {
52382
+ "p10": {
52383
+ "type": "number"
52384
+ },
52385
+ "p50": {
52386
+ "type": "number"
52387
+ },
52388
+ "p90": {
52389
+ "type": "number"
52390
+ }
52391
+ },
52392
+ "required": [
52393
+ "p10",
52394
+ "p50",
52395
+ "p90"
52396
+ ]
52397
+ },
52398
+ "savingUsd": {
52399
+ "type": "object",
52400
+ "properties": {
52401
+ "p10": {
52402
+ "type": "number"
52403
+ },
52404
+ "p50": {
52405
+ "type": "number"
52406
+ },
52407
+ "p90": {
52408
+ "type": "number"
52409
+ }
52410
+ },
52411
+ "required": [
52412
+ "p10",
52413
+ "p50",
52414
+ "p90"
52415
+ ]
52416
+ },
52417
+ "actualHours": {
52418
+ "type": "number"
52419
+ },
52420
+ "hoursSaved": {
52421
+ "type": "object",
52422
+ "properties": {
52423
+ "p10": {
52424
+ "type": "number"
52425
+ },
52426
+ "p50": {
52427
+ "type": "number"
52428
+ },
52429
+ "p90": {
52430
+ "type": "number"
52431
+ }
52432
+ },
52433
+ "required": [
52434
+ "p10",
52435
+ "p50",
52436
+ "p90"
52437
+ ]
52438
+ }
52439
+ },
52440
+ "required": [
52441
+ "runs",
52442
+ "substitutedRuns",
52443
+ "enabledOnlyRuns",
52444
+ "measuredUsd",
52445
+ "estimatedLlmUsd",
52446
+ "actualUsd",
52447
+ "agentOnlyUsd",
52448
+ "savingUsd",
52449
+ "actualHours",
52450
+ "hoursSaved"
52451
+ ]
52452
+ }
52453
+ },
52454
+ "required": [
52455
+ "window",
52456
+ "tier",
52457
+ "calibrationModel",
52458
+ "calibratedAt",
52459
+ "calibrationSource",
52460
+ "computedAt",
52461
+ "valid",
52462
+ "reason",
52463
+ "boundaryEstimated",
52464
+ "rows",
52465
+ "total"
52466
+ ]
52467
+ }
52468
+ }
52469
+ }
52470
+ },
52471
+ "400": {
52472
+ "description": "Not exactly one of workflowId, scriptName, scheduleId and kind, `components=true` without workflowId, or an unknown days or tier value",
52473
+ "content": {
52474
+ "application/json": {
52475
+ "schema": {
52476
+ "$ref": "#/components/schemas/ErrorResponse"
52477
+ }
52478
+ }
52479
+ }
52480
+ },
52481
+ "404": {
52482
+ "description": "Workflow, script or schedule not found",
52483
+ "content": {
52484
+ "application/json": {
52485
+ "schema": {
52486
+ "$ref": "#/components/schemas/ErrorResponse"
52487
+ }
52488
+ }
52489
+ }
52490
+ }
52491
+ }
52492
+ }
52493
+ },
52494
+ "/api/savings/daily": {
52495
+ "get": {
52496
+ "summary": "Daily automation savings of a workflow, a script or the fleet",
52497
+ "description": "The p50 saving, measured spend, estimated LLM spend and scaled actual cost per UTC day of the window, from the hourly savings rollup. With `workflowId` or `scriptName` the points add up to the window figures of `GET /api/savings/jobs` for the same target; with neither they cover every workflow and script and add up to `GET /api/savings/summary`.",
52498
+ "tags": [
52499
+ "Savings"
52500
+ ],
52501
+ "security": [
52502
+ {
52503
+ "bearerAuth": []
52504
+ }
52505
+ ],
52506
+ "parameters": [
52507
+ {
52508
+ "schema": {
52509
+ "type": "string",
52510
+ "minLength": 1
52511
+ },
52512
+ "required": false,
52513
+ "name": "workflowId",
52514
+ "in": "query"
52515
+ },
52516
+ {
52517
+ "schema": {
52518
+ "type": "string",
52519
+ "minLength": 1
52520
+ },
52521
+ "required": false,
52522
+ "name": "scriptName",
52523
+ "in": "query"
52524
+ },
52525
+ {
52526
+ "schema": {
52527
+ "type": "string",
52528
+ "enum": [
52529
+ "7",
52530
+ "30",
52531
+ "90"
52532
+ ],
52533
+ "default": "30"
52534
+ },
52535
+ "required": false,
52536
+ "name": "days",
52537
+ "in": "query"
52538
+ },
52539
+ {
52540
+ "schema": {
52541
+ "type": "string",
52542
+ "enum": [
52543
+ "smol",
52544
+ "regular",
52545
+ "smart",
52546
+ "ultra"
52547
+ ],
52548
+ "default": "smart"
52549
+ },
52550
+ "required": false,
52551
+ "name": "tier",
52552
+ "in": "query"
52553
+ }
52554
+ ],
52555
+ "responses": {
52556
+ "200": {
52557
+ "description": "Daily savings points",
52558
+ "content": {
52559
+ "application/json": {
52560
+ "schema": {
52561
+ "type": "object",
52562
+ "properties": {
52563
+ "window": {
52564
+ "type": "object",
52565
+ "properties": {
52566
+ "start": {
52567
+ "type": "string"
52568
+ },
52569
+ "end": {
52570
+ "type": "string"
52571
+ },
52572
+ "days": {
52573
+ "type": "integer"
52574
+ }
52575
+ },
52576
+ "required": [
52577
+ "start",
52578
+ "end",
52579
+ "days"
52580
+ ]
52581
+ },
52582
+ "tier": {
52583
+ "type": "string",
52584
+ "enum": [
52585
+ "smol",
52586
+ "regular",
52587
+ "smart",
52588
+ "ultra"
52589
+ ]
52590
+ },
52591
+ "calibrationModel": {
52592
+ "type": "string"
52593
+ },
52594
+ "calibratedAt": {
52595
+ "type": "string"
52596
+ },
52597
+ "calibrationSource": {
52598
+ "type": "string",
52599
+ "enum": [
52600
+ "shipped",
52601
+ "deployment"
52602
+ ]
52603
+ },
52604
+ "computedAt": {
52605
+ "type": [
52606
+ "string",
52607
+ "null"
52608
+ ]
52609
+ },
52610
+ "valid": {
52611
+ "type": "boolean"
52612
+ },
52613
+ "reason": {
52614
+ "type": [
52615
+ "string",
52616
+ "null"
52617
+ ],
52618
+ "enum": [
52619
+ "not-computed",
52620
+ "no-runs",
52621
+ "target-missing",
52622
+ null
52623
+ ]
52624
+ },
52625
+ "boundaryEstimated": {
52626
+ "type": "boolean",
52627
+ "description": "The window is rolling, so its first UTC day is partial and its runs are scanned live. True when that scan could not run (too many runs, or a busy database) and the day's bucket was scaled to the part inside the window instead."
52628
+ },
52629
+ "points": {
52630
+ "type": "array",
52631
+ "items": {
52632
+ "type": "object",
52633
+ "properties": {
52634
+ "day": {
52635
+ "type": "string"
52636
+ },
52637
+ "savingUsd": {
52638
+ "type": "number"
52639
+ },
52640
+ "actualUsd": {
52641
+ "type": "number",
52642
+ "description": "Scaled estimate: the day's measured and estimated spend times the window's substituted share."
52643
+ },
52644
+ "measuredUsd": {
52645
+ "type": "number",
52646
+ "description": "The day's measured spend, not scaled."
52647
+ },
52648
+ "estimatedLlmUsd": {
52649
+ "type": "number",
52650
+ "description": "The day's LLM spend estimated from tokens and output size, not measured."
52651
+ }
52652
+ },
52653
+ "required": [
52654
+ "day",
52655
+ "savingUsd",
52656
+ "actualUsd",
52657
+ "measuredUsd",
52658
+ "estimatedLlmUsd"
52659
+ ]
52660
+ }
52661
+ }
52662
+ },
52663
+ "required": [
52664
+ "window",
52665
+ "tier",
52666
+ "calibrationModel",
52667
+ "calibratedAt",
52668
+ "calibrationSource",
52669
+ "computedAt",
52670
+ "valid",
52671
+ "reason",
52672
+ "boundaryEstimated",
52673
+ "points"
52674
+ ]
52675
+ }
52676
+ }
52677
+ }
52678
+ },
52679
+ "400": {
52680
+ "description": "Both workflowId and scriptName, or an unknown days or tier value",
52681
+ "content": {
52682
+ "application/json": {
52683
+ "schema": {
52684
+ "$ref": "#/components/schemas/ErrorResponse"
52685
+ }
52686
+ }
52687
+ }
52688
+ },
52689
+ "404": {
52690
+ "description": "Workflow or script not found",
52691
+ "content": {
52692
+ "application/json": {
52693
+ "schema": {
52694
+ "$ref": "#/components/schemas/ErrorResponse"
52695
+ }
52696
+ }
52697
+ }
52698
+ }
52699
+ }
52700
+ }
52701
+ },
52702
+ "/api/savings/summary": {
52703
+ "get": {
52704
+ "summary": "Fleet automation savings",
52705
+ "description": "What every workflow and script run in the window would have cost as agent tasks, minus what they cost, from the hourly savings rollup at the chosen tier, with the fleet's 80% range. Adds the swarm's measured session spend over the same window, the self-optimization ratio, the runs left out and the model's assumptions. `valid` is false until the rollup has computed every day of the window, and when there were no runs.",
52706
+ "tags": [
52707
+ "Savings"
52708
+ ],
52709
+ "security": [
52710
+ {
52711
+ "bearerAuth": []
52712
+ }
52713
+ ],
52714
+ "parameters": [
52715
+ {
52716
+ "schema": {
52717
+ "type": "string",
52718
+ "enum": [
52719
+ "7",
52720
+ "30",
52721
+ "90"
52722
+ ],
52723
+ "default": "30"
52724
+ },
52725
+ "required": false,
52726
+ "name": "days",
52727
+ "in": "query"
52728
+ },
52729
+ {
52730
+ "schema": {
52731
+ "type": "string",
52732
+ "enum": [
52733
+ "smol",
52734
+ "regular",
52735
+ "smart",
52736
+ "ultra"
52737
+ ],
52738
+ "default": "smart"
52739
+ },
52740
+ "required": false,
52741
+ "name": "tier",
52742
+ "in": "query"
52743
+ }
52744
+ ],
52745
+ "responses": {
52746
+ "200": {
52747
+ "description": "Fleet savings",
52748
+ "content": {
52749
+ "application/json": {
52750
+ "schema": {
52751
+ "type": "object",
52752
+ "properties": {
52753
+ "window": {
52754
+ "type": "object",
52755
+ "properties": {
52756
+ "start": {
52757
+ "type": "string"
52758
+ },
52759
+ "end": {
52760
+ "type": "string"
52761
+ },
52762
+ "days": {
52763
+ "type": "integer"
52764
+ }
52765
+ },
52766
+ "required": [
52767
+ "start",
52768
+ "end",
52769
+ "days"
52770
+ ]
52771
+ },
52772
+ "tier": {
52773
+ "type": "string",
52774
+ "enum": [
52775
+ "smol",
52776
+ "regular",
52777
+ "smart",
52778
+ "ultra"
52779
+ ]
52780
+ },
52781
+ "calibrationModel": {
52782
+ "type": "string"
52783
+ },
52784
+ "calibratedAt": {
52785
+ "type": "string"
52786
+ },
52787
+ "calibrationSource": {
52788
+ "type": "string",
52789
+ "enum": [
52790
+ "shipped",
52791
+ "deployment"
52792
+ ]
52793
+ },
52794
+ "computedAt": {
52795
+ "type": [
52796
+ "string",
52797
+ "null"
52798
+ ]
52799
+ },
52800
+ "valid": {
52801
+ "type": "boolean"
52802
+ },
52803
+ "reason": {
52804
+ "type": [
52805
+ "string",
52806
+ "null"
52807
+ ],
52808
+ "enum": [
52809
+ "not-computed",
52810
+ "no-runs",
52811
+ "target-missing",
52812
+ null
52813
+ ]
52814
+ },
52815
+ "boundaryEstimated": {
52816
+ "type": "boolean",
52817
+ "description": "The window is rolling, so its first UTC day is partial and its runs are scanned live. True when that scan could not run (too many runs, or a busy database) and the day's bucket was scaled to the part inside the window instead."
52818
+ },
52819
+ "total": {
52820
+ "type": [
52821
+ "object",
52822
+ "null"
52823
+ ],
52824
+ "properties": {
52825
+ "runs": {
52826
+ "type": "integer"
52827
+ },
52828
+ "substitutedRuns": {
52829
+ "type": "integer"
52830
+ },
52831
+ "enabledOnlyRuns": {
52832
+ "type": "integer"
52833
+ },
52834
+ "measuredUsd": {
52835
+ "type": "number"
52836
+ },
52837
+ "estimatedLlmUsd": {
52838
+ "type": "number"
52839
+ },
52840
+ "actualUsd": {
52841
+ "type": "number"
52842
+ },
52843
+ "agentOnlyUsd": {
52844
+ "type": "object",
52845
+ "properties": {
52846
+ "p10": {
52847
+ "type": "number"
52848
+ },
52849
+ "p50": {
52850
+ "type": "number"
52851
+ },
52852
+ "p90": {
52853
+ "type": "number"
52854
+ }
52855
+ },
52856
+ "required": [
52857
+ "p10",
52858
+ "p50",
52859
+ "p90"
52860
+ ]
52861
+ },
52862
+ "savingUsd": {
52863
+ "type": "object",
52864
+ "properties": {
52865
+ "p10": {
52866
+ "type": "number"
52867
+ },
52868
+ "p50": {
52869
+ "type": "number"
52870
+ },
52871
+ "p90": {
52872
+ "type": "number"
52873
+ }
52874
+ },
52875
+ "required": [
52876
+ "p10",
52877
+ "p50",
52878
+ "p90"
52879
+ ]
52880
+ },
52881
+ "actualHours": {
52882
+ "type": "number"
52883
+ },
52884
+ "hoursSaved": {
52885
+ "type": "object",
52886
+ "properties": {
52887
+ "p10": {
52888
+ "type": "number"
52889
+ },
52890
+ "p50": {
52891
+ "type": "number"
52892
+ },
52893
+ "p90": {
52894
+ "type": "number"
52895
+ }
52896
+ },
52897
+ "required": [
52898
+ "p10",
52899
+ "p50",
52900
+ "p90"
52901
+ ]
52902
+ }
52903
+ },
52904
+ "required": [
52905
+ "runs",
52906
+ "substitutedRuns",
52907
+ "enabledOnlyRuns",
52908
+ "measuredUsd",
52909
+ "estimatedLlmUsd",
52910
+ "actualUsd",
52911
+ "agentOnlyUsd",
52912
+ "savingUsd",
52913
+ "actualHours",
52914
+ "hoursSaved"
52915
+ ]
52916
+ },
52917
+ "byKind": {
52918
+ "type": [
52919
+ "object",
52920
+ "null"
52921
+ ],
52922
+ "properties": {
52923
+ "workflows": {
52924
+ "type": "object",
52925
+ "properties": {
52926
+ "jobs": {
52927
+ "type": "integer"
52928
+ },
52929
+ "runs": {
52930
+ "type": "integer"
52931
+ },
52932
+ "substitutedRuns": {
52933
+ "type": "integer"
52934
+ },
52935
+ "savingUsd": {
52936
+ "type": "number",
52937
+ "description": "p50"
52938
+ },
52939
+ "hoursSaved": {
52940
+ "type": "number",
52941
+ "description": "p50"
52942
+ }
52943
+ },
52944
+ "required": [
52945
+ "jobs",
52946
+ "runs",
52947
+ "substitutedRuns",
52948
+ "savingUsd",
52949
+ "hoursSaved"
52950
+ ]
52951
+ },
52952
+ "scheduledScripts": {
52953
+ "type": "object",
52954
+ "properties": {
52955
+ "jobs": {
52956
+ "type": "integer"
52957
+ },
52958
+ "runs": {
52959
+ "type": "integer"
52960
+ },
52961
+ "substitutedRuns": {
52962
+ "type": "integer"
52963
+ },
52964
+ "savingUsd": {
52965
+ "type": "number",
52966
+ "description": "p50"
52967
+ },
52968
+ "hoursSaved": {
52969
+ "type": "number",
52970
+ "description": "p50"
52971
+ }
52972
+ },
52973
+ "required": [
52974
+ "jobs",
52975
+ "runs",
52976
+ "substitutedRuns",
52977
+ "savingUsd",
52978
+ "hoursSaved"
52979
+ ]
52980
+ },
52981
+ "agentInvokedScripts": {
52982
+ "type": "object",
52983
+ "properties": {
52984
+ "jobs": {
52985
+ "type": "integer"
52986
+ },
52987
+ "runs": {
52988
+ "type": "integer"
52989
+ },
52990
+ "substitutedRuns": {
52991
+ "type": "integer"
52992
+ },
52993
+ "savingUsd": {
52994
+ "type": "number",
52995
+ "description": "p50"
52996
+ },
52997
+ "hoursSaved": {
52998
+ "type": "number",
52999
+ "description": "p50"
53000
+ }
53001
+ },
53002
+ "required": [
53003
+ "jobs",
53004
+ "runs",
53005
+ "substitutedRuns",
53006
+ "savingUsd",
53007
+ "hoursSaved"
53008
+ ]
53009
+ }
53010
+ },
53011
+ "required": [
53012
+ "workflows",
53013
+ "scheduledScripts",
53014
+ "agentInvokedScripts"
53015
+ ]
53016
+ },
53017
+ "fleetLlmUsd": {
53018
+ "type": "number",
53019
+ "description": "Measured session spend of the whole swarm in the window, as on the usage page."
53020
+ },
53021
+ "selfOptimizationRatio": {
53022
+ "type": [
53023
+ "number",
53024
+ "null"
53025
+ ],
53026
+ "description": "`(fleetLlmUsd + savingUsd.p50) / fleetLlmUsd`: what the swarm would have spent without its automations, per dollar it spent. Null without spend or without a valid total."
53027
+ },
53028
+ "excluded": {
53029
+ "type": [
53030
+ "object",
53031
+ "null"
53032
+ ],
53033
+ "properties": {
53034
+ "enabledOnlyRuns": {
53035
+ "type": "integer",
53036
+ "description": "Runs that are not substituted: router events and API runs with no effect, polls above the hourly cap, skipped and cancelled runs."
53037
+ }
53038
+ },
53039
+ "required": [
53040
+ "enabledOnlyRuns"
53041
+ ]
53042
+ },
53043
+ "assumptions": {
53044
+ "type": "array",
53045
+ "items": {
53046
+ "type": "string"
53047
+ }
53048
+ }
53049
+ },
53050
+ "required": [
53051
+ "window",
53052
+ "tier",
53053
+ "calibrationModel",
53054
+ "calibratedAt",
53055
+ "calibrationSource",
53056
+ "computedAt",
53057
+ "valid",
53058
+ "reason",
53059
+ "boundaryEstimated",
53060
+ "total",
53061
+ "byKind",
53062
+ "fleetLlmUsd",
53063
+ "selfOptimizationRatio",
53064
+ "excluded",
53065
+ "assumptions"
53066
+ ]
53067
+ }
53068
+ }
53069
+ }
53070
+ },
53071
+ "400": {
53072
+ "description": "An unknown days or tier value",
53073
+ "content": {
53074
+ "application/json": {
53075
+ "schema": {
53076
+ "$ref": "#/components/schemas/ErrorResponse"
53077
+ }
53078
+ }
53079
+ }
53080
+ }
53081
+ }
53082
+ }
53083
+ },
53084
+ "/api/savings/calibration": {
53085
+ "get": {
53086
+ "summary": "The savings curve in use",
53087
+ "description": "Which curve prices the savings endpoints: the one shipped with the release, or one derived from this deployment's sessions and stored by `POST /api/savings/calibration`. Reports the stored row's metadata (a malformed row is reported as invalid and ignored by the savings endpoints).",
53088
+ "tags": [
53089
+ "Savings"
53090
+ ],
53091
+ "security": [
53092
+ {
53093
+ "bearerAuth": []
53094
+ }
53095
+ ],
53096
+ "responses": {
53097
+ "200": {
53098
+ "description": "The active calibration",
53099
+ "content": {
53100
+ "application/json": {
53101
+ "schema": {
53102
+ "type": "object",
53103
+ "properties": {
53104
+ "source": {
53105
+ "type": "string",
53106
+ "enum": [
53107
+ "shipped",
53108
+ "deployment"
53109
+ ]
53110
+ },
53111
+ "active": {
53112
+ "type": "object",
53113
+ "properties": {
53114
+ "calibratedAt": {
53115
+ "type": "string"
53116
+ },
53117
+ "model": {
53118
+ "type": "string"
53119
+ },
53120
+ "curve": {
53121
+ "type": "object",
53122
+ "properties": {
53123
+ "smol": {
53124
+ "type": "object",
53125
+ "properties": {
53126
+ "usd": {
53127
+ "type": "array",
53128
+ "items": {
53129
+ "type": "number"
53130
+ }
53131
+ },
53132
+ "hrs": {
53133
+ "type": "array",
53134
+ "items": {
53135
+ "type": "number"
53136
+ }
53137
+ }
53138
+ },
53139
+ "required": [
53140
+ "usd",
53141
+ "hrs"
53142
+ ]
53143
+ },
53144
+ "regular": {
53145
+ "type": "object",
53146
+ "properties": {
53147
+ "usd": {
53148
+ "type": "array",
53149
+ "items": {
53150
+ "type": "number"
53151
+ }
53152
+ },
53153
+ "hrs": {
53154
+ "type": "array",
53155
+ "items": {
53156
+ "type": "number"
53157
+ }
53158
+ }
53159
+ },
53160
+ "required": [
53161
+ "usd",
53162
+ "hrs"
53163
+ ]
53164
+ },
53165
+ "smart": {
53166
+ "type": "object",
53167
+ "properties": {
53168
+ "usd": {
53169
+ "type": "array",
53170
+ "items": {
53171
+ "type": "number"
53172
+ }
53173
+ },
53174
+ "hrs": {
53175
+ "type": "array",
53176
+ "items": {
53177
+ "type": "number"
53178
+ }
53179
+ }
53180
+ },
53181
+ "required": [
53182
+ "usd",
53183
+ "hrs"
53184
+ ]
53185
+ },
53186
+ "ultra": {
53187
+ "type": "object",
53188
+ "properties": {
53189
+ "usd": {
53190
+ "type": "array",
53191
+ "items": {
53192
+ "type": "number"
53193
+ }
53194
+ },
53195
+ "hrs": {
53196
+ "type": "array",
53197
+ "items": {
53198
+ "type": "number"
53199
+ }
53200
+ }
53201
+ },
53202
+ "required": [
53203
+ "usd",
53204
+ "hrs"
53205
+ ]
53206
+ }
53207
+ },
53208
+ "required": [
53209
+ "smol",
53210
+ "regular",
53211
+ "smart",
53212
+ "ultra"
53213
+ ]
53214
+ }
53215
+ },
53216
+ "required": [
53217
+ "calibratedAt",
53218
+ "model",
53219
+ "curve"
53220
+ ]
53221
+ },
53222
+ "stored": {
53223
+ "type": [
53224
+ "object",
53225
+ "null"
53226
+ ],
53227
+ "properties": {
53228
+ "valid": {
53229
+ "type": "boolean"
53230
+ },
53231
+ "updatedAt": {
53232
+ "type": "string"
53233
+ },
53234
+ "calibratedAt": {
53235
+ "type": "string"
53236
+ },
53237
+ "model": {
53238
+ "type": "string"
53239
+ },
53240
+ "window": {
53241
+ "type": "object",
53242
+ "properties": {
53243
+ "start": {
53244
+ "type": "string"
53245
+ },
53246
+ "end": {
53247
+ "type": "string"
53248
+ },
53249
+ "sessions": {
53250
+ "type": "integer"
53251
+ }
53252
+ },
53253
+ "required": [
53254
+ "start",
53255
+ "end",
53256
+ "sessions"
53257
+ ]
53258
+ }
53259
+ },
53260
+ "required": [
53261
+ "valid",
53262
+ "updatedAt"
53263
+ ]
53264
+ }
53265
+ },
53266
+ "required": [
53267
+ "source",
53268
+ "active",
53269
+ "stored"
53270
+ ]
53271
+ }
53272
+ }
53273
+ }
53274
+ }
53275
+ }
53276
+ },
53277
+ "post": {
53278
+ "summary": "Derive the savings curve from this deployment's sessions",
53279
+ "description": "Reads the window's opus sessions through the bounded query executor, derives the per-tier cost and hours curve, and compares it to the shipped one. Read-only unless `apply` is true, which also requires `config.write.any`: then the curve is stored in the global `SAVINGS_CURVE_CALIBRATION` config row and the savings endpoints use it within seconds. Nothing is stored when the data cannot support a curve or the derived mean cost is more than 3x or less than a third of the shipped one. One run at a time; a run past 120 s is abandoned with 504.",
53280
+ "tags": [
53281
+ "Savings"
53282
+ ],
53283
+ "security": [
53284
+ {
53285
+ "bearerAuth": []
53286
+ }
53287
+ ],
53288
+ "requestBody": {
53289
+ "content": {
53290
+ "application/json": {
53291
+ "schema": {
53292
+ "type": "object",
53293
+ "properties": {
53294
+ "days": {
53295
+ "type": "integer",
53296
+ "minimum": 1,
53297
+ "maximum": 90,
53298
+ "default": 30
53299
+ },
53300
+ "end": {
53301
+ "type": "string",
53302
+ "format": "date-time",
53303
+ "description": "End of the window (ISO 8601); default now."
53304
+ },
53305
+ "apply": {
53306
+ "type": "boolean",
53307
+ "default": false
53308
+ }
53309
+ }
53310
+ }
53311
+ }
53312
+ }
53313
+ },
53314
+ "responses": {
53315
+ "200": {
53316
+ "description": "The derived curve, or why there is none",
53317
+ "content": {
53318
+ "application/json": {
53319
+ "schema": {
53320
+ "type": "object",
53321
+ "properties": {
53322
+ "window": {
53323
+ "type": "object",
53324
+ "properties": {
53325
+ "start": {
53326
+ "type": "string"
53327
+ },
53328
+ "end": {
53329
+ "type": "string"
53330
+ },
53331
+ "days": {
53332
+ "type": "integer"
53333
+ }
53334
+ },
53335
+ "required": [
53336
+ "start",
53337
+ "end",
53338
+ "days"
53339
+ ]
53340
+ },
53341
+ "sessions": {
53342
+ "type": "integer",
53343
+ "description": "Opus sessions of 1 to 61 turns used."
53344
+ },
53345
+ "refusals": {
53346
+ "type": "array",
53347
+ "items": {
53348
+ "type": "string"
53349
+ },
53350
+ "description": "Why no curve was derived, or why a derived one was not applied."
53351
+ },
53352
+ "calibration": {
53353
+ "type": [
53354
+ "object",
53355
+ "null"
53356
+ ],
53357
+ "properties": {
53358
+ "calibratedAt": {
53359
+ "type": "string"
53360
+ },
53361
+ "model": {
53362
+ "type": "string"
53363
+ },
53364
+ "curve": {
53365
+ "type": "object",
53366
+ "properties": {
53367
+ "smol": {
53368
+ "type": "object",
53369
+ "properties": {
53370
+ "usd": {
53371
+ "type": "array",
53372
+ "items": {
53373
+ "type": "number"
53374
+ }
53375
+ },
53376
+ "hrs": {
53377
+ "type": "array",
53378
+ "items": {
53379
+ "type": "number"
53380
+ }
53381
+ }
53382
+ },
53383
+ "required": [
53384
+ "usd",
53385
+ "hrs"
53386
+ ]
53387
+ },
53388
+ "regular": {
53389
+ "type": "object",
53390
+ "properties": {
53391
+ "usd": {
53392
+ "type": "array",
53393
+ "items": {
53394
+ "type": "number"
53395
+ }
53396
+ },
53397
+ "hrs": {
53398
+ "type": "array",
53399
+ "items": {
53400
+ "type": "number"
53401
+ }
53402
+ }
53403
+ },
53404
+ "required": [
53405
+ "usd",
53406
+ "hrs"
53407
+ ]
53408
+ },
53409
+ "smart": {
53410
+ "type": "object",
53411
+ "properties": {
53412
+ "usd": {
53413
+ "type": "array",
53414
+ "items": {
53415
+ "type": "number"
53416
+ }
53417
+ },
53418
+ "hrs": {
53419
+ "type": "array",
53420
+ "items": {
53421
+ "type": "number"
53422
+ }
53423
+ }
53424
+ },
53425
+ "required": [
53426
+ "usd",
53427
+ "hrs"
53428
+ ]
53429
+ },
53430
+ "ultra": {
53431
+ "type": "object",
53432
+ "properties": {
53433
+ "usd": {
53434
+ "type": "array",
53435
+ "items": {
53436
+ "type": "number"
53437
+ }
53438
+ },
53439
+ "hrs": {
53440
+ "type": "array",
53441
+ "items": {
53442
+ "type": "number"
53443
+ }
53444
+ }
53445
+ },
53446
+ "required": [
53447
+ "usd",
53448
+ "hrs"
53449
+ ]
53450
+ }
53451
+ },
53452
+ "required": [
53453
+ "smol",
53454
+ "regular",
53455
+ "smart",
53456
+ "ultra"
53457
+ ]
53458
+ },
53459
+ "window": {
53460
+ "type": "object",
53461
+ "properties": {
53462
+ "start": {
53463
+ "type": "string"
53464
+ },
53465
+ "end": {
53466
+ "type": "string"
53467
+ },
53468
+ "sessions": {
53469
+ "type": "integer"
53470
+ }
53471
+ },
53472
+ "required": [
53473
+ "start",
53474
+ "end",
53475
+ "sessions"
53476
+ ]
53477
+ }
53478
+ },
53479
+ "required": [
53480
+ "calibratedAt",
53481
+ "model",
53482
+ "curve"
53483
+ ],
53484
+ "description": "The derived curve; null when refused."
53485
+ },
53486
+ "speed": {
53487
+ "type": [
53488
+ "object",
53489
+ "null"
53490
+ ],
53491
+ "additionalProperties": {
53492
+ "type": "number"
53493
+ }
53494
+ },
53495
+ "repriceMatch": {
53496
+ "type": [
53497
+ "number",
53498
+ "null"
53499
+ ]
53500
+ },
53501
+ "meanRatio": {
53502
+ "type": [
53503
+ "number",
53504
+ "null"
53505
+ ],
53506
+ "description": "Derived smart-tier mean cost over the shipped one."
53507
+ },
53508
+ "gaps": {
53509
+ "type": "array",
53510
+ "items": {
53511
+ "type": "object",
53512
+ "properties": {
53513
+ "tier": {
53514
+ "type": "string",
53515
+ "enum": [
53516
+ "smol",
53517
+ "regular",
53518
+ "smart",
53519
+ "ultra"
53520
+ ]
53521
+ },
53522
+ "key": {
53523
+ "type": "string",
53524
+ "enum": [
53525
+ "usd",
53526
+ "hrs"
53527
+ ]
53528
+ },
53529
+ "median": {
53530
+ "type": "number",
53531
+ "description": "Median absolute deviation from the shipped curve, as a fraction."
53532
+ },
53533
+ "max": {
53534
+ "type": "number"
53535
+ },
53536
+ "over5pct": {
53537
+ "type": "integer",
53538
+ "description": "Turn counts more than 5% from the shipped curve."
53539
+ },
53540
+ "points": {
53541
+ "type": "integer"
53542
+ },
53543
+ "weighted": {
53544
+ "type": "number",
53545
+ "description": "Session-weighted mean of derived over shipped; 1 means the same price."
53546
+ }
53547
+ },
53548
+ "required": [
53549
+ "tier",
53550
+ "key",
53551
+ "median",
53552
+ "max",
53553
+ "over5pct",
53554
+ "points",
53555
+ "weighted"
53556
+ ]
53557
+ }
53558
+ },
53559
+ "applied": {
53560
+ "type": "boolean"
53561
+ }
53562
+ },
53563
+ "required": [
53564
+ "window",
53565
+ "sessions",
53566
+ "refusals",
53567
+ "calibration",
53568
+ "speed",
53569
+ "repriceMatch",
53570
+ "meanRatio",
53571
+ "gaps",
53572
+ "applied"
53573
+ ]
53574
+ }
53575
+ }
53576
+ }
53577
+ },
53578
+ "400": {
53579
+ "description": "Invalid days, end or apply",
53580
+ "content": {
53581
+ "application/json": {
53582
+ "schema": {
53583
+ "$ref": "#/components/schemas/ErrorResponse"
53584
+ }
53585
+ }
53586
+ }
53587
+ },
53588
+ "403": {
53589
+ "description": "`apply` without permission to write config",
53590
+ "content": {
53591
+ "application/json": {
53592
+ "schema": {
53593
+ "$ref": "#/components/schemas/ErrorResponse"
53594
+ }
53595
+ }
53596
+ }
53597
+ },
53598
+ "408": {
53599
+ "description": "A session query ran past its time budget",
53600
+ "content": {
53601
+ "application/json": {
53602
+ "schema": {
53603
+ "$ref": "#/components/schemas/ErrorResponse"
53604
+ }
53605
+ }
53606
+ }
53607
+ },
53608
+ "409": {
53609
+ "description": "Another calibration run is in progress",
53610
+ "content": {
53611
+ "application/json": {
53612
+ "schema": {
53613
+ "$ref": "#/components/schemas/ErrorResponse"
53614
+ }
53615
+ }
53616
+ }
53617
+ },
53618
+ "504": {
53619
+ "description": "The run passed its 120 s deadline",
53620
+ "content": {
53621
+ "application/json": {
53622
+ "schema": {
53623
+ "$ref": "#/components/schemas/ErrorResponse"
53624
+ }
53625
+ }
53626
+ }
53627
+ }
53628
+ }
53629
+ }
53630
+ },
53631
+ "/api/sessions/tokens": {
53632
+ "post": {
53633
+ "summary": "Mint an ephemeral task or runtime token",
53634
+ "description": "Operators can mint task or runtime tokens. Runtime and agent tokens can mint task tokens for their own assigned tasks. A child token never outlives its parent and is revoked with it.",
53635
+ "tags": [
53636
+ "Sessions"
53637
+ ],
53638
+ "security": [
53639
+ {
53640
+ "bearerAuth": []
53641
+ }
53642
+ ],
53643
+ "requestBody": {
53644
+ "content": {
53645
+ "application/json": {
53646
+ "schema": {
53647
+ "type": "object",
53648
+ "properties": {
53649
+ "agentId": {
53650
+ "type": "string",
53651
+ "minLength": 1
53652
+ },
53653
+ "taskId": {
53654
+ "type": "string",
53655
+ "minLength": 1
53656
+ },
53657
+ "runtimeId": {
53658
+ "type": "string",
53659
+ "minLength": 1
53660
+ },
53661
+ "ttlMs": {
53662
+ "type": "integer",
53663
+ "exclusiveMinimum": 0,
53664
+ "maximum": 604800000
53665
+ }
53666
+ },
53667
+ "required": [
53668
+ "agentId"
53669
+ ]
53670
+ }
53671
+ }
53672
+ }
53673
+ },
53674
+ "responses": {
53675
+ "200": {
53676
+ "description": "Minted token plaintext (returned once) and its stable token ID",
53677
+ "content": {
53678
+ "application/json": {
53679
+ "schema": {
53680
+ "type": "object",
53681
+ "properties": {
53682
+ "tokenId": {
53683
+ "type": "string"
53684
+ },
53685
+ "plaintext": {
53686
+ "type": "string"
53687
+ }
53688
+ },
53689
+ "required": [
53690
+ "tokenId",
53691
+ "plaintext"
53692
+ ]
53693
+ }
53694
+ }
53695
+ }
53696
+ },
53697
+ "400": {
53698
+ "description": "Validation error",
53699
+ "content": {
53700
+ "application/json": {
53701
+ "schema": {
53702
+ "$ref": "#/components/schemas/ErrorResponse"
53703
+ }
53704
+ }
53705
+ }
53706
+ },
53707
+ "401": {
53708
+ "description": "Unauthorized",
53709
+ "content": {
53710
+ "application/json": {
53711
+ "schema": {
53712
+ "$ref": "#/components/schemas/ErrorResponse"
53713
+ }
53714
+ }
53715
+ }
53716
+ },
53717
+ "403": {
53718
+ "description": "Token cannot mint for this agent or task",
53719
+ "content": {
53720
+ "application/json": {
53721
+ "schema": {
53722
+ "$ref": "#/components/schemas/ErrorResponse"
53723
+ }
53724
+ }
53725
+ }
53726
+ }
53727
+ }
53728
+ }
53729
+ },
53730
+ "/api/sessions/tokens/{tokenId}": {
53731
+ "delete": {
53732
+ "summary": "Revoke an ephemeral session token",
53733
+ "description": "Operators can revoke any ephemeral token. Agent tokens, and runtime tokens when runtime pools are enabled, can revoke their own child task tokens. Repeated revocation has no effect.",
53734
+ "tags": [
53735
+ "Sessions"
53736
+ ],
53737
+ "security": [
53738
+ {
53739
+ "bearerAuth": []
53740
+ }
53741
+ ],
53742
+ "parameters": [
53743
+ {
53744
+ "schema": {
53745
+ "type": "string"
53746
+ },
53747
+ "required": true,
53748
+ "name": "tokenId",
53749
+ "in": "path"
53750
+ }
53751
+ ],
53752
+ "responses": {
53753
+ "204": {
53754
+ "description": "Token revoked (or was already revoked)"
53755
+ },
53756
+ "401": {
53757
+ "description": "Unauthorized",
53758
+ "content": {
53759
+ "application/json": {
53760
+ "schema": {
53761
+ "$ref": "#/components/schemas/ErrorResponse"
53762
+ }
53763
+ }
53764
+ }
53765
+ },
53766
+ "403": {
53767
+ "description": "Token cannot revoke this child",
53768
+ "content": {
53769
+ "application/json": {
53770
+ "schema": {
53771
+ "$ref": "#/components/schemas/ErrorResponse"
53772
+ }
53773
+ }
53774
+ }
53775
+ }
53776
+ }
53777
+ }
53778
+ },
53779
+ "/api/agents/{id}/token": {
53780
+ "post": {
53781
+ "operationId": "agents_mintWorkerToken",
53782
+ "summary": "Mint an agent-bound worker token",
53783
+ "description": "Returns the token once. A worker runs on it in place of the swarm API key and acts only as this agent. Creates the agent when it does not exist and `name` is given. Fails with 409 when the agent already holds an active token.",
53784
+ "tags": [
53785
+ "Sessions"
53786
+ ],
53787
+ "security": [
53788
+ {
53789
+ "bearerAuth": []
53790
+ }
53791
+ ],
53792
+ "parameters": [
53793
+ {
53794
+ "schema": {
53795
+ "type": "string",
53796
+ "minLength": 1
53797
+ },
53798
+ "required": true,
53799
+ "name": "id",
53800
+ "in": "path"
53801
+ }
53802
+ ],
53803
+ "requestBody": {
53804
+ "content": {
53805
+ "application/json": {
53806
+ "schema": {
53807
+ "type": "object",
53808
+ "properties": {
53809
+ "name": {
53810
+ "type": "string",
53811
+ "minLength": 1
53812
+ },
53813
+ "ttlMs": {
53814
+ "type": "integer",
53815
+ "exclusiveMinimum": 0,
53816
+ "description": "Token lifetime in ms. Omit for the default (no expiry)."
53817
+ }
53818
+ },
53819
+ "additionalProperties": false
53820
+ }
53821
+ }
53822
+ }
53823
+ },
53824
+ "responses": {
53825
+ "200": {
53826
+ "description": "Minted worker token",
53827
+ "content": {
53828
+ "application/json": {
53829
+ "schema": {
53830
+ "type": "object",
53831
+ "properties": {
53832
+ "agentId": {
53833
+ "type": "string"
53834
+ },
53835
+ "tokenId": {
53836
+ "type": "string"
53837
+ },
53838
+ "plaintext": {
53839
+ "type": "string"
53840
+ },
53841
+ "expiresAt": {
53842
+ "type": [
53843
+ "string",
53844
+ "null"
53845
+ ],
53846
+ "description": "null when the token does not expire"
53847
+ },
53848
+ "agentCreated": {
53849
+ "type": "boolean"
53850
+ }
53851
+ },
53852
+ "required": [
53853
+ "agentId",
53854
+ "tokenId",
53855
+ "plaintext",
53856
+ "expiresAt",
53857
+ "agentCreated"
53858
+ ]
53859
+ }
53860
+ }
53861
+ }
53862
+ },
53863
+ "403": {
53864
+ "description": "Operator or user credentials required",
53865
+ "content": {
53866
+ "application/json": {
53867
+ "schema": {
53868
+ "$ref": "#/components/schemas/ErrorResponse"
53869
+ }
53870
+ }
53871
+ }
53872
+ },
53873
+ "404": {
53874
+ "description": "Agent not found and no name given",
53875
+ "content": {
53876
+ "application/json": {
53877
+ "schema": {
53878
+ "$ref": "#/components/schemas/ErrorResponse"
53879
+ }
53880
+ }
53881
+ }
53882
+ },
53883
+ "409": {
53884
+ "description": "Agent already holds an active token",
53885
+ "content": {
53886
+ "application/json": {
53887
+ "schema": {
53888
+ "$ref": "#/components/schemas/ErrorResponse"
53889
+ }
53890
+ }
53891
+ }
53892
+ }
53893
+ }
53894
+ },
53895
+ "delete": {
53896
+ "operationId": "agents_revokeWorkerToken",
53897
+ "summary": "Revoke an agent-bound worker token",
53898
+ "description": "Revokes every active worker token of the agent and the task tokens they minted. Open realtime connections on them close.",
53899
+ "tags": [
53900
+ "Sessions"
53901
+ ],
53902
+ "security": [
53903
+ {
53904
+ "bearerAuth": []
53905
+ }
53906
+ ],
53907
+ "parameters": [
53908
+ {
53909
+ "schema": {
53910
+ "type": "string",
53911
+ "minLength": 1
53912
+ },
53913
+ "required": true,
53914
+ "name": "id",
53915
+ "in": "path"
53916
+ }
53917
+ ],
53918
+ "responses": {
53919
+ "200": {
53920
+ "description": "Number of worker tokens revoked (0 when none was active)",
53921
+ "content": {
53922
+ "application/json": {
53923
+ "schema": {
53924
+ "type": "object",
53925
+ "properties": {
53926
+ "revoked": {
53927
+ "type": "integer"
53928
+ }
53929
+ },
53930
+ "required": [
53931
+ "revoked"
53932
+ ]
53933
+ }
53934
+ }
53935
+ }
53936
+ },
53937
+ "403": {
53938
+ "description": "Operator or user credentials required",
53939
+ "content": {
53940
+ "application/json": {
53941
+ "schema": {
53942
+ "$ref": "#/components/schemas/ErrorResponse"
53943
+ }
53944
+ }
53945
+ }
53946
+ }
53947
+ }
53948
+ }
53949
+ },
53950
+ "/api/agents/{id}/token/rotate": {
53951
+ "post": {
53952
+ "operationId": "agents_rotateWorkerToken",
53953
+ "summary": "Rotate an agent-bound worker token",
53954
+ "description": "Returns a new token once. The previous token keeps working for `graceSec` (default 300), then expires. Use revoke for a token that must stop now.",
53955
+ "tags": [
53956
+ "Sessions"
53957
+ ],
53958
+ "security": [
53959
+ {
53960
+ "bearerAuth": []
53961
+ }
53962
+ ],
53963
+ "parameters": [
53964
+ {
53965
+ "schema": {
53966
+ "type": "string",
53967
+ "minLength": 1
53968
+ },
53969
+ "required": true,
53970
+ "name": "id",
53971
+ "in": "path"
53972
+ }
53973
+ ],
53974
+ "requestBody": {
53975
+ "content": {
53976
+ "application/json": {
53977
+ "schema": {
53978
+ "type": "object",
53979
+ "properties": {
53980
+ "graceSec": {
53981
+ "type": "integer",
53982
+ "minimum": 0,
53983
+ "maximum": 86400
53984
+ },
53985
+ "ttlMs": {
53986
+ "type": "integer",
53987
+ "exclusiveMinimum": 0,
53988
+ "description": "Token lifetime in ms. Omit for the default (no expiry)."
53989
+ }
53990
+ },
53991
+ "additionalProperties": false
53992
+ }
53993
+ }
53994
+ }
53995
+ },
53996
+ "responses": {
53997
+ "200": {
53998
+ "description": "New worker token",
53999
+ "content": {
54000
+ "application/json": {
54001
+ "schema": {
54002
+ "type": "object",
54003
+ "properties": {
54004
+ "agentId": {
54005
+ "type": "string"
54006
+ },
54007
+ "tokenId": {
54008
+ "type": "string"
51542
54009
  },
51543
54010
  "plaintext": {
51544
54011
  "type": "string"
@@ -59262,10 +61729,15 @@
59262
61729
  },
59263
61730
  "/api/trackers/jira/authorize": {
59264
61731
  "get": {
59265
- "summary": "Redirect to Atlassian OAuth consent screen",
61732
+ "summary": "Start the Jira OAuth flow (admin): redirect to the consent screen, or return its URL",
59266
61733
  "tags": [
59267
61734
  "Trackers"
59268
61735
  ],
61736
+ "security": [
61737
+ {
61738
+ "bearerAuth": []
61739
+ }
61740
+ ],
59269
61741
  "parameters": [
59270
61742
  {
59271
61743
  "schema": {
@@ -59274,12 +61746,52 @@
59274
61746
  "required": false,
59275
61747
  "name": "redirect",
59276
61748
  "in": "query"
61749
+ },
61750
+ {
61751
+ "schema": {
61752
+ "type": "string",
61753
+ "enum": [
61754
+ "redirect",
61755
+ "json"
61756
+ ]
61757
+ },
61758
+ "required": false,
61759
+ "name": "format",
61760
+ "in": "query"
59277
61761
  }
59278
61762
  ],
59279
61763
  "responses": {
61764
+ "200": {
61765
+ "description": "Consent URL (format=json), for clients that navigate themselves",
61766
+ "content": {
61767
+ "application/json": {
61768
+ "schema": {
61769
+ "type": "object",
61770
+ "properties": {
61771
+ "authorizeUrl": {
61772
+ "type": "string"
61773
+ }
61774
+ },
61775
+ "required": [
61776
+ "authorizeUrl"
61777
+ ]
61778
+ }
61779
+ }
61780
+ }
61781
+ },
59280
61782
  "302": {
59281
61783
  "description": "Redirect to Atlassian OAuth"
59282
61784
  },
61785
+ "403": {
61786
+ "description": "Caller lacks oauth-authorization.manage",
61787
+ "content": {
61788
+ "application/json": {
61789
+ "schema": {
61790
+ "$ref": "#/components/schemas/ErrorResponse"
61791
+ }
61792
+ }
61793
+ }
61794
+ },
59283
61795
  "500": {
59284
61796
  "description": "Failed to generate authorization URL",
59285
61797
  "content": {
@@ -59945,10 +62457,15 @@
59945
62457
  },
59946
62458
  "/api/trackers/linear/authorize": {
59947
62459
  "get": {
59948
- "summary": "Redirect to Linear OAuth consent screen",
62460
+ "summary": "Start the Linear OAuth flow (admin): redirect to the consent screen, or return its URL",
59949
62461
  "tags": [
59950
62462
  "Trackers"
59951
62463
  ],
62464
+ "security": [
62465
+ {
62466
+ "bearerAuth": []
62467
+ }
62468
+ ],
59952
62469
  "parameters": [
59953
62470
  {
59954
62471
  "schema": {
@@ -59957,12 +62474,52 @@
59957
62474
  "required": false,
59958
62475
  "name": "redirect",
59959
62476
  "in": "query"
62477
+ },
62478
+ {
62479
+ "schema": {
62480
+ "type": "string",
62481
+ "enum": [
62482
+ "redirect",
62483
+ "json"
62484
+ ]
62485
+ },
62486
+ "required": false,
62487
+ "name": "format",
62488
+ "in": "query"
59960
62489
  }
59961
62490
  ],
59962
62491
  "responses": {
62492
+ "200": {
62493
+ "description": "Consent URL (format=json), for clients that navigate themselves",
62494
+ "content": {
62495
+ "application/json": {
62496
+ "schema": {
62497
+ "type": "object",
62498
+ "properties": {
62499
+ "authorizeUrl": {
62500
+ "type": "string"
62501
+ }
62502
+ },
62503
+ "required": [
62504
+ "authorizeUrl"
62505
+ ]
62506
+ }
62507
+ }
62508
+ }
62509
+ },
59963
62510
  "302": {
59964
62511
  "description": "Redirect to Linear OAuth"
59965
62512
  },
62513
+ "403": {
62514
+ "description": "Caller lacks oauth-authorization.manage",
62515
+ "content": {
62516
+ "application/json": {
62517
+ "schema": {
62518
+ "$ref": "#/components/schemas/ErrorResponse"
62519
+ }
62520
+ }
62521
+ }
62522
+ },
59966
62523
  "500": {
59967
62524
  "description": "Failed to generate authorization URL",
59968
62525
  "content": {