@desplega.ai/agent-swarm 2.8.0 → 2.8.2

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 (216) hide show
  1. package/dist/{acp-adapter-t949vbbp.js → acp-adapter-fqzkxyra.js} +3 -3
  2. package/dist/{actions-7e9czc7s.js → actions-kxek041g.js} +18 -18
  3. package/dist/{amp-adapter-gv6cbb7d.js → amp-adapter-ce7jjke4.js} +1 -1
  4. package/dist/{app-b9fbkp9v.js → app-v6zz8yh0.js} +3 -3
  5. package/dist/{assistant-wjb7v4c7.js → assistant-m0sw9xx2.js} +19 -19
  6. package/dist/{boot-args-schema-2t37e0fe.js → boot-args-schema-66bk37wv.js} +1 -1
  7. package/dist/{boot-reembed-gka3zas7.js → boot-reembed-edjpwsc1.js} +1 -1
  8. package/dist/{boot-reembed-a35nkyr1.js → boot-reembed-y27n09tz.js} +1 -1
  9. package/dist/{boot-scrub-sweep-65sdnp6c.js → boot-scrub-sweep-1xc35965.js} +3 -3
  10. package/dist/{boot-seeds-x42tzytw.js → boot-seeds-7hjj91qj.js} +4 -4
  11. package/dist/{boxd-qbkxy6ap.js → boxd-ent8ch04.js} +1 -1
  12. package/dist/{claude-adapter-v221b2fd.js → claude-adapter-stw7jdcf.js} +3 -3
  13. package/dist/{claude-managed-adapter-29eq09wd.js → claude-managed-adapter-jh6c523j.js} +2 -2
  14. package/dist/{claude-managed-setup-9m6450zk.js → claude-managed-setup-y6z2perp.js} +5 -5
  15. package/dist/{claude-sdk-session-0q0ptaba.js → claude-sdk-session-vvya8wqk.js} +3 -3
  16. package/dist/{cli-wk18cm92.js → cli-0cq8y6m7.js} +1 -1
  17. package/dist/{cli-p1w18yhx.js → cli-1pz0330a.js} +1 -1
  18. package/dist/{cli-y97qxcfx.js → cli-1qkz151v.js} +3 -3
  19. package/dist/{cli-qwca7s44.js → cli-26ctbcdp.js} +18 -6
  20. package/dist/{cli-8fknbnhw.js → cli-2kvhc7x8.js} +7 -7
  21. package/dist/{cli-rfywm85n.js → cli-3e875j5p.js} +136 -49
  22. package/dist/{cli-6wxjceza.js → cli-3sy2xags.js} +10 -10
  23. package/dist/{cli-a7wvp2km.js → cli-3vmb0n58.js} +1 -1
  24. package/dist/{cli-p1bq50aa.js → cli-4vzgeta4.js} +13 -13
  25. package/dist/{cli-m28atx8q.js → cli-5y340nzn.js} +4 -4
  26. package/dist/{cli-7p1kvkck.js → cli-6rc5frdm.js} +1 -1
  27. package/dist/{cli-tph5wt3y.js → cli-6wj7p986.js} +1 -1
  28. package/dist/{cli-t73cas91.js → cli-7349va39.js} +8100 -7620
  29. package/dist/{cli-ee0b971j.js → cli-837vfs2x.js} +2 -2
  30. package/dist/{cli-abejgen1.js → cli-959kp5h2.js} +12 -11
  31. package/dist/{cli-8kzasymh.js → cli-97ae65rz.js} +4 -4
  32. package/dist/{cli-m4dqmnbp.js → cli-9mb2q6pb.js} +1 -1
  33. package/dist/{cli-p2gfst4m.js → cli-a0z912j7.js} +123 -35
  34. package/dist/{cli-4txa0ter.js → cli-b98a65ed.js} +3 -3
  35. package/dist/{cli-k0wwfqbg.js → cli-dns0y538.js} +4 -0
  36. package/dist/{cli-tk7cjj8h.js → cli-dzpc6en0.js} +1 -1
  37. package/dist/{cli-qa4wdgsy.js → cli-e1p3n5gq.js} +4 -4
  38. package/dist/{cli-gxkx0zzp.js → cli-f4e8r23x.js} +1 -1
  39. package/dist/{cli-qmqk2yc2.js → cli-f4r3g076.js} +1 -1
  40. package/dist/{cli-wcg8x116.js → cli-f6bahpn5.js} +1 -1
  41. package/dist/{cli-qsnnd04k.js → cli-fpjmegdb.js} +1 -1
  42. package/dist/{cli-j790gp2w.js → cli-fwy8kfd6.js} +271 -37
  43. package/dist/{cli-rmmpt0wm.js → cli-g5mtmf6t.js} +6 -6
  44. package/dist/{cli-rzsy6nc6.js → cli-gyt3zydq.js} +3 -3
  45. package/dist/{cli-pasjcnmj.js → cli-j24zbska.js} +3 -3
  46. package/dist/{cli-qfedvmcr.js → cli-jdknh18m.js} +10 -10
  47. package/dist/{cli-7b8sbmag.js → cli-kjtwrhea.js} +1 -1
  48. package/dist/{cli-gpwhbgx0.js → cli-m9s2qff2.js} +57 -25
  49. package/dist/{cli-2wnq8jkz.js → cli-mxn1qvbn.js} +3 -2
  50. package/dist/{cli-s7t6p9my.js → cli-n6vtrcht.js} +1 -1
  51. package/dist/{cli-2zp0et3v.js → cli-pchypa1s.js} +55 -19
  52. package/dist/{cli-yq3zak69.js → cli-pfs8adn4.js} +1 -1
  53. package/dist/{cli-c55z5chy.js → cli-q24n86d2.js} +2 -2
  54. package/dist/{cli-h38x262p.js → cli-rcecc3yq.js} +167 -43
  55. package/dist/{cli-xae4g51r.js → cli-rh15cakt.js} +1 -1
  56. package/dist/{cli-sdtt3men.js → cli-rmzsadkf.js} +1 -1
  57. package/dist/{cli-f3vq58d2.js → cli-t2tma8gb.js} +1 -1
  58. package/dist/{cli-m23zjcy2.js → cli-tekytdq9.js} +2 -2
  59. package/dist/{cli-tqegb8eq.js → cli-vdektqgf.js} +1 -1
  60. package/dist/{cli-ffhtssbp.js → cli-vj75tyaw.js} +1 -1
  61. package/dist/{cli-deefvewm.js → cli-w401b9tq.js} +1 -1
  62. package/dist/{cli-n9ftpys4.js → cli-x6t50dmw.js} +7 -7
  63. package/dist/{cli-6t09sdhy.js → cli-xf3qw745.js} +3 -3
  64. package/dist/{cli-hxpyc9sn.js → cli-z1w943va.js} +2 -2
  65. package/dist/{cli-334z18y3.js → cli-zh9rsbqf.js} +3 -3
  66. package/dist/cli.js +17 -17
  67. package/dist/{codex-adapter-30j9bpzd.js → codex-adapter-zerf5qsp.js} +1 -1
  68. package/dist/{codex-hook-h3vk6xzr.js → codex-hook-30gyhzxe.js} +1 -1
  69. package/dist/{codex-session-runner-8vp57v8w.js → codex-session-runner-89s304py.js} +1 -1
  70. package/dist/{commands-bngnz9g7.js → commands-jeh1b51j.js} +3 -3
  71. package/dist/{controller-hxx8wwy1.js → controller-mctfbrse.js} +3 -3
  72. package/dist/{controllers-connect-e2b4gyxc.js → controllers-connect-nxa1ddwn.js} +19 -19
  73. package/dist/{cursor-adapter-n5nc3mfe.js → cursor-adapter-qj8vehv6.js} +1 -1
  74. package/dist/{db-bgm7vkc0.js → db-2dvay0es.js} +3 -3
  75. package/dist/{db-c6np41ca.js → db-b36qn6k3.js} +2 -2
  76. package/dist/{dispatcher-jnybck15.js → dispatcher-gndbta01.js} +17 -17
  77. package/dist/{dsh-adapter-nrhbrjz8.js → dsh-adapter-f75sz821.js} +1 -1
  78. package/dist/{e2b-jkwfhbcv.js → e2b-3gpc2n3w.js} +1 -1
  79. package/dist/{e2b-s16txnpx.js → e2b-jbm7mj93.js} +1 -1
  80. package/dist/{embedding-space-crsm2zp0.js → embedding-space-4p05vb2x.js} +6 -6
  81. package/dist/{embeddings-e7z3f27f.js → embeddings-m6768mgh.js} +1 -1
  82. package/dist/{external-channel-m77wf5z3.js → external-channel-gjv3jne3.js} +2 -2
  83. package/dist/{fx-adapter-b6w0kf56.js → fx-adapter-rpsgb1tw.js} +4 -4
  84. package/dist/{grok-adapter-4sqtebdk.js → grok-adapter-n2m3zjg1.js} +4 -4
  85. package/dist/handlers-nv8edn19.js +32 -0
  86. package/dist/{heartbeat-xgb036sx.js → heartbeat-a1tv60gt.js} +20 -20
  87. package/dist/{hook-xsk1jbha.js → hook-8h5dzcgq.js} +2 -2
  88. package/dist/{hook-5h02c9ga.js → hook-cyaps9ba.js} +4 -4
  89. package/dist/{http-txe7qhvn.js → http-t15mhbd9.js} +1733 -79
  90. package/dist/{index-0eny15vj.js → index-2skqtd76.js} +2 -2
  91. package/dist/{index-w7em4ktq.js → index-d6wkh8ar.js} +2 -2
  92. package/dist/{index-rvccek1w.js → index-gjwaqaq8.js} +5 -5
  93. package/dist/{index-e5pfbsys.js → index-hjhfk3ra.js} +3 -3
  94. package/dist/{index-1qw6f2dc.js → index-khe3gp0k.js} +4 -4
  95. package/dist/index-ksmyd6kc.js +37 -0
  96. package/dist/{index-vk63emp7.js → index-qav6455f.js} +14 -12
  97. package/dist/index-rjnrje98.js +32 -0
  98. package/dist/index-tv3413wy.js +33 -0
  99. package/dist/{index-ysvbhg5m.js → index-w1zqf680.js} +1 -1
  100. package/dist/{keepalive-4zsrce78.js → keepalive-91s7hzrb.js} +3 -3
  101. package/dist/lead-3hmddvrm.js +70 -0
  102. package/dist/{maintenance-86jvartk.js → maintenance-7pjmy5xy.js} +1 -1
  103. package/dist/{node-je82wjet.js → node-4c5jqxr3.js} +1 -1
  104. package/dist/{oauth-refresh-sweep-j52kg9pr.js → oauth-refresh-sweep-rzqfm94j.js} +2 -2
  105. package/dist/{onboard-c2aj5p8q.js → onboard-74st7pag.js} +3 -3
  106. package/dist/{opencode-adapter-dsagkhtw.js → opencode-adapter-arn7gm8q.js} +2 -2
  107. package/dist/{otel-impl-yyy203z8.js → otel-impl-rnzey8cb.js} +1 -1
  108. package/dist/{pi-mono-adapter-546cd1cc.js → pi-mono-adapter-6mkwq64n.js} +3 -2
  109. package/dist/{pricing-refresh-1rgzqyzz.js → pricing-refresh-ha21jhk7.js} +2 -2
  110. package/dist/{rbac-roles-e70xfeyj.js → rbac-roles-59dxachk.js} +2 -2
  111. package/dist/{rbac-roles-q89qe8er.js → rbac-roles-wqhma4dr.js} +3 -3
  112. package/dist/{render-v2-k6tt107q.js → render-v2-14kpzx12.js} +3 -3
  113. package/dist/{resume-cnnrjfxa.js → resume-gsa5fb5f.js} +6 -6
  114. package/dist/{session-access-xkxkjw3n.js → session-access-skm7bnp6.js} +4 -4
  115. package/dist/{session-source-backfill-1d5pdwww.js → session-source-backfill-pbqzbncv.js} +2 -2
  116. package/dist/{setup-se8q7gkc.js → setup-5yermsem.js} +1 -1
  117. package/dist/{work-objects-1kxnbzy5.js → work-objects-xj0ck0w4.js} +20 -20
  118. package/dist/{worker-follow-up-zqm8apt4.js → worker-follow-up-911xc0b8.js} +19 -17
  119. package/dist/worker-qgg0m2gw.js +70 -0
  120. package/openapi.json +1741 -290
  121. package/package.json +3 -3
  122. package/src/apps/catalog.generated.json +120 -1
  123. package/src/apps/definition.ts +38 -11
  124. package/src/apps/page-validator.ts +88 -0
  125. package/src/be/db/model-profiles.ts +110 -11
  126. package/src/be/db/tasks/read.ts +20 -0
  127. package/src/be/db/workflow-run-definitions.ts +19 -8
  128. package/src/be/db-client.ts +43 -5
  129. package/src/be/db.ts +9 -3
  130. package/src/be/migrations/284_model_profile_fallbacks.sql +9 -0
  131. package/src/be/model-profile-check.ts +43 -18
  132. package/src/be/runtime-pools/routing.ts +1 -0
  133. package/src/be/savings/calibrate.ts +468 -0
  134. package/src/be/savings/compute.ts +182 -0
  135. package/src/be/savings/model.ts +406 -0
  136. package/src/be/scripts/typecheck.ts +5 -0
  137. package/src/be/seed/agent-fs-provision.ts +48 -11
  138. package/src/be/seed/workflows-seeder.ts +67 -23
  139. package/src/be/skill-parser.ts +19 -7
  140. package/src/commands/onboard/agent-fs-version.ts +1 -1
  141. package/src/commands/provider-error-class.ts +97 -0
  142. package/src/commands/runner.ts +99 -17
  143. package/src/extensions/contract-types.generated.ts +1 -1
  144. package/src/http/all-routes.ts +2 -0
  145. package/src/http/fs.ts +8 -2
  146. package/src/http/index.ts +4 -0
  147. package/src/http/model-profiles.ts +43 -10
  148. package/src/http/poll.ts +1 -0
  149. package/src/http/savings-calibration.ts +277 -0
  150. package/src/http/savings.ts +363 -0
  151. package/src/http/tasks.ts +46 -4
  152. package/src/http/trackers/authorize-gate.ts +41 -0
  153. package/src/http/trackers/jira.ts +26 -4
  154. package/src/http/trackers/linear.ts +26 -4
  155. package/src/integrations/chat-sdk/limits.ts +6 -1
  156. package/src/jira/oauth.ts +7 -1
  157. package/src/linear/README.md +2 -1
  158. package/src/linear/oauth.ts +7 -1
  159. package/src/providers/amp-adapter.ts +1 -1
  160. package/src/providers/codex-adapter.ts +3 -0
  161. package/src/providers/pi-mono-adapter.ts +6 -5
  162. package/src/providers/types.ts +7 -0
  163. package/src/scripts-runtime/eval-harness.ts +14 -1
  164. package/src/scripts-runtime/executors/types.ts +3 -0
  165. package/src/scripts-runtime/sdk-allowlist.ts +11 -1
  166. package/src/scripts-runtime/swarm-sdk.ts +6 -0
  167. package/src/scripts-runtime/types/stdlib.d.ts +9 -0
  168. package/src/scripts-runtime/types/swarm-extension.d.ts +34 -0
  169. package/src/scripts-runtime/types/swarm-sdk.d.ts +9 -0
  170. package/src/tasks/worker-follow-up.ts +142 -3
  171. package/src/tests/agent-fs-provision-seeder.test.ts +81 -0
  172. package/src/tests/apps-chart-shell.test.ts +170 -0
  173. package/src/tests/apps-icon.test.ts +156 -2
  174. package/src/tests/chat-sdk-relay.test.ts +12 -0
  175. package/src/tests/codex-adapter.test.ts +11 -0
  176. package/src/tests/comb-default.test.ts +6 -0
  177. package/src/tests/core-auth.test.ts +7 -6
  178. package/src/tests/db-client-busy-retry.test.ts +58 -6
  179. package/src/tests/deploy-guard.test.ts +154 -0
  180. package/src/tests/docs-index-footprint.test.js +3 -3
  181. package/src/tests/fixtures/app-shell-charts-definition.json.txt +180 -0
  182. package/src/tests/mcp-tools.test.ts +1 -1
  183. package/src/tests/model-profile-fallbacks.test.ts +482 -0
  184. package/src/tests/model-profiles-api.test.ts +1 -0
  185. package/src/tests/pi-mono-session-cost-on-abort.test.ts +115 -0
  186. package/src/tests/provider-error-class.test.ts +174 -0
  187. package/src/tests/runner-provider-fallback.test.ts +197 -0
  188. package/src/tests/savings-calibration-api.test.ts +264 -0
  189. package/src/tests/savings-calibration.test.ts +201 -0
  190. package/src/tests/savings-compute.test.ts +406 -0
  191. package/src/tests/savings-model.test.ts +287 -0
  192. package/src/tests/script-connections.test.ts +2 -0
  193. package/src/tests/script-native-unawaited-drain.test.ts +167 -0
  194. package/src/tests/sdk-allowlist.test.ts +40 -0
  195. package/src/tests/seed-workflows.test.ts +167 -11
  196. package/src/tests/skill-parser.test.ts +45 -0
  197. package/src/tests/tracker-oauth-authorize-auth.test.ts +262 -0
  198. package/src/tests/workflow-definition-pinning.test.ts +128 -3
  199. package/src/tests/workflow-script-principal.test.ts +94 -4
  200. package/src/tools/app-upsert.ts +1 -1
  201. package/src/tools/model-profiles/list-model-profiles.ts +4 -2
  202. package/src/tools/script-run.ts +1 -1
  203. package/src/tools/update-profile.ts +1 -1
  204. package/src/types.ts +115 -33
  205. package/src/utils/constants.ts +2 -0
  206. package/templates/skills/apps/SKILL.md +62 -3
  207. package/templates/skills/apps/content.md +62 -3
  208. package/templates/skills/swarm-docs/content.md +2 -0
  209. package/templates/skills/swarm-scripts/SKILL.md +1 -1
  210. package/templates/skills/swarm-scripts/content.md +1 -1
  211. package/dist/handlers-kdjcyzdj.js +0 -32
  212. package/dist/index-835xdgnm.js +0 -33
  213. package/dist/index-d469300x.js +0 -37
  214. package/dist/index-rzqwp11g.js +0 -32
  215. package/dist/lead-yqt47dkr.js +0 -70
  216. package/dist/worker-j6xxtq7p.js +0 -70
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.0",
5
+ "version": "2.8.2",
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": [
@@ -399,6 +399,60 @@
399
399
  "resolvedProfile": {
400
400
  "type": "string"
401
401
  },
402
+ "fallbackHops": {
403
+ "type": "array",
404
+ "items": {
405
+ "type": "object",
406
+ "properties": {
407
+ "from": {
408
+ "type": "string"
409
+ },
410
+ "profile": {
411
+ "type": "string"
412
+ },
413
+ "errorClass": {
414
+ "type": "string",
415
+ "enum": [
416
+ "rate_limit",
417
+ "model_window",
418
+ "seat",
419
+ "credits",
420
+ "overloaded",
421
+ "server_error",
422
+ "auth",
423
+ "pool_empty"
424
+ ]
425
+ },
426
+ "at": {
427
+ "type": "string"
428
+ },
429
+ "skipped": {
430
+ "type": "array",
431
+ "items": {
432
+ "type": "object",
433
+ "properties": {
434
+ "profile": {
435
+ "type": "string"
436
+ },
437
+ "reason": {
438
+ "type": "string"
439
+ }
440
+ },
441
+ "required": [
442
+ "profile",
443
+ "reason"
444
+ ]
445
+ }
446
+ }
447
+ },
448
+ "required": [
449
+ "from",
450
+ "profile",
451
+ "errorClass",
452
+ "at"
453
+ ]
454
+ }
455
+ },
402
456
  "scheduleId": {
403
457
  "type": "string"
404
458
  },
@@ -1253,6 +1307,54 @@
1253
1307
  "type",
1254
1308
  "icon"
1255
1309
  ]
1310
+ },
1311
+ {
1312
+ "type": "object",
1313
+ "properties": {
1314
+ "type": {
1315
+ "type": "string",
1316
+ "enum": [
1317
+ "url"
1318
+ ]
1319
+ },
1320
+ "url": {
1321
+ "type": "string",
1322
+ "maxLength": 2048,
1323
+ "format": "uri"
1324
+ }
1325
+ },
1326
+ "required": [
1327
+ "type",
1328
+ "url"
1329
+ ]
1330
+ },
1331
+ {
1332
+ "type": "object",
1333
+ "properties": {
1334
+ "type": {
1335
+ "type": "string",
1336
+ "enum": [
1337
+ "agent-fs"
1338
+ ]
1339
+ },
1340
+ "path": {
1341
+ "type": "string",
1342
+ "minLength": 2,
1343
+ "maxLength": 1024
1344
+ },
1345
+ "orgId": {
1346
+ "type": "string",
1347
+ "minLength": 1
1348
+ },
1349
+ "driveId": {
1350
+ "type": "string",
1351
+ "minLength": 1
1352
+ }
1353
+ },
1354
+ "required": [
1355
+ "type",
1356
+ "path"
1357
+ ]
1256
1358
  }
1257
1359
  ]
1258
1360
  },
@@ -7593,6 +7695,54 @@
7593
7695
  "type",
7594
7696
  "icon"
7595
7697
  ]
7698
+ },
7699
+ {
7700
+ "type": "object",
7701
+ "properties": {
7702
+ "type": {
7703
+ "type": "string",
7704
+ "enum": [
7705
+ "url"
7706
+ ]
7707
+ },
7708
+ "url": {
7709
+ "type": "string",
7710
+ "maxLength": 2048,
7711
+ "format": "uri"
7712
+ }
7713
+ },
7714
+ "required": [
7715
+ "type",
7716
+ "url"
7717
+ ]
7718
+ },
7719
+ {
7720
+ "type": "object",
7721
+ "properties": {
7722
+ "type": {
7723
+ "type": "string",
7724
+ "enum": [
7725
+ "agent-fs"
7726
+ ]
7727
+ },
7728
+ "path": {
7729
+ "type": "string",
7730
+ "minLength": 2,
7731
+ "maxLength": 1024
7732
+ },
7733
+ "orgId": {
7734
+ "type": "string",
7735
+ "minLength": 1
7736
+ },
7737
+ "driveId": {
7738
+ "type": "string",
7739
+ "minLength": 1
7740
+ }
7741
+ },
7742
+ "required": [
7743
+ "type",
7744
+ "path"
7745
+ ]
7596
7746
  }
7597
7747
  ]
7598
7748
  },
@@ -12070,6 +12220,54 @@
12070
12220
  "icon"
12071
12221
  ]
12072
12222
  },
12223
+ {
12224
+ "type": "object",
12225
+ "properties": {
12226
+ "type": {
12227
+ "type": "string",
12228
+ "enum": [
12229
+ "url"
12230
+ ]
12231
+ },
12232
+ "url": {
12233
+ "type": "string",
12234
+ "maxLength": 2048,
12235
+ "format": "uri"
12236
+ }
12237
+ },
12238
+ "required": [
12239
+ "type",
12240
+ "url"
12241
+ ]
12242
+ },
12243
+ {
12244
+ "type": "object",
12245
+ "properties": {
12246
+ "type": {
12247
+ "type": "string",
12248
+ "enum": [
12249
+ "agent-fs"
12250
+ ]
12251
+ },
12252
+ "path": {
12253
+ "type": "string",
12254
+ "minLength": 2,
12255
+ "maxLength": 1024
12256
+ },
12257
+ "orgId": {
12258
+ "type": "string",
12259
+ "minLength": 1
12260
+ },
12261
+ "driveId": {
12262
+ "type": "string",
12263
+ "minLength": 1
12264
+ }
12265
+ },
12266
+ "required": [
12267
+ "type",
12268
+ "path"
12269
+ ]
12270
+ },
12073
12271
  {
12074
12272
  "type": "null"
12075
12273
  }
@@ -22818,7 +23016,7 @@
22818
23016
  "/api/fs/members/invite": {
22819
23017
  "post": {
22820
23018
  "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.",
23019
+ "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
23020
  "tags": [
22823
23021
  "FS"
22824
23022
  ],
@@ -22876,7 +23074,7 @@
22876
23074
  "added",
22877
23075
  "pending"
22878
23076
  ],
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."
23077
+ "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
23078
  },
22881
23079
  "inviteId": {
22882
23080
  "type": "string",
@@ -22889,6 +23087,10 @@
22889
23087
  "acceptUrl": {
22890
23088
  "type": "string",
22891
23089
  "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."
23090
+ },
23091
+ "token": {
23092
+ "type": "string",
23093
+ "description": "Accept token (status pending). Only the invited account can redeem it, with its own key: agent-fs POST /invites/{token}/accept."
22892
23094
  }
22893
23095
  },
22894
23096
  "required": [
@@ -28380,6 +28582,12 @@
28380
28582
  "minItems": 1
28381
28583
  }
28382
28584
  },
28585
+ "fallbacks": {
28586
+ "type": "array",
28587
+ "items": {
28588
+ "type": "string"
28589
+ }
28590
+ },
28383
28591
  "createdAt": {
28384
28592
  "type": "string"
28385
28593
  },
@@ -28397,6 +28605,7 @@
28397
28605
  "description",
28398
28606
  "seededFrom",
28399
28607
  "credentials",
28608
+ "fallbacks",
28400
28609
  "createdAt",
28401
28610
  "lastUpdatedAt"
28402
28611
  ]
@@ -28414,7 +28623,7 @@
28414
28623
  },
28415
28624
  "post": {
28416
28625
  "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).",
28626
+ "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
28627
  "tags": [
28419
28628
  "Models"
28420
28629
  ],
@@ -28494,6 +28703,14 @@
28494
28703
  },
28495
28704
  "minItems": 1
28496
28705
  }
28706
+ },
28707
+ "fallbacks": {
28708
+ "type": "array",
28709
+ "items": {
28710
+ "type": "string",
28711
+ "pattern": "^[a-z0-9][a-z0-9._-]{0,99}$"
28712
+ },
28713
+ "maxItems": 10
28497
28714
  }
28498
28715
  },
28499
28716
  "required": [
@@ -28584,161 +28801,10 @@
28584
28801
  "minItems": 1
28585
28802
  }
28586
28803
  },
28587
- "createdAt": {
28588
- "type": "string"
28589
- },
28590
- "lastUpdatedAt": {
28591
- "type": "string"
28592
- }
28593
- },
28594
- "required": [
28595
- "id",
28596
- "name",
28597
- "harness",
28598
- "model",
28599
- "effort",
28600
- "allowCustomModel",
28601
- "description",
28602
- "seededFrom",
28603
- "credentials",
28604
- "createdAt",
28605
- "lastUpdatedAt"
28606
- ]
28607
- }
28608
- }
28609
- }
28610
- },
28611
- "400": {
28612
- "description": "Validation error",
28613
- "content": {
28614
- "application/json": {
28615
- "schema": {
28616
- "$ref": "#/components/schemas/ErrorResponse"
28617
- }
28618
- }
28619
- }
28620
- },
28621
- "403": {
28622
- "description": "Forbidden",
28623
- "content": {
28624
- "application/json": {
28625
- "schema": {
28626
- "$ref": "#/components/schemas/ErrorResponse"
28627
- }
28628
- }
28629
- }
28630
- },
28631
- "409": {
28632
- "description": "A profile with that name exists",
28633
- "content": {
28634
- "application/json": {
28635
- "schema": {
28636
- "$ref": "#/components/schemas/ErrorResponse"
28637
- }
28638
- }
28639
- }
28640
- }
28641
- }
28642
- }
28643
- },
28644
- "/api/model-profiles/{name}": {
28645
- "get": {
28646
- "summary": "Get one model profile",
28647
- "tags": [
28648
- "Models"
28649
- ],
28650
- "security": [
28651
- {
28652
- "bearerAuth": []
28653
- }
28654
- ],
28655
- "parameters": [
28656
- {
28657
- "schema": {
28658
- "type": "string"
28659
- },
28660
- "required": true,
28661
- "name": "name",
28662
- "in": "path"
28663
- }
28664
- ],
28665
- "responses": {
28666
- "200": {
28667
- "description": "The model profile",
28668
- "content": {
28669
- "application/json": {
28670
- "schema": {
28671
- "type": "object",
28672
- "properties": {
28673
- "id": {
28674
- "type": "string"
28675
- },
28676
- "name": {
28677
- "type": "string"
28678
- },
28679
- "harness": {
28680
- "type": "string",
28681
- "enum": [
28682
- "claude",
28683
- "codex",
28684
- "pi",
28685
- "devin",
28686
- "claude-managed",
28687
- "opencode",
28688
- "acp",
28689
- "dsh",
28690
- "amp",
28691
- "cursor",
28692
- "grok",
28693
- "fx"
28694
- ]
28695
- },
28696
- "model": {
28697
- "type": "string"
28698
- },
28699
- "effort": {
28700
- "type": [
28701
- "string",
28702
- "null"
28703
- ],
28704
- "enum": [
28705
- "off",
28706
- "low",
28707
- "medium",
28708
- "high",
28709
- "xhigh",
28710
- "max",
28711
- null
28712
- ]
28713
- },
28714
- "allowCustomModel": {
28715
- "type": "boolean"
28716
- },
28717
- "description": {
28718
- "type": [
28719
- "string",
28720
- "null"
28721
- ]
28722
- },
28723
- "seededFrom": {
28724
- "type": [
28725
- "string",
28726
- "null"
28727
- ]
28728
- },
28729
- "credentials": {
28730
- "type": [
28731
- "object",
28732
- "null"
28733
- ],
28734
- "additionalProperties": {
28735
- "type": "array",
28736
- "items": {
28737
- "type": "string",
28738
- "minLength": 5,
28739
- "maxLength": 5
28740
- },
28741
- "minItems": 1
28804
+ "fallbacks": {
28805
+ "type": "array",
28806
+ "items": {
28807
+ "type": "string"
28742
28808
  }
28743
28809
  },
28744
28810
  "createdAt": {
@@ -28758,6 +28824,171 @@
28758
28824
  "description",
28759
28825
  "seededFrom",
28760
28826
  "credentials",
28827
+ "fallbacks",
28828
+ "createdAt",
28829
+ "lastUpdatedAt"
28830
+ ]
28831
+ }
28832
+ }
28833
+ }
28834
+ },
28835
+ "400": {
28836
+ "description": "Validation error",
28837
+ "content": {
28838
+ "application/json": {
28839
+ "schema": {
28840
+ "$ref": "#/components/schemas/ErrorResponse"
28841
+ }
28842
+ }
28843
+ }
28844
+ },
28845
+ "403": {
28846
+ "description": "Forbidden",
28847
+ "content": {
28848
+ "application/json": {
28849
+ "schema": {
28850
+ "$ref": "#/components/schemas/ErrorResponse"
28851
+ }
28852
+ }
28853
+ }
28854
+ },
28855
+ "409": {
28856
+ "description": "A profile with that name exists",
28857
+ "content": {
28858
+ "application/json": {
28859
+ "schema": {
28860
+ "$ref": "#/components/schemas/ErrorResponse"
28861
+ }
28862
+ }
28863
+ }
28864
+ }
28865
+ }
28866
+ }
28867
+ },
28868
+ "/api/model-profiles/{name}": {
28869
+ "get": {
28870
+ "summary": "Get one model profile",
28871
+ "tags": [
28872
+ "Models"
28873
+ ],
28874
+ "security": [
28875
+ {
28876
+ "bearerAuth": []
28877
+ }
28878
+ ],
28879
+ "parameters": [
28880
+ {
28881
+ "schema": {
28882
+ "type": "string"
28883
+ },
28884
+ "required": true,
28885
+ "name": "name",
28886
+ "in": "path"
28887
+ }
28888
+ ],
28889
+ "responses": {
28890
+ "200": {
28891
+ "description": "The model profile",
28892
+ "content": {
28893
+ "application/json": {
28894
+ "schema": {
28895
+ "type": "object",
28896
+ "properties": {
28897
+ "id": {
28898
+ "type": "string"
28899
+ },
28900
+ "name": {
28901
+ "type": "string"
28902
+ },
28903
+ "harness": {
28904
+ "type": "string",
28905
+ "enum": [
28906
+ "claude",
28907
+ "codex",
28908
+ "pi",
28909
+ "devin",
28910
+ "claude-managed",
28911
+ "opencode",
28912
+ "acp",
28913
+ "dsh",
28914
+ "amp",
28915
+ "cursor",
28916
+ "grok",
28917
+ "fx"
28918
+ ]
28919
+ },
28920
+ "model": {
28921
+ "type": "string"
28922
+ },
28923
+ "effort": {
28924
+ "type": [
28925
+ "string",
28926
+ "null"
28927
+ ],
28928
+ "enum": [
28929
+ "off",
28930
+ "low",
28931
+ "medium",
28932
+ "high",
28933
+ "xhigh",
28934
+ "max",
28935
+ null
28936
+ ]
28937
+ },
28938
+ "allowCustomModel": {
28939
+ "type": "boolean"
28940
+ },
28941
+ "description": {
28942
+ "type": [
28943
+ "string",
28944
+ "null"
28945
+ ]
28946
+ },
28947
+ "seededFrom": {
28948
+ "type": [
28949
+ "string",
28950
+ "null"
28951
+ ]
28952
+ },
28953
+ "credentials": {
28954
+ "type": [
28955
+ "object",
28956
+ "null"
28957
+ ],
28958
+ "additionalProperties": {
28959
+ "type": "array",
28960
+ "items": {
28961
+ "type": "string",
28962
+ "minLength": 5,
28963
+ "maxLength": 5
28964
+ },
28965
+ "minItems": 1
28966
+ }
28967
+ },
28968
+ "fallbacks": {
28969
+ "type": "array",
28970
+ "items": {
28971
+ "type": "string"
28972
+ }
28973
+ },
28974
+ "createdAt": {
28975
+ "type": "string"
28976
+ },
28977
+ "lastUpdatedAt": {
28978
+ "type": "string"
28979
+ }
28980
+ },
28981
+ "required": [
28982
+ "id",
28983
+ "name",
28984
+ "harness",
28985
+ "model",
28986
+ "effort",
28987
+ "allowCustomModel",
28988
+ "description",
28989
+ "seededFrom",
28990
+ "credentials",
28991
+ "fallbacks",
28761
28992
  "createdAt",
28762
28993
  "lastUpdatedAt"
28763
28994
  ]
@@ -28779,7 +29010,7 @@
28779
29010
  },
28780
29011
  "patch": {
28781
29012
  "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).",
29013
+ "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
29014
  "tags": [
28784
29015
  "Models"
28785
29016
  ],
@@ -28847,6 +29078,14 @@
28847
29078
  },
28848
29079
  "minItems": 1
28849
29080
  }
29081
+ },
29082
+ "fallbacks": {
29083
+ "type": "array",
29084
+ "items": {
29085
+ "type": "string",
29086
+ "pattern": "^[a-z0-9][a-z0-9._-]{0,99}$"
29087
+ },
29088
+ "maxItems": 10
28850
29089
  }
28851
29090
  }
28852
29091
  }
@@ -28932,6 +29171,12 @@
28932
29171
  "minItems": 1
28933
29172
  }
28934
29173
  },
29174
+ "fallbacks": {
29175
+ "type": "array",
29176
+ "items": {
29177
+ "type": "string"
29178
+ }
29179
+ },
28935
29180
  "createdAt": {
28936
29181
  "type": "string"
28937
29182
  },
@@ -28949,6 +29194,7 @@
28949
29194
  "description",
28950
29195
  "seededFrom",
28951
29196
  "credentials",
29197
+ "fallbacks",
28952
29198
  "createdAt",
28953
29199
  "lastUpdatedAt"
28954
29200
  ]
@@ -28990,7 +29236,7 @@
28990
29236
  },
28991
29237
  "delete": {
28992
29238
  "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).",
29239
+ "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
29240
  "tags": [
28995
29241
  "Models"
28996
29242
  ],
@@ -36817,7 +37063,7 @@
36817
37063
  "/api/tasks/{id}/supersede": {
36818
37064
  "post": {
36819
37065
  "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.",
37066
+ "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
37067
  "tags": [
36822
37068
  "Tasks"
36823
37069
  ],
@@ -36848,7 +37094,21 @@
36848
37094
  "graceful_shutdown",
36849
37095
  "context_limits",
36850
37096
  "manual_supersede",
36851
- "crash_recovery"
37097
+ "crash_recovery",
37098
+ "provider_fallback"
37099
+ ]
37100
+ },
37101
+ "errorClass": {
37102
+ "type": "string",
37103
+ "enum": [
37104
+ "rate_limit",
37105
+ "model_window",
37106
+ "seat",
37107
+ "credits",
37108
+ "overloaded",
37109
+ "server_error",
37110
+ "auth",
37111
+ "pool_empty"
36852
37112
  ]
36853
37113
  }
36854
37114
  },
@@ -36878,7 +37138,8 @@
36878
37138
  "enum": [
36879
37139
  "alreadyFinished",
36880
37140
  "workflow-failed",
36881
- "resumed"
37141
+ "resumed",
37142
+ "noFallback"
36882
37143
  ]
36883
37144
  },
36884
37145
  "task": {
@@ -36914,6 +37175,12 @@
36914
37175
  "superseded",
36915
37176
  "skipped"
36916
37177
  ]
37178
+ },
37179
+ "failureReason": {
37180
+ "type": [
37181
+ "string",
37182
+ "null"
37183
+ ]
36917
37184
  }
36918
37185
  },
36919
37186
  "required": [
@@ -51161,84 +51428,302 @@
51161
51428
  }
51162
51429
  }
51163
51430
  },
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.",
51431
+ "/api/savings/jobs": {
51432
+ "get": {
51433
+ "summary": "Estimated automation savings for a workflow",
51434
+ "description": "What the workflow's runs in the window would have cost as agent tasks, minus what they cost. `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). `valid` is false when the workflow had no runs, or more runs than the live computation handles.",
51168
51435
  "tags": [
51169
- "Sessions"
51436
+ "Savings"
51170
51437
  ],
51171
51438
  "security": [
51172
51439
  {
51173
51440
  "bearerAuth": []
51174
51441
  }
51175
51442
  ],
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
- }
51443
+ "parameters": [
51444
+ {
51445
+ "schema": {
51446
+ "type": "string",
51447
+ "minLength": 1
51448
+ },
51449
+ "required": true,
51450
+ "name": "workflowId",
51451
+ "in": "query"
51452
+ },
51453
+ {
51454
+ "schema": {
51455
+ "type": "string",
51456
+ "enum": [
51457
+ "7",
51458
+ "30",
51459
+ "90"
51460
+ ],
51461
+ "default": "30"
51462
+ },
51463
+ "required": false,
51464
+ "name": "days",
51465
+ "in": "query"
51466
+ },
51467
+ {
51468
+ "schema": {
51469
+ "type": "string",
51470
+ "enum": [
51471
+ "smol",
51472
+ "regular",
51473
+ "smart",
51474
+ "ultra"
51475
+ ],
51476
+ "default": "smart"
51477
+ },
51478
+ "required": false,
51479
+ "name": "tier",
51480
+ "in": "query"
51205
51481
  }
51206
- },
51482
+ ],
51207
51483
  "responses": {
51208
51484
  "200": {
51209
- "description": "Minted token plaintext (returned once) and its stable token ID",
51485
+ "description": "Savings rows for the workflow",
51210
51486
  "content": {
51211
51487
  "application/json": {
51212
51488
  "schema": {
51213
51489
  "type": "object",
51214
51490
  "properties": {
51215
- "tokenId": {
51491
+ "window": {
51492
+ "type": "object",
51493
+ "properties": {
51494
+ "start": {
51495
+ "type": "string"
51496
+ },
51497
+ "end": {
51498
+ "type": "string"
51499
+ },
51500
+ "days": {
51501
+ "type": "integer"
51502
+ }
51503
+ },
51504
+ "required": [
51505
+ "start",
51506
+ "end",
51507
+ "days"
51508
+ ]
51509
+ },
51510
+ "tier": {
51511
+ "type": "string",
51512
+ "enum": [
51513
+ "smol",
51514
+ "regular",
51515
+ "smart",
51516
+ "ultra"
51517
+ ]
51518
+ },
51519
+ "calibrationModel": {
51216
51520
  "type": "string"
51217
51521
  },
51218
- "plaintext": {
51522
+ "calibratedAt": {
51523
+ "type": "string"
51524
+ },
51525
+ "calibrationSource": {
51526
+ "type": "string",
51527
+ "enum": [
51528
+ "shipped",
51529
+ "deployment"
51530
+ ]
51531
+ },
51532
+ "computedAt": {
51219
51533
  "type": "string"
51534
+ },
51535
+ "valid": {
51536
+ "type": "boolean"
51537
+ },
51538
+ "reason": {
51539
+ "type": [
51540
+ "string",
51541
+ "null"
51542
+ ],
51543
+ "enum": [
51544
+ "no-runs",
51545
+ "too-many-runs",
51546
+ null
51547
+ ]
51548
+ },
51549
+ "rows": {
51550
+ "type": "array",
51551
+ "items": {
51552
+ "type": "object",
51553
+ "properties": {
51554
+ "kind": {
51555
+ "type": "string",
51556
+ "enum": [
51557
+ "workflow"
51558
+ ]
51559
+ },
51560
+ "workflowId": {
51561
+ "type": "string"
51562
+ },
51563
+ "name": {
51564
+ "type": "string"
51565
+ },
51566
+ "basis": {
51567
+ "type": "string",
51568
+ "enum": [
51569
+ "modelled"
51570
+ ]
51571
+ },
51572
+ "runs": {
51573
+ "type": "integer"
51574
+ },
51575
+ "substitutedRuns": {
51576
+ "type": "integer"
51577
+ },
51578
+ "effectRuns": {
51579
+ "type": "integer"
51580
+ },
51581
+ "enabledOnlyRuns": {
51582
+ "type": "integer"
51583
+ },
51584
+ "capApplied": {
51585
+ "type": "boolean"
51586
+ },
51587
+ "opsPerRun": {
51588
+ "type": "number"
51589
+ },
51590
+ "measuredUsd": {
51591
+ "type": "number",
51592
+ "description": "Measured spend of every run in the window: agent tasks, their reviews, recorded LLM cost."
51593
+ },
51594
+ "estimatedLlmUsd": {
51595
+ "type": "number",
51596
+ "description": "LLM spend estimated from tokens and output size, not measured. 0 when the runs recorded their LLM cost."
51597
+ },
51598
+ "actualUsd": {
51599
+ "type": "number",
51600
+ "description": "Scaled estimate, not a measurement: `measuredUsd + estimatedLlmUsd` times `substitutedRuns / runs`. The saving subtracts this."
51601
+ },
51602
+ "agentOnlyUsd": {
51603
+ "type": "object",
51604
+ "properties": {
51605
+ "p10": {
51606
+ "type": "number"
51607
+ },
51608
+ "p50": {
51609
+ "type": "number"
51610
+ },
51611
+ "p90": {
51612
+ "type": "number"
51613
+ }
51614
+ },
51615
+ "required": [
51616
+ "p10",
51617
+ "p50",
51618
+ "p90"
51619
+ ]
51620
+ },
51621
+ "savingUsd": {
51622
+ "type": "object",
51623
+ "properties": {
51624
+ "p10": {
51625
+ "type": "number"
51626
+ },
51627
+ "p50": {
51628
+ "type": "number"
51629
+ },
51630
+ "p90": {
51631
+ "type": "number"
51632
+ }
51633
+ },
51634
+ "required": [
51635
+ "p10",
51636
+ "p50",
51637
+ "p90"
51638
+ ]
51639
+ },
51640
+ "actualHours": {
51641
+ "type": "number",
51642
+ "description": "Scaled estimate: measured hours times `substitutedRuns / runs`."
51643
+ },
51644
+ "agentOnlyHours": {
51645
+ "type": "object",
51646
+ "properties": {
51647
+ "p10": {
51648
+ "type": "number"
51649
+ },
51650
+ "p50": {
51651
+ "type": "number"
51652
+ },
51653
+ "p90": {
51654
+ "type": "number"
51655
+ }
51656
+ },
51657
+ "required": [
51658
+ "p10",
51659
+ "p50",
51660
+ "p90"
51661
+ ]
51662
+ },
51663
+ "hoursSaved": {
51664
+ "type": "object",
51665
+ "properties": {
51666
+ "p10": {
51667
+ "type": "number"
51668
+ },
51669
+ "p50": {
51670
+ "type": "number"
51671
+ },
51672
+ "p90": {
51673
+ "type": "number"
51674
+ }
51675
+ },
51676
+ "required": [
51677
+ "p10",
51678
+ "p50",
51679
+ "p90"
51680
+ ]
51681
+ },
51682
+ "agentOnlyUsdPerRun": {
51683
+ "type": "number"
51684
+ }
51685
+ },
51686
+ "required": [
51687
+ "kind",
51688
+ "workflowId",
51689
+ "name",
51690
+ "basis",
51691
+ "runs",
51692
+ "substitutedRuns",
51693
+ "effectRuns",
51694
+ "enabledOnlyRuns",
51695
+ "capApplied",
51696
+ "opsPerRun",
51697
+ "measuredUsd",
51698
+ "estimatedLlmUsd",
51699
+ "actualUsd",
51700
+ "agentOnlyUsd",
51701
+ "savingUsd",
51702
+ "actualHours",
51703
+ "agentOnlyHours",
51704
+ "hoursSaved",
51705
+ "agentOnlyUsdPerRun"
51706
+ ]
51707
+ }
51220
51708
  }
51221
51709
  },
51222
51710
  "required": [
51223
- "tokenId",
51224
- "plaintext"
51711
+ "window",
51712
+ "tier",
51713
+ "calibrationModel",
51714
+ "calibratedAt",
51715
+ "calibrationSource",
51716
+ "computedAt",
51717
+ "valid",
51718
+ "reason",
51719
+ "rows"
51225
51720
  ]
51226
51721
  }
51227
51722
  }
51228
51723
  }
51229
51724
  },
51230
51725
  "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",
51726
+ "description": "Missing workflowId, or an unknown days or tier value",
51242
51727
  "content": {
51243
51728
  "application/json": {
51244
51729
  "schema": {
@@ -51247,8 +51732,8 @@
51247
51732
  }
51248
51733
  }
51249
51734
  },
51250
- "403": {
51251
- "description": "Token cannot mint for this agent or task",
51735
+ "404": {
51736
+ "description": "Workflow not found",
51252
51737
  "content": {
51253
51738
  "application/json": {
51254
51739
  "schema": {
@@ -51256,38 +51741,9 @@
51256
51741
  }
51257
51742
  }
51258
51743
  }
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.",
51267
- "tags": [
51268
- "Sessions"
51269
- ],
51270
- "security": [
51271
- {
51272
- "bearerAuth": []
51273
- }
51274
- ],
51275
- "parameters": [
51276
- {
51277
- "schema": {
51278
- "type": "string"
51279
- },
51280
- "required": true,
51281
- "name": "tokenId",
51282
- "in": "path"
51283
- }
51284
- ],
51285
- "responses": {
51286
- "204": {
51287
- "description": "Token revoked (or was already revoked)"
51288
51744
  },
51289
- "401": {
51290
- "description": "Unauthorized",
51745
+ "408": {
51746
+ "description": "A savings query ran past its time budget",
51291
51747
  "content": {
51292
51748
  "application/json": {
51293
51749
  "schema": {
@@ -51296,8 +51752,8 @@
51296
51752
  }
51297
51753
  }
51298
51754
  },
51299
- "403": {
51300
- "description": "Token cannot revoke this child",
51755
+ "429": {
51756
+ "description": "Too many concurrent database queries; retry shortly",
51301
51757
  "content": {
51302
51758
  "application/json": {
51303
51759
  "schema": {
@@ -51309,13 +51765,12 @@
51309
51765
  }
51310
51766
  }
51311
51767
  },
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.",
51768
+ "/api/savings/daily": {
51769
+ "get": {
51770
+ "summary": "Daily automation savings for a workflow",
51771
+ "description": "The workflow's p50 saving, measured spend and scaled actual cost per UTC day of the window, from the same computation as `/api/savings/jobs`, so the points sum to its p50 saving, `measuredUsd`, `estimatedLlmUsd` and `actualUsd`. When the hourly cap applies, the counted schedule runs are spread pro rata over the days. `valid` is false when the workflow had no runs, or more runs than the live computation handles.",
51317
51772
  "tags": [
51318
- "Sessions"
51773
+ "Savings"
51319
51774
  ],
51320
51775
  "security": [
51321
51776
  {
@@ -51329,47 +51784,953 @@
51329
51784
  "minLength": 1
51330
51785
  },
51331
51786
  "required": true,
51332
- "name": "id",
51333
- "in": "path"
51787
+ "name": "workflowId",
51788
+ "in": "query"
51789
+ },
51790
+ {
51791
+ "schema": {
51792
+ "type": "string",
51793
+ "enum": [
51794
+ "7",
51795
+ "30",
51796
+ "90"
51797
+ ],
51798
+ "default": "30"
51799
+ },
51800
+ "required": false,
51801
+ "name": "days",
51802
+ "in": "query"
51803
+ },
51804
+ {
51805
+ "schema": {
51806
+ "type": "string",
51807
+ "enum": [
51808
+ "smol",
51809
+ "regular",
51810
+ "smart",
51811
+ "ultra"
51812
+ ],
51813
+ "default": "smart"
51814
+ },
51815
+ "required": false,
51816
+ "name": "tier",
51817
+ "in": "query"
51334
51818
  }
51335
51819
  ],
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
51820
  "responses": {
51358
51821
  "200": {
51359
- "description": "Minted worker token",
51822
+ "description": "Daily savings points for the workflow",
51360
51823
  "content": {
51361
51824
  "application/json": {
51362
51825
  "schema": {
51363
51826
  "type": "object",
51364
51827
  "properties": {
51365
- "agentId": {
51366
- "type": "string"
51367
- },
51368
- "tokenId": {
51369
- "type": "string"
51370
- },
51371
- "plaintext": {
51372
- "type": "string"
51828
+ "window": {
51829
+ "type": "object",
51830
+ "properties": {
51831
+ "start": {
51832
+ "type": "string"
51833
+ },
51834
+ "end": {
51835
+ "type": "string"
51836
+ },
51837
+ "days": {
51838
+ "type": "integer"
51839
+ }
51840
+ },
51841
+ "required": [
51842
+ "start",
51843
+ "end",
51844
+ "days"
51845
+ ]
51846
+ },
51847
+ "tier": {
51848
+ "type": "string",
51849
+ "enum": [
51850
+ "smol",
51851
+ "regular",
51852
+ "smart",
51853
+ "ultra"
51854
+ ]
51855
+ },
51856
+ "calibrationModel": {
51857
+ "type": "string"
51858
+ },
51859
+ "calibratedAt": {
51860
+ "type": "string"
51861
+ },
51862
+ "calibrationSource": {
51863
+ "type": "string",
51864
+ "enum": [
51865
+ "shipped",
51866
+ "deployment"
51867
+ ]
51868
+ },
51869
+ "computedAt": {
51870
+ "type": "string"
51871
+ },
51872
+ "valid": {
51873
+ "type": "boolean"
51874
+ },
51875
+ "reason": {
51876
+ "type": [
51877
+ "string",
51878
+ "null"
51879
+ ],
51880
+ "enum": [
51881
+ "no-runs",
51882
+ "too-many-runs",
51883
+ null
51884
+ ]
51885
+ },
51886
+ "points": {
51887
+ "type": "array",
51888
+ "items": {
51889
+ "type": "object",
51890
+ "properties": {
51891
+ "day": {
51892
+ "type": "string"
51893
+ },
51894
+ "savingUsd": {
51895
+ "type": "number"
51896
+ },
51897
+ "actualUsd": {
51898
+ "type": "number",
51899
+ "description": "Scaled estimate: the day's measured and estimated spend times the window's substituted share."
51900
+ },
51901
+ "measuredUsd": {
51902
+ "type": "number",
51903
+ "description": "The day's measured spend, not scaled."
51904
+ },
51905
+ "estimatedLlmUsd": {
51906
+ "type": "number",
51907
+ "description": "The day's LLM spend estimated from tokens and output size, not measured."
51908
+ }
51909
+ },
51910
+ "required": [
51911
+ "day",
51912
+ "savingUsd",
51913
+ "actualUsd",
51914
+ "measuredUsd",
51915
+ "estimatedLlmUsd"
51916
+ ]
51917
+ }
51918
+ }
51919
+ },
51920
+ "required": [
51921
+ "window",
51922
+ "tier",
51923
+ "calibrationModel",
51924
+ "calibratedAt",
51925
+ "calibrationSource",
51926
+ "computedAt",
51927
+ "valid",
51928
+ "reason",
51929
+ "points"
51930
+ ]
51931
+ }
51932
+ }
51933
+ }
51934
+ },
51935
+ "400": {
51936
+ "description": "Missing workflowId, or an unknown days or tier value",
51937
+ "content": {
51938
+ "application/json": {
51939
+ "schema": {
51940
+ "$ref": "#/components/schemas/ErrorResponse"
51941
+ }
51942
+ }
51943
+ }
51944
+ },
51945
+ "404": {
51946
+ "description": "Workflow not found",
51947
+ "content": {
51948
+ "application/json": {
51949
+ "schema": {
51950
+ "$ref": "#/components/schemas/ErrorResponse"
51951
+ }
51952
+ }
51953
+ }
51954
+ },
51955
+ "408": {
51956
+ "description": "A savings query ran past its time budget",
51957
+ "content": {
51958
+ "application/json": {
51959
+ "schema": {
51960
+ "$ref": "#/components/schemas/ErrorResponse"
51961
+ }
51962
+ }
51963
+ }
51964
+ },
51965
+ "429": {
51966
+ "description": "Too many concurrent database queries; retry shortly",
51967
+ "content": {
51968
+ "application/json": {
51969
+ "schema": {
51970
+ "$ref": "#/components/schemas/ErrorResponse"
51971
+ }
51972
+ }
51973
+ }
51974
+ }
51975
+ }
51976
+ }
51977
+ },
51978
+ "/api/savings/calibration": {
51979
+ "get": {
51980
+ "summary": "The savings curve in use",
51981
+ "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).",
51982
+ "tags": [
51983
+ "Savings"
51984
+ ],
51985
+ "security": [
51986
+ {
51987
+ "bearerAuth": []
51988
+ }
51989
+ ],
51990
+ "responses": {
51991
+ "200": {
51992
+ "description": "The active calibration",
51993
+ "content": {
51994
+ "application/json": {
51995
+ "schema": {
51996
+ "type": "object",
51997
+ "properties": {
51998
+ "source": {
51999
+ "type": "string",
52000
+ "enum": [
52001
+ "shipped",
52002
+ "deployment"
52003
+ ]
52004
+ },
52005
+ "active": {
52006
+ "type": "object",
52007
+ "properties": {
52008
+ "calibratedAt": {
52009
+ "type": "string"
52010
+ },
52011
+ "model": {
52012
+ "type": "string"
52013
+ },
52014
+ "curve": {
52015
+ "type": "object",
52016
+ "properties": {
52017
+ "smol": {
52018
+ "type": "object",
52019
+ "properties": {
52020
+ "usd": {
52021
+ "type": "array",
52022
+ "items": {
52023
+ "type": "number"
52024
+ }
52025
+ },
52026
+ "hrs": {
52027
+ "type": "array",
52028
+ "items": {
52029
+ "type": "number"
52030
+ }
52031
+ }
52032
+ },
52033
+ "required": [
52034
+ "usd",
52035
+ "hrs"
52036
+ ]
52037
+ },
52038
+ "regular": {
52039
+ "type": "object",
52040
+ "properties": {
52041
+ "usd": {
52042
+ "type": "array",
52043
+ "items": {
52044
+ "type": "number"
52045
+ }
52046
+ },
52047
+ "hrs": {
52048
+ "type": "array",
52049
+ "items": {
52050
+ "type": "number"
52051
+ }
52052
+ }
52053
+ },
52054
+ "required": [
52055
+ "usd",
52056
+ "hrs"
52057
+ ]
52058
+ },
52059
+ "smart": {
52060
+ "type": "object",
52061
+ "properties": {
52062
+ "usd": {
52063
+ "type": "array",
52064
+ "items": {
52065
+ "type": "number"
52066
+ }
52067
+ },
52068
+ "hrs": {
52069
+ "type": "array",
52070
+ "items": {
52071
+ "type": "number"
52072
+ }
52073
+ }
52074
+ },
52075
+ "required": [
52076
+ "usd",
52077
+ "hrs"
52078
+ ]
52079
+ },
52080
+ "ultra": {
52081
+ "type": "object",
52082
+ "properties": {
52083
+ "usd": {
52084
+ "type": "array",
52085
+ "items": {
52086
+ "type": "number"
52087
+ }
52088
+ },
52089
+ "hrs": {
52090
+ "type": "array",
52091
+ "items": {
52092
+ "type": "number"
52093
+ }
52094
+ }
52095
+ },
52096
+ "required": [
52097
+ "usd",
52098
+ "hrs"
52099
+ ]
52100
+ }
52101
+ },
52102
+ "required": [
52103
+ "smol",
52104
+ "regular",
52105
+ "smart",
52106
+ "ultra"
52107
+ ]
52108
+ }
52109
+ },
52110
+ "required": [
52111
+ "calibratedAt",
52112
+ "model",
52113
+ "curve"
52114
+ ]
52115
+ },
52116
+ "stored": {
52117
+ "type": [
52118
+ "object",
52119
+ "null"
52120
+ ],
52121
+ "properties": {
52122
+ "valid": {
52123
+ "type": "boolean"
52124
+ },
52125
+ "updatedAt": {
52126
+ "type": "string"
52127
+ },
52128
+ "calibratedAt": {
52129
+ "type": "string"
52130
+ },
52131
+ "model": {
52132
+ "type": "string"
52133
+ },
52134
+ "window": {
52135
+ "type": "object",
52136
+ "properties": {
52137
+ "start": {
52138
+ "type": "string"
52139
+ },
52140
+ "end": {
52141
+ "type": "string"
52142
+ },
52143
+ "sessions": {
52144
+ "type": "integer"
52145
+ }
52146
+ },
52147
+ "required": [
52148
+ "start",
52149
+ "end",
52150
+ "sessions"
52151
+ ]
52152
+ }
52153
+ },
52154
+ "required": [
52155
+ "valid",
52156
+ "updatedAt"
52157
+ ]
52158
+ }
52159
+ },
52160
+ "required": [
52161
+ "source",
52162
+ "active",
52163
+ "stored"
52164
+ ]
52165
+ }
52166
+ }
52167
+ }
52168
+ }
52169
+ }
52170
+ },
52171
+ "post": {
52172
+ "summary": "Derive the savings curve from this deployment's sessions",
52173
+ "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.",
52174
+ "tags": [
52175
+ "Savings"
52176
+ ],
52177
+ "security": [
52178
+ {
52179
+ "bearerAuth": []
52180
+ }
52181
+ ],
52182
+ "requestBody": {
52183
+ "content": {
52184
+ "application/json": {
52185
+ "schema": {
52186
+ "type": "object",
52187
+ "properties": {
52188
+ "days": {
52189
+ "type": "integer",
52190
+ "minimum": 1,
52191
+ "maximum": 90,
52192
+ "default": 30
52193
+ },
52194
+ "end": {
52195
+ "type": "string",
52196
+ "format": "date-time",
52197
+ "description": "End of the window (ISO 8601); default now."
52198
+ },
52199
+ "apply": {
52200
+ "type": "boolean",
52201
+ "default": false
52202
+ }
52203
+ }
52204
+ }
52205
+ }
52206
+ }
52207
+ },
52208
+ "responses": {
52209
+ "200": {
52210
+ "description": "The derived curve, or why there is none",
52211
+ "content": {
52212
+ "application/json": {
52213
+ "schema": {
52214
+ "type": "object",
52215
+ "properties": {
52216
+ "window": {
52217
+ "type": "object",
52218
+ "properties": {
52219
+ "start": {
52220
+ "type": "string"
52221
+ },
52222
+ "end": {
52223
+ "type": "string"
52224
+ },
52225
+ "days": {
52226
+ "type": "integer"
52227
+ }
52228
+ },
52229
+ "required": [
52230
+ "start",
52231
+ "end",
52232
+ "days"
52233
+ ]
52234
+ },
52235
+ "sessions": {
52236
+ "type": "integer",
52237
+ "description": "Opus sessions of 1 to 61 turns used."
52238
+ },
52239
+ "refusals": {
52240
+ "type": "array",
52241
+ "items": {
52242
+ "type": "string"
52243
+ },
52244
+ "description": "Why no curve was derived, or why a derived one was not applied."
52245
+ },
52246
+ "calibration": {
52247
+ "type": [
52248
+ "object",
52249
+ "null"
52250
+ ],
52251
+ "properties": {
52252
+ "calibratedAt": {
52253
+ "type": "string"
52254
+ },
52255
+ "model": {
52256
+ "type": "string"
52257
+ },
52258
+ "curve": {
52259
+ "type": "object",
52260
+ "properties": {
52261
+ "smol": {
52262
+ "type": "object",
52263
+ "properties": {
52264
+ "usd": {
52265
+ "type": "array",
52266
+ "items": {
52267
+ "type": "number"
52268
+ }
52269
+ },
52270
+ "hrs": {
52271
+ "type": "array",
52272
+ "items": {
52273
+ "type": "number"
52274
+ }
52275
+ }
52276
+ },
52277
+ "required": [
52278
+ "usd",
52279
+ "hrs"
52280
+ ]
52281
+ },
52282
+ "regular": {
52283
+ "type": "object",
52284
+ "properties": {
52285
+ "usd": {
52286
+ "type": "array",
52287
+ "items": {
52288
+ "type": "number"
52289
+ }
52290
+ },
52291
+ "hrs": {
52292
+ "type": "array",
52293
+ "items": {
52294
+ "type": "number"
52295
+ }
52296
+ }
52297
+ },
52298
+ "required": [
52299
+ "usd",
52300
+ "hrs"
52301
+ ]
52302
+ },
52303
+ "smart": {
52304
+ "type": "object",
52305
+ "properties": {
52306
+ "usd": {
52307
+ "type": "array",
52308
+ "items": {
52309
+ "type": "number"
52310
+ }
52311
+ },
52312
+ "hrs": {
52313
+ "type": "array",
52314
+ "items": {
52315
+ "type": "number"
52316
+ }
52317
+ }
52318
+ },
52319
+ "required": [
52320
+ "usd",
52321
+ "hrs"
52322
+ ]
52323
+ },
52324
+ "ultra": {
52325
+ "type": "object",
52326
+ "properties": {
52327
+ "usd": {
52328
+ "type": "array",
52329
+ "items": {
52330
+ "type": "number"
52331
+ }
52332
+ },
52333
+ "hrs": {
52334
+ "type": "array",
52335
+ "items": {
52336
+ "type": "number"
52337
+ }
52338
+ }
52339
+ },
52340
+ "required": [
52341
+ "usd",
52342
+ "hrs"
52343
+ ]
52344
+ }
52345
+ },
52346
+ "required": [
52347
+ "smol",
52348
+ "regular",
52349
+ "smart",
52350
+ "ultra"
52351
+ ]
52352
+ },
52353
+ "window": {
52354
+ "type": "object",
52355
+ "properties": {
52356
+ "start": {
52357
+ "type": "string"
52358
+ },
52359
+ "end": {
52360
+ "type": "string"
52361
+ },
52362
+ "sessions": {
52363
+ "type": "integer"
52364
+ }
52365
+ },
52366
+ "required": [
52367
+ "start",
52368
+ "end",
52369
+ "sessions"
52370
+ ]
52371
+ }
52372
+ },
52373
+ "required": [
52374
+ "calibratedAt",
52375
+ "model",
52376
+ "curve"
52377
+ ],
52378
+ "description": "The derived curve; null when refused."
52379
+ },
52380
+ "speed": {
52381
+ "type": [
52382
+ "object",
52383
+ "null"
52384
+ ],
52385
+ "additionalProperties": {
52386
+ "type": "number"
52387
+ }
52388
+ },
52389
+ "repriceMatch": {
52390
+ "type": [
52391
+ "number",
52392
+ "null"
52393
+ ]
52394
+ },
52395
+ "meanRatio": {
52396
+ "type": [
52397
+ "number",
52398
+ "null"
52399
+ ],
52400
+ "description": "Derived smart-tier mean cost over the shipped one."
52401
+ },
52402
+ "gaps": {
52403
+ "type": "array",
52404
+ "items": {
52405
+ "type": "object",
52406
+ "properties": {
52407
+ "tier": {
52408
+ "type": "string",
52409
+ "enum": [
52410
+ "smol",
52411
+ "regular",
52412
+ "smart",
52413
+ "ultra"
52414
+ ]
52415
+ },
52416
+ "key": {
52417
+ "type": "string",
52418
+ "enum": [
52419
+ "usd",
52420
+ "hrs"
52421
+ ]
52422
+ },
52423
+ "median": {
52424
+ "type": "number",
52425
+ "description": "Median absolute deviation from the shipped curve, as a fraction."
52426
+ },
52427
+ "max": {
52428
+ "type": "number"
52429
+ },
52430
+ "over5pct": {
52431
+ "type": "integer",
52432
+ "description": "Turn counts more than 5% from the shipped curve."
52433
+ },
52434
+ "points": {
52435
+ "type": "integer"
52436
+ },
52437
+ "weighted": {
52438
+ "type": "number",
52439
+ "description": "Session-weighted mean of derived over shipped; 1 means the same price."
52440
+ }
52441
+ },
52442
+ "required": [
52443
+ "tier",
52444
+ "key",
52445
+ "median",
52446
+ "max",
52447
+ "over5pct",
52448
+ "points",
52449
+ "weighted"
52450
+ ]
52451
+ }
52452
+ },
52453
+ "applied": {
52454
+ "type": "boolean"
52455
+ }
52456
+ },
52457
+ "required": [
52458
+ "window",
52459
+ "sessions",
52460
+ "refusals",
52461
+ "calibration",
52462
+ "speed",
52463
+ "repriceMatch",
52464
+ "meanRatio",
52465
+ "gaps",
52466
+ "applied"
52467
+ ]
52468
+ }
52469
+ }
52470
+ }
52471
+ },
52472
+ "400": {
52473
+ "description": "Invalid days, end or apply",
52474
+ "content": {
52475
+ "application/json": {
52476
+ "schema": {
52477
+ "$ref": "#/components/schemas/ErrorResponse"
52478
+ }
52479
+ }
52480
+ }
52481
+ },
52482
+ "403": {
52483
+ "description": "`apply` without permission to write config",
52484
+ "content": {
52485
+ "application/json": {
52486
+ "schema": {
52487
+ "$ref": "#/components/schemas/ErrorResponse"
52488
+ }
52489
+ }
52490
+ }
52491
+ },
52492
+ "408": {
52493
+ "description": "A session query ran past its time budget",
52494
+ "content": {
52495
+ "application/json": {
52496
+ "schema": {
52497
+ "$ref": "#/components/schemas/ErrorResponse"
52498
+ }
52499
+ }
52500
+ }
52501
+ },
52502
+ "409": {
52503
+ "description": "Another calibration run is in progress",
52504
+ "content": {
52505
+ "application/json": {
52506
+ "schema": {
52507
+ "$ref": "#/components/schemas/ErrorResponse"
52508
+ }
52509
+ }
52510
+ }
52511
+ },
52512
+ "504": {
52513
+ "description": "The run passed its 120 s deadline",
52514
+ "content": {
52515
+ "application/json": {
52516
+ "schema": {
52517
+ "$ref": "#/components/schemas/ErrorResponse"
52518
+ }
52519
+ }
52520
+ }
52521
+ }
52522
+ }
52523
+ }
52524
+ },
52525
+ "/api/sessions/tokens": {
52526
+ "post": {
52527
+ "summary": "Mint an ephemeral task or runtime token",
52528
+ "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.",
52529
+ "tags": [
52530
+ "Sessions"
52531
+ ],
52532
+ "security": [
52533
+ {
52534
+ "bearerAuth": []
52535
+ }
52536
+ ],
52537
+ "requestBody": {
52538
+ "content": {
52539
+ "application/json": {
52540
+ "schema": {
52541
+ "type": "object",
52542
+ "properties": {
52543
+ "agentId": {
52544
+ "type": "string",
52545
+ "minLength": 1
52546
+ },
52547
+ "taskId": {
52548
+ "type": "string",
52549
+ "minLength": 1
52550
+ },
52551
+ "runtimeId": {
52552
+ "type": "string",
52553
+ "minLength": 1
52554
+ },
52555
+ "ttlMs": {
52556
+ "type": "integer",
52557
+ "exclusiveMinimum": 0,
52558
+ "maximum": 604800000
52559
+ }
52560
+ },
52561
+ "required": [
52562
+ "agentId"
52563
+ ]
52564
+ }
52565
+ }
52566
+ }
52567
+ },
52568
+ "responses": {
52569
+ "200": {
52570
+ "description": "Minted token plaintext (returned once) and its stable token ID",
52571
+ "content": {
52572
+ "application/json": {
52573
+ "schema": {
52574
+ "type": "object",
52575
+ "properties": {
52576
+ "tokenId": {
52577
+ "type": "string"
52578
+ },
52579
+ "plaintext": {
52580
+ "type": "string"
52581
+ }
52582
+ },
52583
+ "required": [
52584
+ "tokenId",
52585
+ "plaintext"
52586
+ ]
52587
+ }
52588
+ }
52589
+ }
52590
+ },
52591
+ "400": {
52592
+ "description": "Validation error",
52593
+ "content": {
52594
+ "application/json": {
52595
+ "schema": {
52596
+ "$ref": "#/components/schemas/ErrorResponse"
52597
+ }
52598
+ }
52599
+ }
52600
+ },
52601
+ "401": {
52602
+ "description": "Unauthorized",
52603
+ "content": {
52604
+ "application/json": {
52605
+ "schema": {
52606
+ "$ref": "#/components/schemas/ErrorResponse"
52607
+ }
52608
+ }
52609
+ }
52610
+ },
52611
+ "403": {
52612
+ "description": "Token cannot mint for this agent or task",
52613
+ "content": {
52614
+ "application/json": {
52615
+ "schema": {
52616
+ "$ref": "#/components/schemas/ErrorResponse"
52617
+ }
52618
+ }
52619
+ }
52620
+ }
52621
+ }
52622
+ }
52623
+ },
52624
+ "/api/sessions/tokens/{tokenId}": {
52625
+ "delete": {
52626
+ "summary": "Revoke an ephemeral session token",
52627
+ "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.",
52628
+ "tags": [
52629
+ "Sessions"
52630
+ ],
52631
+ "security": [
52632
+ {
52633
+ "bearerAuth": []
52634
+ }
52635
+ ],
52636
+ "parameters": [
52637
+ {
52638
+ "schema": {
52639
+ "type": "string"
52640
+ },
52641
+ "required": true,
52642
+ "name": "tokenId",
52643
+ "in": "path"
52644
+ }
52645
+ ],
52646
+ "responses": {
52647
+ "204": {
52648
+ "description": "Token revoked (or was already revoked)"
52649
+ },
52650
+ "401": {
52651
+ "description": "Unauthorized",
52652
+ "content": {
52653
+ "application/json": {
52654
+ "schema": {
52655
+ "$ref": "#/components/schemas/ErrorResponse"
52656
+ }
52657
+ }
52658
+ }
52659
+ },
52660
+ "403": {
52661
+ "description": "Token cannot revoke this child",
52662
+ "content": {
52663
+ "application/json": {
52664
+ "schema": {
52665
+ "$ref": "#/components/schemas/ErrorResponse"
52666
+ }
52667
+ }
52668
+ }
52669
+ }
52670
+ }
52671
+ }
52672
+ },
52673
+ "/api/agents/{id}/token": {
52674
+ "post": {
52675
+ "operationId": "agents_mintWorkerToken",
52676
+ "summary": "Mint an agent-bound worker token",
52677
+ "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.",
52678
+ "tags": [
52679
+ "Sessions"
52680
+ ],
52681
+ "security": [
52682
+ {
52683
+ "bearerAuth": []
52684
+ }
52685
+ ],
52686
+ "parameters": [
52687
+ {
52688
+ "schema": {
52689
+ "type": "string",
52690
+ "minLength": 1
52691
+ },
52692
+ "required": true,
52693
+ "name": "id",
52694
+ "in": "path"
52695
+ }
52696
+ ],
52697
+ "requestBody": {
52698
+ "content": {
52699
+ "application/json": {
52700
+ "schema": {
52701
+ "type": "object",
52702
+ "properties": {
52703
+ "name": {
52704
+ "type": "string",
52705
+ "minLength": 1
52706
+ },
52707
+ "ttlMs": {
52708
+ "type": "integer",
52709
+ "exclusiveMinimum": 0,
52710
+ "description": "Token lifetime in ms. Omit for the default (no expiry)."
52711
+ }
52712
+ },
52713
+ "additionalProperties": false
52714
+ }
52715
+ }
52716
+ }
52717
+ },
52718
+ "responses": {
52719
+ "200": {
52720
+ "description": "Minted worker token",
52721
+ "content": {
52722
+ "application/json": {
52723
+ "schema": {
52724
+ "type": "object",
52725
+ "properties": {
52726
+ "agentId": {
52727
+ "type": "string"
52728
+ },
52729
+ "tokenId": {
52730
+ "type": "string"
52731
+ },
52732
+ "plaintext": {
52733
+ "type": "string"
51373
52734
  },
51374
52735
  "expiresAt": {
51375
52736
  "type": [
@@ -59262,10 +60623,15 @@
59262
60623
  },
59263
60624
  "/api/trackers/jira/authorize": {
59264
60625
  "get": {
59265
- "summary": "Redirect to Atlassian OAuth consent screen",
60626
+ "summary": "Start the Jira OAuth flow (admin): redirect to the consent screen, or return its URL",
59266
60627
  "tags": [
59267
60628
  "Trackers"
59268
60629
  ],
60630
+ "security": [
60631
+ {
60632
+ "bearerAuth": []
60633
+ }
60634
+ ],
59269
60635
  "parameters": [
59270
60636
  {
59271
60637
  "schema": {
@@ -59274,12 +60640,52 @@
59274
60640
  "required": false,
59275
60641
  "name": "redirect",
59276
60642
  "in": "query"
60643
+ },
60644
+ {
60645
+ "schema": {
60646
+ "type": "string",
60647
+ "enum": [
60648
+ "redirect",
60649
+ "json"
60650
+ ]
60651
+ },
60652
+ "required": false,
60653
+ "name": "format",
60654
+ "in": "query"
59277
60655
  }
59278
60656
  ],
59279
60657
  "responses": {
60658
+ "200": {
60659
+ "description": "Consent URL (format=json), for clients that navigate themselves",
60660
+ "content": {
60661
+ "application/json": {
60662
+ "schema": {
60663
+ "type": "object",
60664
+ "properties": {
60665
+ "authorizeUrl": {
60666
+ "type": "string"
60667
+ }
60668
+ },
60669
+ "required": [
60670
+ "authorizeUrl"
60671
+ ]
60672
+ }
60673
+ }
60674
+ }
60675
+ },
59280
60676
  "302": {
59281
60677
  "description": "Redirect to Atlassian OAuth"
59282
60678
  },
60679
+ "403": {
60680
+ "description": "Caller lacks oauth-authorization.manage",
60681
+ "content": {
60682
+ "application/json": {
60683
+ "schema": {
60684
+ "$ref": "#/components/schemas/ErrorResponse"
60685
+ }
60686
+ }
60687
+ }
60688
+ },
59283
60689
  "500": {
59284
60690
  "description": "Failed to generate authorization URL",
59285
60691
  "content": {
@@ -59945,10 +61351,15 @@
59945
61351
  },
59946
61352
  "/api/trackers/linear/authorize": {
59947
61353
  "get": {
59948
- "summary": "Redirect to Linear OAuth consent screen",
61354
+ "summary": "Start the Linear OAuth flow (admin): redirect to the consent screen, or return its URL",
59949
61355
  "tags": [
59950
61356
  "Trackers"
59951
61357
  ],
61358
+ "security": [
61359
+ {
61360
+ "bearerAuth": []
61361
+ }
61362
+ ],
59952
61363
  "parameters": [
59953
61364
  {
59954
61365
  "schema": {
@@ -59957,12 +61368,52 @@
59957
61368
  "required": false,
59958
61369
  "name": "redirect",
59959
61370
  "in": "query"
61371
+ },
61372
+ {
61373
+ "schema": {
61374
+ "type": "string",
61375
+ "enum": [
61376
+ "redirect",
61377
+ "json"
61378
+ ]
61379
+ },
61380
+ "required": false,
61381
+ "name": "format",
61382
+ "in": "query"
59960
61383
  }
59961
61384
  ],
59962
61385
  "responses": {
61386
+ "200": {
61387
+ "description": "Consent URL (format=json), for clients that navigate themselves",
61388
+ "content": {
61389
+ "application/json": {
61390
+ "schema": {
61391
+ "type": "object",
61392
+ "properties": {
61393
+ "authorizeUrl": {
61394
+ "type": "string"
61395
+ }
61396
+ },
61397
+ "required": [
61398
+ "authorizeUrl"
61399
+ ]
61400
+ }
61401
+ }
61402
+ }
61403
+ },
59963
61404
  "302": {
59964
61405
  "description": "Redirect to Linear OAuth"
59965
61406
  },
61407
+ "403": {
61408
+ "description": "Caller lacks oauth-authorization.manage",
61409
+ "content": {
61410
+ "application/json": {
61411
+ "schema": {
61412
+ "$ref": "#/components/schemas/ErrorResponse"
61413
+ }
61414
+ }
61415
+ }
61416
+ },
59966
61417
  "500": {
59967
61418
  "description": "Failed to generate authorization URL",
59968
61419
  "content": {