@mastra/factory 0.29.0-alpha.4 → 0.29.0-alpha.6

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 (401) hide show
  1. package/README.md +172 -89
  2. package/dist/boards/board-events.d.ts +89 -9
  3. package/dist/boards/board-events.d.ts.map +1 -1
  4. package/dist/boards/board-events.js +176 -13
  5. package/dist/boards/board-events.js.map +1 -1
  6. package/dist/boards/board-writes.d.ts.map +1 -1
  7. package/dist/boards/board-writes.js +14 -1
  8. package/dist/boards/board-writes.js.map +1 -1
  9. package/dist/boards/busy-card.d.ts +11 -0
  10. package/dist/boards/busy-card.d.ts.map +1 -0
  11. package/dist/boards/busy-card.js +15 -0
  12. package/dist/boards/busy-card.js.map +1 -0
  13. package/dist/boards/card-facts.d.ts.map +1 -1
  14. package/dist/boards/card-facts.js +18 -4
  15. package/dist/boards/card-facts.js.map +1 -1
  16. package/dist/boards/index.d.ts +2 -1
  17. package/dist/boards/index.d.ts.map +1 -1
  18. package/dist/boards/index.js +3 -2
  19. package/dist/boards/intake-dry-run.d.ts +109 -0
  20. package/dist/boards/intake-dry-run.d.ts.map +1 -0
  21. package/dist/boards/intake-dry-run.js +158 -0
  22. package/dist/boards/intake-dry-run.js.map +1 -0
  23. package/dist/boards/intake-lookup.d.ts +32 -0
  24. package/dist/boards/intake-lookup.d.ts.map +1 -0
  25. package/dist/boards/intake-lookup.js +12 -0
  26. package/dist/boards/intake-lookup.js.map +1 -0
  27. package/dist/boards/intake-order.d.ts +32 -0
  28. package/dist/boards/intake-order.d.ts.map +1 -0
  29. package/dist/boards/intake-order.js +60 -0
  30. package/dist/boards/intake-order.js.map +1 -0
  31. package/dist/boards/intake-routing.d.ts +246 -35
  32. package/dist/boards/intake-routing.d.ts.map +1 -1
  33. package/dist/boards/intake-routing.js +437 -52
  34. package/dist/boards/intake-routing.js.map +1 -1
  35. package/dist/boards/reroute.d.ts +7 -3
  36. package/dist/boards/reroute.d.ts.map +1 -1
  37. package/dist/boards/reroute.js +21 -4
  38. package/dist/boards/reroute.js.map +1 -1
  39. package/dist/boards/semantics.d.ts +8 -28
  40. package/dist/boards/semantics.d.ts.map +1 -1
  41. package/dist/boards/semantics.js +14 -40
  42. package/dist/boards/semantics.js.map +1 -1
  43. package/dist/boards/work-routes.d.ts +31 -11
  44. package/dist/boards/work-routes.d.ts.map +1 -1
  45. package/dist/boards/work-routes.js +104 -20
  46. package/dist/boards/work-routes.js.map +1 -1
  47. package/dist/factory.d.ts +37 -1
  48. package/dist/factory.d.ts.map +1 -1
  49. package/dist/factory.js +127 -48
  50. package/dist/factory.js.map +1 -1
  51. package/dist/integrations/base.d.ts +9 -0
  52. package/dist/integrations/base.d.ts.map +1 -1
  53. package/dist/integrations/dependabot/rules.js +1 -1
  54. package/dist/integrations/dependabot/rules.js.map +1 -1
  55. package/dist/integrations/github/default-rules.d.ts +22 -1
  56. package/dist/integrations/github/default-rules.d.ts.map +1 -1
  57. package/dist/integrations/github/default-rules.js +23 -5
  58. package/dist/integrations/github/default-rules.js.map +1 -1
  59. package/dist/integrations/github/intake-lookup.d.ts +16 -0
  60. package/dist/integrations/github/intake-lookup.d.ts.map +1 -0
  61. package/dist/integrations/github/intake-lookup.js +76 -0
  62. package/dist/integrations/github/intake-lookup.js.map +1 -0
  63. package/dist/integrations/github/integration.d.ts +19 -5
  64. package/dist/integrations/github/integration.d.ts.map +1 -1
  65. package/dist/integrations/github/integration.js +21 -6
  66. package/dist/integrations/github/integration.js.map +1 -1
  67. package/dist/integrations/github/issue-intake.d.ts +15 -0
  68. package/dist/integrations/github/issue-intake.d.ts.map +1 -0
  69. package/dist/integrations/github/issue-intake.js +50 -0
  70. package/dist/integrations/github/issue-intake.js.map +1 -0
  71. package/dist/integrations/github/issue-reconciler.d.ts.map +1 -1
  72. package/dist/integrations/github/issue-reconciler.js +10 -1
  73. package/dist/integrations/github/issue-reconciler.js.map +1 -1
  74. package/dist/integrations/github/review-status-reporter.js +1 -1
  75. package/dist/integrations/github/routes.d.ts.map +1 -1
  76. package/dist/integrations/github/routes.js +14 -2
  77. package/dist/integrations/github/routes.js.map +1 -1
  78. package/dist/integrations/github/rules.d.ts +14 -1
  79. package/dist/integrations/github/rules.d.ts.map +1 -1
  80. package/dist/integrations/github/rules.js +221 -30
  81. package/dist/integrations/github/rules.js.map +1 -1
  82. package/dist/integrations/github/sandbox.d.ts.map +1 -1
  83. package/dist/integrations/github/sandbox.js +30 -4
  84. package/dist/integrations/github/sandbox.js.map +1 -1
  85. package/dist/integrations/gitlab/default-rules.d.ts.map +1 -1
  86. package/dist/integrations/gitlab/default-rules.js +19 -3
  87. package/dist/integrations/gitlab/default-rules.js.map +1 -1
  88. package/dist/integrations/gitlab/intake-lookup.d.ts +17 -0
  89. package/dist/integrations/gitlab/intake-lookup.d.ts.map +1 -0
  90. package/dist/integrations/gitlab/intake-lookup.js +85 -0
  91. package/dist/integrations/gitlab/intake-lookup.js.map +1 -0
  92. package/dist/integrations/gitlab/integration.d.ts +5 -0
  93. package/dist/integrations/gitlab/integration.d.ts.map +1 -1
  94. package/dist/integrations/gitlab/integration.js +21 -1
  95. package/dist/integrations/gitlab/integration.js.map +1 -1
  96. package/dist/integrations/gitlab/rules.d.ts +20 -0
  97. package/dist/integrations/gitlab/rules.d.ts.map +1 -1
  98. package/dist/integrations/gitlab/rules.js +108 -12
  99. package/dist/integrations/gitlab/rules.js.map +1 -1
  100. package/dist/integrations/incidentio/rules.d.ts.map +1 -1
  101. package/dist/integrations/incidentio/rules.js +14 -4
  102. package/dist/integrations/incidentio/rules.js.map +1 -1
  103. package/dist/integrations/jira/rules.d.ts.map +1 -1
  104. package/dist/integrations/jira/rules.js +12 -2
  105. package/dist/integrations/jira/rules.js.map +1 -1
  106. package/dist/integrations/linear/rules.d.ts.map +1 -1
  107. package/dist/integrations/linear/rules.js +13 -2
  108. package/dist/integrations/linear/rules.js.map +1 -1
  109. package/dist/integrations/platform/connect/routes.d.ts +43 -1
  110. package/dist/integrations/platform/connect/routes.d.ts.map +1 -1
  111. package/dist/integrations/platform/connect/routes.js +82 -7
  112. package/dist/integrations/platform/connect/routes.js.map +1 -1
  113. package/dist/integrations/platform/connect/session-tools.d.ts +12 -0
  114. package/dist/integrations/platform/connect/session-tools.d.ts.map +1 -1
  115. package/dist/integrations/platform/connect/session-tools.js +28 -10
  116. package/dist/integrations/platform/connect/session-tools.js.map +1 -1
  117. package/dist/integrations/platform/github/event-worker.js +9 -1
  118. package/dist/integrations/platform/github/event-worker.js.map +1 -1
  119. package/dist/integrations/platform/github/integration.d.ts +6 -6
  120. package/dist/integrations/platform/github/integration.d.ts.map +1 -1
  121. package/dist/integrations/platform/github/integration.js +22 -3
  122. package/dist/integrations/platform/github/integration.js.map +1 -1
  123. package/dist/integrations/platform/vanta/integration.d.ts.map +1 -1
  124. package/dist/integrations/platform/vanta/integration.js +3 -3
  125. package/dist/integrations/platform/vanta/integration.js.map +1 -1
  126. package/dist/integrations/pull-request-head.d.ts +1 -1
  127. package/dist/integrations/pull-request-head.d.ts.map +1 -1
  128. package/dist/integrations/pull-request-head.js +5 -0
  129. package/dist/integrations/pull-request-head.js.map +1 -1
  130. package/dist/integrations/vanta/rules.js +1 -1
  131. package/dist/integrations/vanta/rules.js.map +1 -1
  132. package/dist/integrations/vanta/sync.d.ts +9 -0
  133. package/dist/integrations/vanta/sync.d.ts.map +1 -1
  134. package/dist/integrations/vanta/sync.js +10 -1
  135. package/dist/integrations/vanta/sync.js.map +1 -1
  136. package/dist/routes/board-snapshot.d.ts +13 -6
  137. package/dist/routes/board-snapshot.d.ts.map +1 -1
  138. package/dist/routes/board-snapshot.js +42 -20
  139. package/dist/routes/board-snapshot.js.map +1 -1
  140. package/dist/routes/boards.js.map +1 -1
  141. package/dist/routes/config.d.ts +17 -2
  142. package/dist/routes/config.d.ts.map +1 -1
  143. package/dist/routes/config.js +247 -77
  144. package/dist/routes/config.js.map +1 -1
  145. package/dist/routes/contracts.d.ts +1294 -7
  146. package/dist/routes/contracts.d.ts.map +1 -1
  147. package/dist/routes/contracts.js +603 -20
  148. package/dist/routes/contracts.js.map +1 -1
  149. package/dist/routes/custom-endpoint-url.d.ts +8 -0
  150. package/dist/routes/custom-endpoint-url.d.ts.map +1 -0
  151. package/dist/routes/custom-endpoint-url.js +45 -0
  152. package/dist/routes/custom-endpoint-url.js.map +1 -0
  153. package/dist/routes/custom-provider-source.d.ts +24 -8
  154. package/dist/routes/custom-provider-source.d.ts.map +1 -1
  155. package/dist/routes/custom-provider-source.js +93 -43
  156. package/dist/routes/custom-provider-source.js.map +1 -1
  157. package/dist/routes/intake-check.d.ts +92 -0
  158. package/dist/routes/intake-check.d.ts.map +1 -0
  159. package/dist/routes/intake-check.js +322 -0
  160. package/dist/routes/intake-check.js.map +1 -0
  161. package/dist/routes/intake-routes.d.ts +10 -2
  162. package/dist/routes/intake-routes.d.ts.map +1 -1
  163. package/dist/routes/intake-routes.js +292 -11
  164. package/dist/routes/intake-routes.js.map +1 -1
  165. package/dist/routes/intake.d.ts +6 -0
  166. package/dist/routes/intake.d.ts.map +1 -1
  167. package/dist/routes/intake.js +20 -0
  168. package/dist/routes/intake.js.map +1 -1
  169. package/dist/routes/mastra-gateway.d.ts.map +1 -1
  170. package/dist/routes/mastra-gateway.js +3 -2
  171. package/dist/routes/mastra-gateway.js.map +1 -1
  172. package/dist/routes/project-sessions.d.ts +61 -0
  173. package/dist/routes/project-sessions.d.ts.map +1 -0
  174. package/dist/routes/project-sessions.js +135 -0
  175. package/dist/routes/project-sessions.js.map +1 -0
  176. package/dist/routes/projects.d.ts +6 -1
  177. package/dist/routes/projects.d.ts.map +1 -1
  178. package/dist/routes/projects.js +19 -3
  179. package/dist/routes/projects.js.map +1 -1
  180. package/dist/routes/provider-credentials.d.ts +10 -1
  181. package/dist/routes/provider-credentials.d.ts.map +1 -1
  182. package/dist/routes/provider-credentials.js +13 -16
  183. package/dist/routes/provider-credentials.js.map +1 -1
  184. package/dist/routes/run-queue.d.ts +6 -6
  185. package/dist/routes/run-queue.d.ts.map +1 -1
  186. package/dist/routes/run-queue.js +28 -8
  187. package/dist/routes/run-queue.js.map +1 -1
  188. package/dist/routes/session-rows.d.ts +30 -0
  189. package/dist/routes/session-rows.d.ts.map +1 -0
  190. package/dist/routes/session-rows.js +94 -0
  191. package/dist/routes/session-rows.js.map +1 -0
  192. package/dist/routes/source-control-sessions.d.ts +4 -5
  193. package/dist/routes/source-control-sessions.d.ts.map +1 -1
  194. package/dist/routes/source-control-sessions.js +8 -87
  195. package/dist/routes/source-control-sessions.js.map +1 -1
  196. package/dist/routes/surface.d.ts +16 -1
  197. package/dist/routes/surface.d.ts.map +1 -1
  198. package/dist/routes/surface.js +41 -30
  199. package/dist/routes/surface.js.map +1 -1
  200. package/dist/routes/tenant-credentials.d.ts.map +1 -1
  201. package/dist/routes/tenant-credentials.js +4 -4
  202. package/dist/routes/tenant-credentials.js.map +1 -1
  203. package/dist/routes/work-item-starters.d.ts +1 -0
  204. package/dist/routes/work-item-starters.d.ts.map +1 -1
  205. package/dist/routes/work-item-starters.js +14 -2
  206. package/dist/routes/work-item-starters.js.map +1 -1
  207. package/dist/routes/work-items.d.ts +22 -3
  208. package/dist/routes/work-items.d.ts.map +1 -1
  209. package/dist/routes/work-items.js +124 -48
  210. package/dist/routes/work-items.js.map +1 -1
  211. package/dist/rules/binding-context.d.ts +5 -0
  212. package/dist/rules/binding-context.d.ts.map +1 -1
  213. package/dist/rules/binding-context.js +51 -5
  214. package/dist/rules/binding-context.js.map +1 -1
  215. package/dist/rules/dispatch-errors.js +1 -1
  216. package/dist/rules/dispatch-errors.js.map +1 -1
  217. package/dist/rules/dispatcher.d.ts +39 -7
  218. package/dist/rules/dispatcher.d.ts.map +1 -1
  219. package/dist/rules/dispatcher.js +363 -123
  220. package/dist/rules/dispatcher.js.map +1 -1
  221. package/dist/rules/event-rules.d.ts +69 -1
  222. package/dist/rules/event-rules.d.ts.map +1 -1
  223. package/dist/rules/event-rules.js +151 -5
  224. package/dist/rules/event-rules.js.map +1 -1
  225. package/dist/rules/review-source-tool.js +1 -1
  226. package/dist/rules/rule-group.d.ts +18 -1
  227. package/dist/rules/rule-group.d.ts.map +1 -1
  228. package/dist/rules/rule-group.js +52 -8
  229. package/dist/rules/rule-group.js.map +1 -1
  230. package/dist/rules/run-bearing.d.ts +8 -0
  231. package/dist/rules/run-bearing.d.ts.map +1 -0
  232. package/dist/rules/run-bearing.js +11 -0
  233. package/dist/rules/run-bearing.js.map +1 -0
  234. package/dist/rules/start-coordinator.d.ts +2 -3
  235. package/dist/rules/start-coordinator.d.ts.map +1 -1
  236. package/dist/rules/start-coordinator.js +25 -38
  237. package/dist/rules/start-coordinator.js.map +1 -1
  238. package/dist/rules/tools.js +2 -1
  239. package/dist/rules/tools.js.map +1 -1
  240. package/dist/rules/transition-service.d.ts +16 -0
  241. package/dist/rules/transition-service.d.ts.map +1 -1
  242. package/dist/rules/transition-service.js +34 -10
  243. package/dist/rules/transition-service.js.map +1 -1
  244. package/dist/rules/types.d.ts +18 -5
  245. package/dist/rules/types.d.ts.map +1 -1
  246. package/dist/rules/types.js +2 -1
  247. package/dist/rules/types.js.map +1 -1
  248. package/dist/rules/update-fold.d.ts +32 -0
  249. package/dist/rules/update-fold.d.ts.map +1 -0
  250. package/dist/rules/update-fold.js +60 -0
  251. package/dist/rules/update-fold.js.map +1 -0
  252. package/dist/rules/validation.d.ts.map +1 -1
  253. package/dist/rules/validation.js +54 -6
  254. package/dist/rules/validation.js.map +1 -1
  255. package/dist/sandbox/session-retirement.d.ts +6 -0
  256. package/dist/sandbox/session-retirement.d.ts.map +1 -1
  257. package/dist/sandbox/session-retirement.js +17 -0
  258. package/dist/sandbox/session-retirement.js.map +1 -1
  259. package/dist/session/factory-session.d.ts.map +1 -1
  260. package/dist/session/factory-session.js +2 -1
  261. package/dist/session/factory-session.js.map +1 -1
  262. package/dist/session/live-sessions.d.ts +6 -1
  263. package/dist/session/live-sessions.d.ts.map +1 -1
  264. package/dist/session/live-sessions.js +4 -0
  265. package/dist/session/live-sessions.js.map +1 -1
  266. package/dist/session/resource-migration.d.ts.map +1 -1
  267. package/dist/session/resource-migration.js +2 -3
  268. package/dist/session/resource-migration.js.map +1 -1
  269. package/dist/session/run-audit.d.ts +10 -1
  270. package/dist/session/run-audit.d.ts.map +1 -1
  271. package/dist/session/run-audit.js +9 -1
  272. package/dist/session/run-audit.js.map +1 -1
  273. package/dist/session/self-review-gate.d.ts +26 -2
  274. package/dist/session/self-review-gate.d.ts.map +1 -1
  275. package/dist/session/self-review-gate.js +60 -10
  276. package/dist/session/self-review-gate.js.map +1 -1
  277. package/dist/session/session-row-query.d.ts +25 -0
  278. package/dist/session/session-row-query.d.ts.map +1 -0
  279. package/dist/session/session-row-query.js +47 -0
  280. package/dist/session/session-row-query.js.map +1 -0
  281. package/dist/session/session-row-status.d.ts +16 -0
  282. package/dist/session/session-row-status.d.ts.map +1 -0
  283. package/dist/session/session-row-status.js +14 -0
  284. package/dist/session/session-row-status.js.map +1 -0
  285. package/dist/session/session-row-view.d.ts +13 -0
  286. package/dist/session/session-row-view.d.ts.map +1 -0
  287. package/dist/session/session-row-view.js +118 -0
  288. package/dist/session/session-row-view.js.map +1 -0
  289. package/dist/session/session-rows.d.ts +60 -0
  290. package/dist/session/session-rows.d.ts.map +1 -0
  291. package/dist/session/session-rows.js +307 -0
  292. package/dist/session/session-rows.js.map +1 -0
  293. package/dist/session/session-threads.d.ts.map +1 -1
  294. package/dist/session/session-threads.js +1 -0
  295. package/dist/session/session-threads.js.map +1 -1
  296. package/dist/session/session-unloader.d.ts +101 -0
  297. package/dist/session/session-unloader.d.ts.map +1 -0
  298. package/dist/session/session-unloader.js +278 -0
  299. package/dist/session/session-unloader.js.map +1 -0
  300. package/dist/session/source-control-tools.d.ts +14 -7
  301. package/dist/session/source-control-tools.d.ts.map +1 -1
  302. package/dist/session/source-control-tools.js +10 -2
  303. package/dist/session/source-control-tools.js.map +1 -1
  304. package/dist/session/work-item-repository.d.ts +49 -1
  305. package/dist/session/work-item-repository.d.ts.map +1 -1
  306. package/dist/session/work-item-repository.js +118 -15
  307. package/dist/session/work-item-repository.js.map +1 -1
  308. package/dist/session/work-item-state-processor.d.ts.map +1 -1
  309. package/dist/session/work-item-state-processor.js +44 -8
  310. package/dist/session/work-item-state-processor.js.map +1 -1
  311. package/dist/session-list-changes.d.ts +9 -0
  312. package/dist/session-list-changes.d.ts.map +1 -0
  313. package/dist/session-list-changes.js +54 -0
  314. package/dist/session-list-changes.js.map +1 -0
  315. package/dist/storage/announced-lists.d.ts +14 -0
  316. package/dist/storage/announced-lists.d.ts.map +1 -0
  317. package/dist/storage/announced-lists.js +78 -0
  318. package/dist/storage/announced-lists.js.map +1 -0
  319. package/dist/storage/domains/audit/actions.d.ts +2 -1
  320. package/dist/storage/domains/audit/actions.d.ts.map +1 -1
  321. package/dist/storage/domains/audit/actions.js +3 -1
  322. package/dist/storage/domains/audit/actions.js.map +1 -1
  323. package/dist/storage/domains/boards/base.d.ts +163 -15
  324. package/dist/storage/domains/boards/base.d.ts.map +1 -1
  325. package/dist/storage/domains/boards/base.js +440 -48
  326. package/dist/storage/domains/boards/base.js.map +1 -1
  327. package/dist/storage/domains/boards/schemas.d.ts +6 -0
  328. package/dist/storage/domains/boards/schemas.d.ts.map +1 -1
  329. package/dist/storage/domains/boards/schemas.js +95 -1
  330. package/dist/storage/domains/boards/schemas.js.map +1 -1
  331. package/dist/storage/domains/custom-providers/base.d.ts +62 -19
  332. package/dist/storage/domains/custom-providers/base.d.ts.map +1 -1
  333. package/dist/storage/domains/custom-providers/base.js +131 -100
  334. package/dist/storage/domains/custom-providers/base.js.map +1 -1
  335. package/dist/storage/domains/intake/base.d.ts +25 -7
  336. package/dist/storage/domains/intake/base.d.ts.map +1 -1
  337. package/dist/storage/domains/intake/base.js +83 -19
  338. package/dist/storage/domains/intake/base.js.map +1 -1
  339. package/dist/storage/domains/projects/base.d.ts.map +1 -1
  340. package/dist/storage/domains/projects/base.js +19 -10
  341. package/dist/storage/domains/projects/base.js.map +1 -1
  342. package/dist/storage/domains/source-control/base.d.ts +8 -0
  343. package/dist/storage/domains/source-control/base.d.ts.map +1 -1
  344. package/dist/storage/domains/source-control/base.js +110 -61
  345. package/dist/storage/domains/source-control/base.js.map +1 -1
  346. package/dist/storage/domains/source-control/inmemory.d.ts +4 -0
  347. package/dist/storage/domains/source-control/inmemory.d.ts.map +1 -1
  348. package/dist/storage/domains/source-control/inmemory.js +8 -5
  349. package/dist/storage/domains/source-control/inmemory.js.map +1 -1
  350. package/dist/storage/domains/work-items/base.d.ts +57 -18
  351. package/dist/storage/domains/work-items/base.d.ts.map +1 -1
  352. package/dist/storage/domains/work-items/base.js +168 -83
  353. package/dist/storage/domains/work-items/base.js.map +1 -1
  354. package/dist/storage/domains/work-items/cards.d.ts +3 -2
  355. package/dist/storage/domains/work-items/cards.d.ts.map +1 -1
  356. package/dist/storage/domains/work-items/cards.js +4 -2
  357. package/dist/storage/domains/work-items/cards.js.map +1 -1
  358. package/dist/tools/audit-events-tool.d.ts +2 -2
  359. package/dist/tools/read-tools.d.ts +9 -5
  360. package/dist/tools/read-tools.d.ts.map +1 -1
  361. package/dist/tools/read-tools.js +61 -54
  362. package/dist/tools/read-tools.js.map +1 -1
  363. package/dist/tools/session-tools.d.ts +0 -13
  364. package/dist/tools/session-tools.d.ts.map +1 -1
  365. package/dist/tools/session-tools.js +128 -341
  366. package/dist/tools/session-tools.js.map +1 -1
  367. package/dist/tools/work-item-tools.d.ts +3 -0
  368. package/dist/tools/work-item-tools.d.ts.map +1 -1
  369. package/dist/tools/work-item-tools.js +99 -27
  370. package/dist/tools/work-item-tools.js.map +1 -1
  371. package/dist/work-item-branch.d.ts +4 -0
  372. package/dist/work-item-branch.d.ts.map +1 -1
  373. package/dist/work-item-branch.js +7 -1
  374. package/dist/work-item-branch.js.map +1 -1
  375. package/dist/work-items/card-context-sessions.d.ts +50 -0
  376. package/dist/work-items/card-context-sessions.d.ts.map +1 -0
  377. package/dist/work-items/card-context-sessions.js +84 -0
  378. package/dist/work-items/card-context-sessions.js.map +1 -0
  379. package/dist/work-items/card-reference.d.ts +21 -0
  380. package/dist/work-items/card-reference.d.ts.map +1 -0
  381. package/dist/work-items/card-reference.js +58 -0
  382. package/dist/work-items/card-reference.js.map +1 -0
  383. package/dist/work-items/change-requests.d.ts +87 -0
  384. package/dist/work-items/change-requests.d.ts.map +1 -0
  385. package/dist/work-items/change-requests.js +134 -0
  386. package/dist/work-items/change-requests.js.map +1 -0
  387. package/dist/work-items/create-work-item.d.ts +7 -2
  388. package/dist/work-items/create-work-item.d.ts.map +1 -1
  389. package/dist/work-items/create-work-item.js +44 -13
  390. package/dist/work-items/create-work-item.js.map +1 -1
  391. package/dist/work-items/list-related-cards.d.ts.map +1 -1
  392. package/dist/work-items/list-related-cards.js +1 -1
  393. package/dist/work-items/list-related-cards.js.map +1 -1
  394. package/dist/work-items/providers/github.d.ts.map +1 -1
  395. package/dist/work-items/providers/github.js +1 -0
  396. package/dist/work-items/providers/github.js.map +1 -1
  397. package/factory-skills/factory-build/SKILL.md +1 -1
  398. package/factory-skills/factory-plan/SKILL.md +5 -3
  399. package/factory-skills/factory-self-review/SKILL.md +2 -0
  400. package/factory-skills/factory-triage/SKILL.md +1 -1
  401. package/package.json +10 -10
package/README.md CHANGED
@@ -58,13 +58,15 @@ function summarizeCard(card: Card) {
58
58
 
59
59
  Each work item has one board item. Factory's card-to-card parent link is `parentBoardItemId`. Provider sub-issue ancestry is not populated into `card.workItem.parentWorkItemId`; migrated work items leave that field null. Existing card IDs, comments, subscriptions, run bindings, and `/work-items/:id` URLs stay unchanged. The work item gets its own ID. For one release, work-item API responses also retain the legacy top-level title, external source, and merged metadata fields.
60
60
 
61
- `GET /web/factory/projects/:id/work-items` lists a project's cards. Pass `sessionId` to list only the cards holding that session and the cards related to them: a card's parent and children, and a pull request with the card whose session branch it was pushed from. Repeat `sessionId` to list several sessions' cards. Pass `scope=sessions` to list the cards holding any session and the cards related to them, without naming the sessions; it can't be combined with `sessionId`. Pass `started=false` to list the cards holding no session, most recently updated first: `limit` sets how many are sent (20 unless given, 50 at most), `q` keeps the cards whose title, key, number or source id contains every word in it, in any case, and `total` in the response counts every card that matched, sent or not. `started=false` can't be combined with `scope` or `sessionId`, and `q` is accepted only with it. Repeat `source` (up to 100 values) to list the cards filed from those sources, each named by its source id or its URL, whatever sessions the cards hold; it can't be combined with `started`, `scope` or `sessionId`. Repeat `workItemId` (up to 100 values) to list the cards with those ids and no other, whatever sessions they hold; an id no card has is left out, so asking for one card that was deleted answers 200 with an empty list. It can't be combined with `source`, `started`, `scope` or `sessionId`. A query the route can't answer gets a 400, never the whole board. Apart from `total`, the response has the same shape in every case, and `runningSessionIds` and `parkedSessionIds` cover only the listed cards.
61
+ `GET /web/factory/projects/:id/work-items` lists a project's cards. Pass `sessionId` to list only the cards holding that session and the cards related to them: a card's parent and children, and a pull request with the card whose session branch it was pushed from. Repeat `sessionId` to list several sessions' cards. Pass `scope=sessions` to list the cards holding any session and the cards related to them, without naming the sessions; it can't be combined with `sessionId`. Pass `started=false` to list the cards holding no session, most recently updated first: `limit` sets how many are sent (20 unless given, 50 at most), `q` keeps the cards whose title, key, number or source id contains every word in it, in any case, and `total` in the response counts every card that matched, sent or not. `started=false` can't be combined with `scope` or `sessionId`, and `q` is accepted only with it. Repeat `source` (up to 100 values) to list the cards filed from those sources, each named by its source id or its URL, whatever sessions the cards hold; it can't be combined with `started`, `scope` or `sessionId`. Repeat `workItemId` (up to 100 values) to list the cards with those ids and no other, whatever sessions they hold; an id no card has is left out, so asking for one card that was deleted answers 200 with an empty list. It can't be combined with `source`, `started`, `scope` or `sessionId`. A query the route can't answer gets a 400, never the whole board. Apart from `total`, the response has the same shape in every case.
62
62
 
63
63
  The whole-board listing also returns a `cursor`, and each card carries `changedAt`, when it last changed. Send the cursor back as `since` to get only what moved since that read: `workItems` then holds the cards changed, `removedIds` the cards deleted, and `check` a value naming every card on the board and when it last changed, with the next `cursor`. A reader merges these into the board it kept, then compares `boardCheck` of its merged cards (exported from `@mastra/factory/work-items/board-check`) with `check`, and reads the board whole again when they differ. A `since` the server can't answer from is ignored, not refused, so the answer is the listing as it would be without it, with no `removedIds`: a malformed cursor, a board that returned no `cursor`, or a listing narrowed by `sessionId`, `scope`, `started`, `source` or `workItemId`.
64
64
 
65
65
  Two reads answer questions about a project's cards without listing them. `GET /web/factory/projects/:id/work-items/starters` counts the cards on the default board that each new-session starter would act on: cards whose run failed, pull requests with changes requested, pull requests waiting for review (with when the oldest was opened), triaged cards waiting on a person, untriaged cards, bugs with no plan, the label with the most cards not started, and stale pull requests. Failed runs are read from the 50 newest run decisions, as on the cards. `GET /web/factory/projects/:id/work-items/activity?since=<ISO 8601 instant>` returns how many cards the project has, and when cards were created and completed from `since` on; a missing or malformed `since` is a 400. Its answer carries an `ETag`: ask again for the same `since` with `If-None-Match`, and an answer that did not change comes back as a 304 with no body.
66
66
 
67
- Two more reads serve a board without sending every card. `GET /web/factory/projects/:id/boards/:boardKey/phases` returns one entry per phase of the board in `phases`, in the board's order: `phase` is its id, `total` counts the cards in it, and `cards` names the first of them as `{ id, version }`. `version` names the card's body: it is another value whenever anything in the body is, including a change that leaves `changedAt` as it was. `limit` sets how many each phase names (50 unless given, 200 at most), `window=<phase>:<count>` (repeatable) names more cards of one phase, and `item=<card id>` asks for one card wherever it lies: the answer names it in `item` as `{ id, version, places }`, where `places` gives each phase the view lists it under and its `position` there (how many cards the phase lists before it), and `cards=true` sends its body. No phase names more cards for it, so the answer is the same size for the oldest card of a phase as for the newest. `places` is empty when the search or filters leave the card out, and `item` is absent when the board does not hold the card. `sort` is `recent` (latest entry into the phase first, the default), `recent-mine` (the cards the signed-in user last moved into the phase first), `created-newest` or `created-oldest`. `q` keeps the cards whose title, key, number or source id contains every word in it; `label`, `source`, `linearProject`, `teammate`, `author`, `assignee`, `reviewer` and `worked` (all repeatable) keep the cards matching every field given. `boardTotal` counts the board's cards whatever the search and filters, `matchingTotal` the cards matching them, a card in two phases once. `related` names the cards related to a named card that no phase names, the first `limit` of each card's, and `relatedTotal` counts them all, and `runningSessionIds` and `parkedSessionIds` cover the named cards. Pass `cards=true` to also receive the body of every named card in `workItems`, each with its `version`; without it, read the cards whose `version` differs from the copy you kept with `GET /web/factory/projects/:id/work-items?workItemId=<id>`, which sends each card with its `version` too. A card in none of the board's phases is counted in the first one. A malformed parameter is a 400 `invalid_phases_query`; a board the project doesn't have is a 404; a `window` for a phase the board doesn't have is ignored. `GET /web/factory/projects/:id/work-items/filter-options` returns what a board can be filtered by, over every card of the project: `labels`, sorted; `people`, each person a source names as author, assignee or requested reviewer, as `{ id, name, source }`; and `actorIds`, the Factory users who filed, moved or started a card. Both answers carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304.
67
+ Two more reads serve a board without sending every card. `GET /web/factory/projects/:id/boards/:boardKey/phases` returns one entry per phase of the board in `phases`, in the board's order: `phase` is its id, `total` counts the cards in it, and `cards` names the first of them as `{ id, version }`. `version` names the card's body: it is another value whenever anything in the body is, including a change that leaves `changedAt` as it was. `limit` sets how many each phase names (50 unless given, 200 at most), `window=<phase>:<count>` (repeatable) names more cards of one phase, and `item=<card id>` asks for one card wherever it lies: the answer names it in `item` as `{ id, version, places }`, where `places` gives each phase the view lists it under and its `position` there (how many cards the phase lists before it), and `cards=true` sends its body. No phase names more cards for it, so the answer is the same size for the oldest card of a phase as for the newest. `places` is empty when the search or filters leave the card out, and `item` is absent when the board does not hold the card. `sort` is `recent` (latest entry into the phase first, the default), `recent-mine` (the cards the signed-in user last moved into the phase first), `created-newest` or `created-oldest`. `q` keeps the cards whose title, key, number or source id contains every word in it; `label`, `source`, `linearProject`, `teammate`, `author`, `assignee`, `reviewer` and `worked` (all repeatable) keep the cards matching every field given. `boardTotal` counts the board's cards whatever the search and filters, `matchingTotal` the cards matching them, a card in two phases once. `related` names the cards related to a named card that no phase names, the first `limit` of each card's, and `relatedTotal` counts them all. Pass `cards=true` to also receive the body of every named card in `workItems`, each with its `version`; without it, read the cards whose `version` differs from the copy you kept with `GET /web/factory/projects/:id/work-items?workItemId=<id>`, which sends each card with its `version` too. A card in none of the board's phases is counted in the first one. A malformed parameter is a 400 `invalid_phases_query`; a board the project doesn't have is a 404; a `window` for a phase the board doesn't have is ignored. `GET /web/factory/projects/:id/work-items/filter-options` returns what a board can be filtered by, over every card of the project: `labels`, sorted; `people`, each person a source names as author, assignee or requested reviewer, as `{ id, name, source }`; and `actorIds`, the Factory users who filed, moved or started a card. Both answers carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304.
68
+
69
+ Two reads serve the sidebar's sessions without sending every session and every card holding one. `GET /web/factory/projects/:id/session-rows` returns the rows of one view of the project's sessions, built on the server: one row per card for a card's sessions (`cardSessionIds` names them all; `children=true` lists the others under the row in `childRows` instead), and one row per session a person or Slack started. Each row carries its `session`, its `status` (`waiting`, `working`, `initializing`, `idle` or `done`), the card it works on, and the card's pull or merge request. `sort` is `activity` (the default), `updated` or `created`; `groupBy` is `none` (the default), `board`, `status` or `owner`; `owner` is `all`, `mine` or `owner:<user id>`; `status` and `updated` (`24h`, `7d` or `30d`) keep the matching rows. `groups` lists the groups holding a matching row, in the order their first row sorts, each with its `key`, its `total` and its first 5 `rows`; `window=<group key>:<count>` (repeatable, 500 at most) lists more of one group. `pin=<session id>` (repeatable) lists sessions before every other one of their group, and `open=<session id>` keeps that session's row listed in its group however deep it lies, with its place in `openIndex`. `total` counts every row, `matching` the rows the filters keep, and `boards` and `owners` name every board and person some row has, whatever the filters. `GET /web/factory/projects/:id/session-activity` returns which sessions are running or waiting on a person's answer, each card's status as its row in `session-rows` shows it in `cardStatuses` (only cards neither idle nor done), the cards one of whose sessions is coming up, running or parked on a person in `sessionHeldCardIds` (no other run may start on those), and how many of the cards in `cardStatuses` are working or waiting. Every write that changes either answer sends a frame on the project's feed, whichever replica made it: read again on a frame. Both carry an `ETag`; send it back as `If-None-Match` and an unchanged answer is a 304. A malformed `session-rows` parameter is a 400 `invalid_session_rows_query`.
68
70
 
69
71
  #### Migration and dry run
70
72
 
@@ -587,12 +589,12 @@ A new pull request or merge request that belongs to a card already on a board th
587
589
  When Factory first sees a pull request (GitHub `pull_request.opened`) or merge request (GitLab `open`), it looks for a home card in the same Factory project and repository. The home card must be on a board that reviews pull requests, not in one of its terminal phases, and not a pull request's own card. Factory checks, in order:
588
590
 
589
591
  1. **A pull request Factory opened for one of its cards** goes to that card, found by provenance or by the head branch matching the card's session branch. On GitHub the card must own an issue of its own: a GitHub card must be from the same repository, while a card whose issue lives in Jira, Linear or incident.io carries no repository to match against and is taken as it is. On GitLab, any card with an issue of its own (GitLab, Linear, Jira or incident.io). A card from the other forge never takes one (a GitLab card keeps only merge requests), and neither does a manual card, since the pull request would become its only source; its pull request gets a separate card. A card still in Building moves to the board's pull request review phase (on a board with self-review, that phase opens the pull request itself, so it has been skipped). A review request or `@<app> review` still sends it there.
590
- 2. **A pull request that closes an issue** can join that issue's card if a project [intake route](#intake-routes) with a `joinClosedIssue` target says so. Factory reads closing keywords from the pull request body or merge request description: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, and on GitLab also `implement`, `implements`, `implemented`, `implementing`. The target is `#N`, or `owner/repo#N` (`group/project#N`) naming the same repository. References to other repositories, links, and code spans don't count. If the pull request names several issues, the first one with an eligible card is the one routes see. The default route joins a trusted author's pull request to a card still waiting in Intake with no pull request yet, and moves that card to Review. Once the card has moved on (Triage, Planning or Building), or already carries a pull request, someone else's pull request gets its own card in Review and is reviewed right away. Done and Canceled cards are finished, so a pull request for them gets its own card too.
592
+ 2. **A pull request that closes an issue** links to that issue's card, whoever opened it and on whichever board the card sits, as long as the card isn't finished. Factory reads closing keywords from the pull request body or merge request description: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, and on GitLab also `implement`, `implements`, `implemented`, `implementing`. The target is `#N`, or `owner/repo#N` (`group/project#N`) naming the same repository. References to other repositories, links, and code spans don't count. If the pull request names several issues, it links to the first one with an unfinished card. Linking itself moves nothing: the card then gets a `pull_request.opened` event, and the card's board's [card-move rules](#status-events-move-existing-cards) decide whether it moves. The default rule, `Trusted pull requests take a waiting issue to Review`, moves a card still waiting in Intake with no pull request yet to Review when the pull request's author is trusted. A card further along stays where it is. Done and Canceled cards are finished, so a pull request for them gets its own card.
591
593
  3. **Anything else** gets its own card, exactly as before.
592
594
 
593
- An untrusted author's pull request never attaches, even when it says `fixes #12` and a route would allow it: it gets its own card in Intake, so an outside author can't take over a trusted card or its sessions. Linking only happens on first sighting: editing the body later doesn't move a pull request onto or off a card, and a replayed delivery doesn't attach it twice. A link made only in GitHub's sidebar isn't visible in the webhook, so that pull request gets its own card. The reconcile sweep doesn't carry the body either, so closing references are only read from live deliveries.
595
+ An outside author's pull request links too, but is recorded on the card as untrusted (`untrustedPullRequests` in the card's metadata), and nothing runs on it until a person picks it: it is never the card's working pull request on its own, its pushes and review requests don't re-review it, and comments on it don't reach the card's sessions. Its opening, reopening, pushes, edits and review requests move the card only by a card-move rule that tests `pullRequest.trusted`: a rule that doesn't, such as an older project's "Pull requests go to Review" or one testing only `source.repository`, skips it. Its merge or close still moves the card like any other. Card-less pull requests are filed by intake as before. To work on it, a person makes it the card's working pull request with `PUT /web/factory/projects/:id/work-items/:workItemId/working-pull-request` (`{ "pullRequest": 17, "expectedRevision": 4 }`); the pull request must be linked to the card and open (`422 pull_request_not_linked`, `422 pull_request_not_open`), and a stale revision answers `409`. Picking it doesn't make its author trusted: `pullRequest.trusted` stays `false`. Linking only happens on first sighting: editing the body later doesn't move a pull request onto or off a card, and a replayed delivery doesn't attach it twice. A link made only in GitHub's sidebar isn't visible in the webhook, so that pull request gets its own card. The reconcile sweep doesn't carry the body either, so closing references are only read from live deliveries.
594
596
 
595
- Any card that enters Work's Review (`pr-review`), or another board's pull request review phase, carrying a pull request starts the reviewer, whatever its own source. On a card with an attached pull request, the pull request's state lives on its own source, and the issue keeps its own; a reopened merge request is open on the card again. `openPullRequestNumber` only names a pull request the card's own sessions opened (its head is one of the card's session branches, or the branch Factory builds the card on). When that pull request closes, it moves to the card's next open one of its own, or clears, never to someone else's, so another person's pull request never switches off the builder's self-review or its own pull request. When a pull request merges, the card moves to Done unless another one is still open, in which case its session is told which one is out. When one closes unmerged, a card in Review with no open pull request left goes back to Intake. The reviewer checks out the pull request on its own branch (`factory/pr-<n>-…`, `factory/gitlab-mr-<n>-…`) in an untrusted checkout, never in the builder's session or branch.
597
+ Any card that enters Work's Review (`pr-review`), or another board's pull request review phase, carrying a pull request starts the reviewer, whatever its own source. On a card with an attached pull request, the pull request's state lives on its own source, and the issue keeps its own; a reopened merge request is open on the card again. The card's working pull request is the one its sessions build on and its reviewer reviews: the one `openPullRequestNumber` names, otherwise the first trusted linked one. One that closed unmerged no longer counts, so the card falls back to its first trusted open pull request, never an outsider's. `openPullRequestNumber` names a pull request the card's own sessions opened, or one a person picked (its head is one of the card's session branches, or the branch Factory builds the card on). When that pull request closes, it moves to the card's next open one of its own, or clears, never to someone else's, so another person's pull request never switches off the builder's self-review or its own pull request. When the working pull request merges, the card moves to Done unless another working one is still open, in which case its session is told which one is out. When one closes unmerged, a card in Review with no open pull request left goes back to Intake. The reviewer checks out the pull request on its own branch (`factory/pr-<n>-…`, `factory/gitlab-mr-<n>-…`) in an untrusted checkout, never in the builder's session or branch.
596
598
 
597
599
  #### The retired Review board
598
600
 
@@ -638,7 +640,7 @@ Each session context a card uses (`triage`, `work`, `review`, or a custom board'
638
640
  - **Finishing.** Entering a terminal phase stops every sandbox the card holds. A Factory process that never opened a sandbox stops it by identity through the configured sandbox provider, so a card finished on any replica stops its sandboxes.
639
641
  - **Coming back.** Stopping keeps the session, its branch and its files. A card that comes back to a context (PR review → Triage) resumes the same sandbox: E2B resumes the paused VM, Docker restarts the container, and the local sandbox reuses its directory. Platform sandboxes are not stopped remotely; they idle out under the environment's policy and the next run reattaches.
640
642
 
641
- Stopping is best-effort: a committed move never fails because a sandbox did not stop, and a card moved again before the stop runs keeps its sandbox. Deleting a session still destroys its sandbox.
643
+ Stopping is best-effort: a committed move never fails because a sandbox did not stop, and a card moved again before the stop runs keeps its sandbox. Deleting a session still destroys its sandbox. A session whose sandbox stops is also unloaded from server memory, see [Unloading idle sessions](#unloading-idle-sessions).
642
644
 
643
645
  #### The pull request loop on any board
644
646
 
@@ -660,26 +662,27 @@ Boards and phases take `name` and an optional `description`. A phase lists the p
660
662
 
661
663
  - `runner` — `{ agentId?, skill?, context?, instructions?, goal? }`. The runner is the only way a phase starts work: when a card enters the phase, from any source and including a card filed straight into it, Factory starts `skill` in the `context` session. `context` names the session the phase runs in (defaults to `work`); phases that share a context share a session. When the agent moves its own card into another phase of its context, that phase's `skill` still starts: its kickoff is queued onto the agent's run. Moving a card back into the phase it is in (a re-entry, such as a re-review after a push) supersedes the run in flight and resumes the skill. `skill` names a built-in Factory skill or one of your app's skills (see [Skills for custom boards](#skills-for-custom-boards)); a phase without one starts nothing. The kickoff names the card only by its URL (or title, quoted as untrusted data when an outside author wrote it); the agent reads everything else from the [`factory-work-item` signal](#the-factory-work-item-signal). `instructions` (up to 1,000 characters) are added to the kickoff. `agentId` defaults to `code-agent`, the only agent Factory runs today.
662
664
  - `runner.goal` — `{ objective, maxRuns? }`: the run pursues `objective` (up to 2,000 characters) as a Mastra goal. Factory stores it on the session's thread as the run starts, with the session's model as judge, and after each run the judge decides from the objective text and the latest messages whether the work is done, should continue (Factory starts another run, up to `maxRuns`, 1–50) or is waiting for a person. Waiting leaves the goal active and the card in its phase; the next message a person sends resumes it, and a skill asks people with `ask_user`, which parks the run in Factory's attention view. When `maxRuns` runs out, the goal pauses and the card stays: resume it from the session or move the card. When the card leaves the phase, by anyone, Factory marks the goal done. The judge sees only the objective and the latest messages, so state the done and waiting criteria in the objective. Work's Building pursues the approved plan this way, with up to 20 runs.
663
- - `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `author.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own.
665
+ - `autoStart` and `autoStartWhen` — the phase's runs start without a person's approval, for every card or only for cards matching the rule. To start only trusted authors' cards, add `item.trusted equals true` to `autoStartWhen`; by default, [intake routes](#intake-routes) file GitHub and GitLab cards from outside the write-access circle in Work › Intake, where nothing starts on its own.
664
666
  - `exitTool` — a tool name, or `{ id, autoApprove, autoApproveWhen }`, that ends the phase. The phase holds the card until that tool succeeds (for `submit_plan`, with an approved plan) in the session that works the card there: until then an agent or board rule asking to move the card on to another working phase is rejected with `approval_required`. Once it has succeeded during the card's current visit to the phase, the agent moves the card itself with `factory_transition_work_item` (the factory-phase signal tells it so and lists `nextPhases`), or a board tool rule for the exit tool (`tools`) moves it; the tool's success never moves the card by itself. A person can move the card at any time. The phase needs at least one next phase. `autoApprove` and `autoApproveWhen` only decide whether the tool approves itself, for every card or only cards matching the rule, or waits for a person; they are the only way plans are approved without a person. Factory sessions already run tools without asking, so for `submit_plan` this means an auto-approved plan is accepted without a person. Any other exit tool that pauses for a yes or no is approved the same way, and the sessions following the card are told a run waits on them only when a person has to answer. Work's Planning declares `{ id: 'submit_plan', autoApprove: false }`: every plan waits for a person, who approves `submit_plan` in a signed-in chat (or moves the card), and then `factory-plan` moves the card to Building.
665
667
  - `tools` — Factory tools the phase gives the session that works the card in it (the session whose context is the phase's `runner.context`): `factory_record_review_verdict` and `factory_review_source`. Tools follow the card: when it moves to a phase without them, the session loses them on its next turn, and a verdict tool call made after the card moved is refused. Every bound session keeps `factory_transition_work_item`. Work's Review grants both; a self-review phase, on a board that has one, grants only the verdict tool.
666
668
 
667
669
  Rules test a card's facts, read from its work item as the provider reported it:
668
670
 
669
- | Fact | What it is |
670
- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
671
- | `item.labels` | The item's labels. |
672
- | `item.title` | The card's title. |
673
- | `item.author` | Who opened the item. |
674
- | `item.key` | The provider's key: `acme/app#42` (GitHub), `acme/app!7` (GitLab merge request), `ENG-12` (Linear), `OPS-3` (Jira), `INC-7` (incident.io). |
675
- | `item.state` | The provider's state: `open`, `closed` or `merged` on GitHub and GitLab, the workflow state name (`In Progress`) on Linear and Jira. |
676
- | `item.assignees` | Who the item is assigned to, as a list. |
677
- | `item.pullRequest` | The number of the card's open pull or merge request, absent when it has none. |
678
- | `author.trusted` | Whether the author is trusted (see below). |
679
- | `source.kind` | `issue`, `pull_request`, … |
680
- | `source.integration` | The integration that filed it: `github`, `gitlab`, `linear`, `jira`, `incidentio`, … |
681
- | `source.provider` | The provider the work item comes from; the integration for every integration Factory ships. |
682
- | `source.repository` | Where the item lives, compared case-insensitively. GitHub: `owner/repo` (`mastra-ai/mastra`, never the bare `mastra`). GitLab: the full project path, subgroups included (`acme/platform/api`). Linear: the team key (`ENG`). Jira: the project key (`PLAT`). Absent for incident.io items (test `source.provider equals incidentio` instead) and for manual cards, which have no `source.*` facts (test `source.kind not_exists`). |
671
+ | Fact | What it is |
672
+ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
673
+ | `item.labels` | The item's labels. |
674
+ | `item.title` | The card's title. |
675
+ | `item.author` | Who opened the item. |
676
+ | `item.key` | The provider's key: `acme/app#42` (GitHub), `acme/app!7` (GitLab merge request), `ENG-12` (Linear), `OPS-3` (Jira), `INC-7` (incident.io). |
677
+ | `item.state` | The provider's state: `open`, `closed` or `merged` on GitHub and GitLab, the workflow state name (`In Progress`) on Linear and Jira. |
678
+ | `item.assignees` | Who the item is assigned to, as a list. |
679
+ | `item.pullRequest` | The number of the card's open pull or merge request, absent when it has none. |
680
+ | `item.trusted` | Whether the item's author has write access (see below). Rules saved with the old name `author.trusted` read as `item.trusted`. |
681
+ | `pullRequest.trusted` | On a pull request event, whether that pull request's author has write access (or Factory opened it); otherwise, whether the author of the card's working pull request does. Absent when there is neither. |
682
+ | `source.kind` | `issue`, `pull_request`, … |
683
+ | `source.integration` | The integration that filed it: `github`, `gitlab`, `linear`, `jira`, `incidentio`, … |
684
+ | `source.provider` | The provider the work item comes from; the integration for every integration Factory ships. |
685
+ | `source.repository` | Where the item lives, compared case-insensitively. GitHub: `owner/repo` (`mastra-ai/mastra`, never the bare `mastra`). GitLab: the full project path, subgroups included (`acme/platform/api`). Linear: the team key (`ENG`). Jira: the project key (`PLAT`). Absent for incident.io items (test `source.provider equals incidentio` instead) and for manual cards, which have no `source.*` facts (test `source.kind not_exists`). |
683
686
 
684
687
  Strings compare case-insensitively, so `source.repository equals Acme/App` matches `acme/app`. A list fact (`item.labels`, `item.assignees`) is tested by its members: `item.assignees equals ada` matches when Ada is one of the assignees, and an empty list counts as missing, so `item.assignees exists` matches only assigned items. A fact the item doesn't have fails every operator except `not_exists`, `not_equals`, `not_contains` and `not_in`.
685
688
 
@@ -725,11 +728,38 @@ const factory = new MastraFactory({ storage, dispatcher: { maxInFlight: 25 } });
725
728
 
726
729
  The cap counts per process, not per deployment: three replicas with the default run up to 30 at once.
727
730
 
731
+ A reply a person writes on a card's GitHub pull request or issue doesn't wait behind automated runs. Each process keeps 2 more slots for these replies, claims them ahead of automated runs, and lets them borrow a free automated slot once the reserve is full. Change the reserve with `dispatcher.maxInteractiveInFlight`, or `MASTRACODE_DISPATCH_MAX_INTERACTIVE_IN_FLIGHT`; `0` keeps no reserve, though replies are still claimed first:
732
+
733
+ ```ts
734
+ const factory = new MastraFactory({ storage, dispatcher: { maxInFlight: 10, maxInteractiveInFlight: 2 } });
735
+ ```
736
+
737
+ A run counts as a reply only when GitHub reports its sender as a user (not a bot), the sender is a trusted collaborator, Factory didn't write it, it would wake the session, and no rule passed it along from another event. Everything else, including GitLab, Linear, Jira and incident.io activity, waits as an automated run.
738
+
739
+ The caps bound how many slots the dispatcher holds, not how many agents run. With the defaults a process holds up to 12 slots. Pull request activity (`signalActivity`) frees its slot once the session accepts it, so the run it wakes continues outside the cap. Messages you send from the Factory UI or Slack, and approval notices to a following session, go to the session directly and never wait for a slot.
740
+
728
741
  The board shows how many automated runs are waiting, and opens a list of them, oldest first. A waiting card reads `Queued (#3)`. Manual starts take the same slots and are claimed ahead of these runs, but are not listed. `GET /web/factory/projects/:id/run-queue` returns the same data:
729
742
 
730
- - `slots` — this server's `inUse` and `cap`, or `null` when it runs no dispatcher. Other replicas keep their own.
743
+ - `slots` — this server's automated `inUse` and `cap`, with the reply reserve's `interactive.inUse` and `interactive.cap`, or `null` when it runs no dispatcher. A reply that borrowed an automated slot counts in `inUse`. Other replicas keep their own.
731
744
  - `running` and `claimed` — the project's automated runs a server holds a slot for, on any replica. A manual start holding a slot counts in `slots.inUse` but not here, so `running` can be lower than `inUse`.
732
- - `queuedCount` and `queued` — every automated run waiting for a slot, and the oldest 50 with their `position`, card, phase and the skill they will run. A retry still backing off is not waiting yet.
745
+ - `queuedCount` and `queued` — every run waiting for a slot, and up to 50 of them, waiting replies first, then automated runs, each oldest first, with their `lane` (`interactive` for a person's reply, else `automated`), `position` within that lane, card, phase and the skill they will run. `queuedByLane` splits `queuedCount` by lane. A retry still backing off is not waiting yet.
746
+
747
+ ### Unloading idle sessions
748
+
749
+ A loaded session holds its conversation, tool results, workspace and process output in server memory. Factory unloads a session from the process when it no longer needs it, so memory follows the sessions in use rather than every session the process has ever opened:
750
+
751
+ - **Released.** When Factory stops a session's sandbox (a card leaves the context, or finishes) the session is unloaded too.
752
+ - **Idle.** A session with no activity for 30 minutes is unloaded. Each process checks its own sessions once a minute.
753
+
754
+ A session stays loaded while a run is in flight, while it waits on an approval or an `ask_user` / `submit_plan` answer, and while a browser tab follows its stream. An idle session also stays loaded while its sandbox runs a background process the agent started, such as a dev server, because the agent can only read or stop that process through the loaded session. A released session that is busy is unloaded once its work ends.
755
+
756
+ Unloading keeps the thread, its messages, the session row and the sandbox. Unloading does not stop the sandbox; a released session's sandbox was already stopped by the release. The next message, run, wake or opened tab loads the session again on its thread and reattaches to the sandbox. Without `auth`, a deferred wake for an unloaded session waits until something else loads it, as it does after a restart. What lives only in memory is lost: session state not stored on the thread, auto-approvals granted in the session, and events from before the reload.
757
+
758
+ Change the timeout and check interval with `idleSessionUnload`. `idleMs: 0` turns off the idle check but still unloads released sessions, and `false` keeps every session loaded until it is deleted:
759
+
760
+ ```ts
761
+ const factory = new MastraFactory({ storage, idleSessionUnload: { idleMs: 60 * 60_000, sweepIntervalMs: 5 * 60_000 } });
762
+ ```
733
763
 
734
764
  ### The `factory-work-item` signal
735
765
 
@@ -908,48 +938,33 @@ Intake bindings are explicit. A Linear project, Jira project, GitLab project, in
908
938
 
909
939
  - **Linear:** each project binding feeds one Factory project.
910
940
  - **Jira:** One Jira project can feed several Factory projects: each binding takes either all issues or only issues carrying its labels (Settings › Intake › Jira routing, or `labels` on `PUT /web/intake/bindings`). Each label belongs to one binding per Jira project, and only one binding per project can take all issues. Label bindings win over the all-issues binding; an issue carrying labels of two label bindings goes to the binding created first. The split happens in the JQL each Factory sends, so every issue is filed in exactly one Factory. Labels only decide placement when an issue is first filed: relabelling an issue, or editing a binding's labels, does not move existing cards. Remove one Factory's binding with `DELETE /web/intake/bindings?integrationId=jira&sourceId=…&factoryProjectId=…`. The create-Factory flow can select a Jira project and binds it to the new Factory. Both `JiraIntegration` and `PlatformJiraIntegration` run a reconciliation sweep every five minutes by default, with or without an open browser: it reads the 150 most recently updated issues of each routed Jira project (five pages, counted per project so a busy one cannot starve the others) and files a work item for each new one, refreshes the status and metadata of imported cards, and transitions the linked card of a closed issue to done or canceled. Both accept a `rules` option to replace or disable the `issueObserved` / `issueClosed` defaults. Agents on Jira-sourced runs get `jira_get_issue` and `jira_create_comment`. Set `MASTRACODE_JIRA_RECONCILE_INTERVAL_MS` to a positive millisecond interval to change its cadence.
911
- - **GitHub:** every repository linked to the project feeds it. To send one repository's issues and pull requests to another board, add an intake route with a `source.repository` condition; for labelled issues, an `item.labels` condition. A label change on an issue updates its card's labels and never moves the card.
941
+ - **GitHub:** pull requests come from every repository linked to the project. Issues come only from repositories in the organization's GitHub list in Settings › Work Intake; linking a repository adds it to that list unless the link request sends `selectIntake: false`, and adding a repository to the list brings in its open issues. To send one repository's issues and pull requests to another board, add an intake route with a `source.repository` condition; for labelled issues, an `item.labels` condition. A label change on an issue updates its card's labels and never moves the card.
942
+
943
+ Each connected service in Settings › Work Intake lists the sources it brings in, and a service with no source selected brings in nothing: there is no separate on/off switch, and a selection saved while a service was switched off reads as empty. Vanta has a single source, every active vulnerability on the connected account, which syncs only while it is selected. Dependabot alerts keep their own switch.
912
944
 
913
945
  Label routes (`GET`/`PUT /web/intake/label-routes`) and a binding's `board` were removed: use an intake route with any condition on the work item instead, such as `item.labels contains release` or `source.repository equals acme/app`. The label-route endpoints answer `410` with `label_routes_removed`, and a `board` an older client still sends on `PUT /web/intake/bindings` is ignored. Their stored rows stay, unread.
914
946
 
915
947
  ### Intake routes
916
948
 
917
- Each project has an ordered list of intake routes: the only thing that decides where a new card lands. Admins manage them in Settings › Work Intake › Intake routes or through the API, and anyone in the project can read them. A route names the board events it handles in `on`. A route on `work_item.created`, the default, decides where a new card lands: the first enabled route whose `when` matches the card names its board and phase. A route on `work_item.closed` or `work_item.reopened` decides where an existing card moves when its source closes or reopens (see [Status events](#status-events-move-existing-cards)).
918
-
919
- **The default routes.** Every project starts with twelve routes: four for new cards, one of which files a pull request on its issue's card and the last of which takes everything else; three that move cards when their issue closes or reopens; and five that move cards when a pull request's status changes. The first, `Pull requests that close a waiting issue join its card`:
920
-
921
- ```json
922
- {
923
- "when": {
924
- "operator": "AND",
925
- "conditions": [
926
- { "field": "source.kind", "operator": "equals", "value": "pull_request" },
927
- { "field": "author.trusted", "operator": "equals", "value": true },
928
- { "field": "pullRequest.closesIssue", "operator": "equals", "value": true },
929
- { "field": "closedIssue.phase", "operator": "in", "value": ["intake"] },
930
- { "field": "closedIssue.hasPullRequest", "operator": "equals", "value": false }
931
- ]
932
- },
933
- "target": { "boardKey": "work", "phaseKey": "pr-review", "joinClosedIssue": true }
934
- }
935
- ```
949
+ Each project has an ordered list of intake routes: the only thing that decides where a new card lands. Admins manage them in Settings › Work Intake › Intake routes or through the API, and anyone in the project can read them. A route names the board events it handles in `on`. Events come in two families: `work_item.*` events are about issues, and every pull or merge request event is `pull_request.*`. A route on `work_item.opened` decides where a new issue lands, and a route on `pull_request.opened` where a new pull request with no card lands: the first enabled route whose `when` matches names its board and phase. `pull_request.opened` is also a card move: when a pull request opens for an issue's unfinished card, the card's board's `pull_request.opened` routes decide where that card moves. A route on `work_item.closed`, `work_item.reopened` or `work_item.updated` decides where an existing issue's card moves when the issue closes, reopens or has its labels or assignees changed; the `pull_request.*` routes do the same for a pull request's card (see [Status events](#status-events-move-existing-cards) and [Label and assignee changes](#label-and-assignee-changes-move-existing-cards)). `work_item.created` is the older arrival event: it files new issues and new pull requests with no card alike, and never moves a card. Routes that name it, or name no event (the default for a route created without `on`), keep that meaning, and the API keeps it as written, so editing an older route never narrows it to issues. A `pull_request.opened` route stored by Factory 0.28 or earlier only ever moved cards, and still does: it files no pull request, so it can't take an outside author's pull request ahead of the outside-authors route. The API returns it with `pullRequestOpenedMovesOnly: true` and Settings lists it with its board's card moves. Every edit keeps it that way, `on` included; to file pull requests, add a route.
936
950
 
937
- It adds a trusted author's pull request to the card of the issue it closes while that card is still waiting (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). Edit `closedIssue.phase` to let pull requests join cards further along, or delete the route to give every pull request its own card. The second, `Outside authors wait in Intake`:
951
+ **The default routes.** Every project starts with thirteen routes: four for new cards, the last two of which take every other pull request and issue; three that move cards when their issue closes or reopens; and six that move cards when a pull request's status changes or a pull request links to their issue. Issue routes are on `work_item.opened` and pull request routes on `pull_request.opened`. A project set up before routes named the two families keeps its routes as they were: its routes on `work_item.created` file issues and pull requests alike, and it isn't given `Pull requests from outside authors wait in Intake`, which its outside-authors route already covers. The first, `Outside authors wait in Intake`:
938
952
 
939
953
  ```json
940
954
  {
955
+ "on": ["work_item.opened"],
941
956
  "when": {
942
957
  "operator": "AND",
943
958
  "conditions": [
944
959
  { "field": "source.integration", "operator": "in", "value": ["github", "gitlab"] },
945
- { "field": "author.trusted", "operator": "equals", "value": false }
960
+ { "field": "item.trusted", "operator": "equals", "value": false }
946
961
  ]
947
962
  },
948
963
  "target": { "boardKey": "work", "phaseKey": "intake" }
949
964
  }
950
965
  ```
951
966
 
952
- It files GitHub and GitLab issues and pull requests from authors outside the write-access circle in Work › Intake, ahead of the routes after it. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The third, `Pull requests go to Review`, sends every other pull request and merge request (`source.kind equals pull_request`) to Work › Review, where the reviewer runs once a person starts it, or on its own when the phase has `autoStart`. Because it comes after the outside-authors route, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it is attached to the authoring card, which goes out for review. Pull requests opened before attaching existed keep their own card.
967
+ It files GitHub and GitLab issues from authors outside the write-access circle in Work › Intake, and the second, `Pull requests from outside authors wait in Intake` (on `pull_request.opened`, with `source.kind equals pull_request` too, so as a card move it never sends an issue's card back), does the same for their pull requests, ahead of the routes after it. Intake is a resting phase, so nothing starts there on its own. Any session, a person's or an agent's, can move the card on, and that move starts the next phase's run. Pushes to a pull request resting in Intake don't re-review it, and comments and edits on an issue never re-run Triage (see GitHub event rules). Trusted authors' cards, and Linear, Jira and incident.io cards (which carry no trust stamp), land where they did before. The third, `Pull requests go to Review`, has no condition and sends every other new pull request and merge request to Work › Review, where the reviewer runs once a person starts it, or on its own when the phase has `autoStart`. Because it comes after the outside-authors route, an outside author's pull request still waits in Intake. A pull request Factory opened for one of its own cards is filed by that card's rule, which no route re-places: it is attached to the authoring card, which goes out for review. Pull requests opened before attaching existed keep their own card.
953
968
 
954
969
  The other three move Work cards when their issue's status changes:
955
970
 
@@ -959,7 +974,7 @@ The other three move Work cards when their issue's status changes:
959
974
  | `Issues closed as not planned go to Canceled` | `["work_item.closed"]` | `event.reason equals canceled` | Work › Canceled |
960
975
  | `Reopened issues go back to Intake` | `["work_item.reopened"]` | none | Work › Intake |
961
976
 
962
- Five more move Work cards when a pull request's status changes. Each agrees with the move Work's default pull request rule already makes, so out of the box nothing changes; retarget one to send those cards elsewhere:
977
+ Six more move Work cards on pull request events. The first five agree with the move Work's default pull request rule already makes, so out of the box nothing changes; retarget one to send those cards elsewhere:
963
978
 
964
979
  | Route | `on` | `when` | Target |
965
980
  | ------------------------------------------------------------- | ----------------------------------- | ------------------------------------- | --------------- |
@@ -968,26 +983,29 @@ Five more move Work cards when a pull request's status changes. Each agrees with
968
983
  | `Issues whose pull request closed unmerged go back to Intake` | `["pull_request.closed"]` | `source.kind not_equals pull_request` | Work › Intake |
969
984
  | `Pushes to a reviewed pull request re-review it` | `["pull_request.synchronized"]` | none | Work › Review |
970
985
  | `Requested reviews go to Review` | `["pull_request.review_requested"]` | none | Work › Review |
986
+ | `Trusted pull requests take a waiting issue to Review` | `["pull_request.opened"]` | see below | Work › Review |
987
+
988
+ The last one handles a pull request that just linked to its issue's card (see [One card for an issue and its pull requests](#one-card-for-an-issue-and-its-pull-requests)). Its `when` requires `pullRequest.trusted`, `pullRequest.closesIssue`, `closedIssue.phase in ["intake"]` and `closedIssue.hasPullRequest equals false`. Edit `closedIssue.phase` to move cards further along too, or delete it to leave linked cards where they are.
971
989
 
972
990
  They replace the close handlers each integration used to apply on its own, so a closed GitHub, GitLab, Linear, Jira or incident.io issue lands where it did before, but you can now edit or disable that move. To stop closes from moving Work cards, disable both close routes. Deleting them does not stop the move: with no route left that handles closes, Work's `sourceClosed` mapping moves closed cards to Done or Canceled again.
973
991
 
974
- The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. The closing-issue route is the exception: it goes first, since its condition only matches trusted authors' pull requests that close an issue. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request, closing-issue or close and reopen routes existed gets them this way too.
992
+ The default routes are stored routes like any other: list them, edit them, disable them, reorder them or delete them through the API. Factory adds each one once, the first time the project's routes are read or written, appending it after the project's existing routes, and doesn't add it back after an admin deletes it. Deleting a default is permanent: recreate it by hand to get it back. A project set up before the pull request or close and reopen routes existed gets them this way too. Routes that joined a pull request to its issue's card (`joinClosedIssue: true`, such as the old default `Pull requests that close a waiting issue join its card`) are switched off once when a project gets the `Trusted pull requests take a waiting issue to Review` rule, and kept so their history stays readable; pull requests now link on their own. A switched-off join route an admin had changed from that default also gets a `rule_retired` entry in the project's intake decision log naming it, since the new rule may not do all it did: add a card-move rule on `pull_request.opened` to move cards the way it did.
975
993
 
976
- **Everything else.** The last default route, `Everything else goes to Work › Intake`, has no condition and sends every new card the routes before it don't take to Work › Intake. Point it at another board to send there every new card the routes above it don't take, or use **Send new cards to** in Settings, which also copies the close, reopen and pull request routes onto that board: a status event only moves a card through routes on the card's own board. Routes above it still apply, so with the defaults, outside authors' items still wait in Work › Intake and pull requests still go to Work › Review; disable or edit those routes to send them elsewhere too. A new route that places new cards goes just ahead of the first enabled route with no condition that takes every new card, whoever added it, so it can match. A route that only handles status events goes at the end. A project with no route left that places a card files it in the default board's first phase.
994
+ **Everything else.** The last default route, `Everything else goes to Work › Intake`, has no condition and sends every new card the routes before it don't take to Work › Intake. Point it at another board to send there every new card the routes above it don't take, or use **Send new cards to** in Settings, which also copies the close, reopen and pull request routes onto that board: a status event only moves a card through routes on the card's own board. Routes above it still apply, so with the defaults, outside authors' items still wait in Work › Intake and pull requests still go to Work › Review; disable or edit those routes to send them elsewhere too. A new route that places new cards goes just ahead of the first enabled route with no condition that takes every new card, whoever added it, so it can match. A route that only handles status events goes at the end. A project with no route left that places a card files it in the default board's first phase. Under the [intake order](#intake-order) evaluator there is no default board: an item no board's rules take is Not routed instead.
977
995
 
978
- **Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`author.trusted equals true`). Runs on untrusted cards still use their own isolated memory.
996
+ **Trust only decides where a card arrives.** Once a card is moved out of Intake, later input on it runs like on any card: a maintainer's push re-reviews an outside author's pull request. A phase that should only auto-start for trusted authors says so in its `autoStartWhen` (`item.trusted equals true`). An outside author's pull request linked to someone else's card is the exception: nothing runs on it until a person makes it the card's working pull request. Runs on untrusted cards still use their own isolated memory.
979
997
 
980
998
  **Route shape.**
981
999
 
982
- | Field | Meaning |
983
- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
984
- | `name` | Up to 120 characters. |
985
- | `enabled` | Defaults to `true`. Disabled routes are skipped. |
986
- | `on` | The board events the route handles: `work_item.created` (the default), `work_item.closed`, `work_item.reopened`, `pull_request.opened`, `pull_request.synchronized`, `pull_request.review_requested`, `pull_request.merged` and `pull_request.closed`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
987
- | `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. A route that handles more than `work_item.created` can also test `event.type` and `event.reason`. |
988
- | `target` | Required. `{ boardKey, phaseKey?, joinClosedIssue? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route on `work_item.created`, the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. With `joinClosedIssue: true`, a pull request is added to the card of the issue it closes instead of getting its own card, and that card moves to `phaseKey` when the board allows the move (otherwise it stays put); the route is skipped when there is no such card on `boardKey`, and its `on` must be `["work_item.created"]` alone. An update that sets `target` replaces the whole target, so repeat `joinClosedIssue: true` to keep a route joining. |
1000
+ | Field | Meaning |
1001
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1002
+ | `name` | Up to 120 characters. |
1003
+ | `enabled` | Defaults to `true`. Disabled routes are skipped. |
1004
+ | `on` | The board events the route handles: `work_item.created` (the default: new issues and pull requests), `work_item.opened`, `work_item.reopened`, `work_item.updated`, `work_item.closed`, `pull_request.opened`, `pull_request.reopened`, `pull_request.updated`, `pull_request.synchronized`, `pull_request.review_requested`, `pull_request.merged` and `pull_request.closed`. Each at most once. `work_item.commented` and `work_item.edited` are activity, which never moves a card, so a route can't name them. |
1005
+ | `when` | A rule over the card's facts (the same format as `autoStartWhen`). `null`, the default, matches every card. Every route can test `item.hasPullRequest` (an issue with an open pull request attached) and `item.hasIssue` (a pull request that closes or links an issue). A route that handles more than arrivals (`work_item.opened`, `work_item.created`) can also test `event.type`, `event.reason` and `card.phase` (the phase the card is in); a route on `work_item.updated` or `pull_request.updated` can test `event.labels.added`, `event.labels.removed`, `event.assignees.added` and `event.assignees.removed`. `item.key`, `item.title`, `item.state`, `source.integration`, `item.pullRequest`, `closedIssue.phase` and `closedIssue.hasPullRequest` are legacy filters: stored routes using them keep evaluating, but the editor no longer offers them. |
1006
+ | `target` | Required. `{ boardKey, phaseKey?, moveToBoardKey? }` sets where matching cards land; without `phaseKey` they land in the board's first phase. The board must be installed in the project (code or stored). For a route that files new cards (`work_item.opened`, `pull_request.opened` or `work_item.created`), the phase can't be terminal and must be reachable from the board's first phase; a route that only moves existing cards can target any phase, terminal ones included. `moveToBoardKey` lets a route on `boardKey` that names none of those events send them to `phaseKey` on another installed board (see [Status events](#status-events-move-existing-cards)). `joinClosedIssue: true` is retired: a new route can't set it (`422 join_retired`), and a stored one can only be switched off. |
989
1007
 
990
- Routes are evaluated in `position` order (0 first). Rules can test the [card facts](#phase-runners-automatic-starts-and-exit-tools) phase rules test, `source.repository` and `item.labels` among them. For pull requests, routes can also test `pullRequest.closesIssue` (`true` when the body closes an issue that has a usable card), `closedIssue.phase` and `closedIssue.hasPullRequest` (that card's phase and whether it already carries a pull request). These three are route-only: phase rules can't use them. A route that lets a pull request join a card already in its review phase doesn't start a second review: the review in progress keeps its pull request, and the new one is reviewed on its next push by a trusted author, or on a review request once the current pass has a verdict. That's why the default route requires `closedIssue.hasPullRequest` to be `false`. `author.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
1008
+ Routes are evaluated in `position` order (0 first). Rules can test the [card facts](#phase-runners-automatic-starts-and-exit-tools) phase rules test, `source.repository` and `item.labels` among them. For pull requests, routes can also test `pullRequest.closesIssue` (`true` when the body closes an issue that has a usable card), `closedIssue.phase` and `closedIssue.hasPullRequest` (that card's phase and whether it already carries a pull request). These three are route-only: phase rules can't use them. On the `pull_request.opened` a linked pull request sends its card, `closedIssue.*` describe the card as it was before the pull request linked. A card already in its review phase doesn't start a second review when another pull request links: the review in progress keeps its pull request. That's why the default rule requires `closedIssue.hasPullRequest` to be `false`. `item.trusted` is `true` when the card carries an `authorTrusted: true` or `factoryAuthored: true` stamp. GitHub and GitLab stamp `authorTrusted` from the author's repository permission, and a stamp that is missing counts as untrusted.
991
1009
 
992
1010
  **Placement.** When an integration files a new card, or a card is created without naming a board (the `factory_create_work_item` tool, or `POST /web/factory/projects/:id/work-items` without `board`), the first enabled route that matches the card and whose board can take it decides where the card lands. On the built-in boards, a pull request lands on Work only in Intake or Review and Review takes only cards with a pull request; a route a card can't take is skipped and the next one is tried. If the route's phase no longer exists, or can no longer be reached from the first phase, the card lands in the first phase. A card routed to a later phase enters the first phase and then moves on through the transition service as a system move, recorded in the card's history. The route makes this move, not a person, so it gives no consent to start work; a run the phase asks for still needs a person unless the phase starts on its own (`autoStart`). A board whose transition policy refuses system moves refuses the route, and the card is not filed. The board and phase an integration's rule names don't count: every integration files a new card in the default board's first phase, and the routes take it from there. If no route places it, it stays there. The default board is Work; a project without a Work board (one an app gave only its own boards with `upsertBoard`) uses its first board in catalog order instead, so its arrivals are still filed and placed by its routes. A project with no boards at all files nothing, and refuses cards created without a board, until a board is installed.
993
1011
 
@@ -999,9 +1017,47 @@ A card a route placed records the route's id in its `intakeRouteId` metadata and
999
1017
 
1000
1018
  A pull request routed to a board with a [pull request loop](#the-pull-request-loop-on-any-board) is reviewed there; on a board without one, review requests and pushes do nothing to its card.
1001
1019
 
1020
+ #### Intake order
1021
+
1022
+ Each board owns its intake rules: a rule places cards on its own board only, and each board has at most 100. A project also keeps an **intake order**, separate from the sidebar order: the order its boards are asked to take a new item. Under the intake order evaluator, intake asks each board in that order, and inside a board its rules top to bottom; the first enabled rule that matches and whose phase can take the card decides. Nothing names a board to fall back to. An item no board takes is **Not routed**: no card is filed, and the item is kept with the reason so an admin can fix a rule and route it again. A card created without a board that no board takes is refused with `intake_board_required` (422), so the person picks the board; `factory_create_work_item` takes that board as `board`. While the intake rules can't be read (stored boards unavailable), arrivals wait and retry, and a card created without a board is refused the same way.
1023
+
1024
+ Each project has its own evaluator. A project created since this release is stamped with `intake-order` as it is created, in the same write. A project from before it has no setting and keeps `route-list`, the evaluator described above (one list across all boards, then the default board's first phase), until an admin switches it with `PUT .../intake-order` and `{ "evaluator": "intake-order" }` (audited as `factory.intake_order.evaluator_updated`). `MastraFactory({ intake: { evaluator } })` or `FACTORY_INTAKE_EVALUATOR` (`intake-order` or `route-list`) forces one evaluator on every project, whatever its setting; the option wins over the variable. Set the same on every replica. A project uses `route-list` only when its setting was read and is empty: while the setting can't be read (stored boards unavailable), its arrivals wait and retry, a card created without a board is refused with `intake_board_required`, and Route again is refused, unless `route-list` is forced. During a rolling deploy, a replica still on an older release ignores the setting and decides every project by `route-list`, so a new project's items can be routed by the route list until every replica runs this release; a project created on such a replica gets no setting and stays on `route-list` until switched.
1025
+
1026
+ Until an admin sets it, a project's intake order is derived from the route list: boards by the position of their first enabled rule that places new cards, then boards with no such rule, in sidebar order. A project whose rules for each board sit together routes exactly as before. A project whose rules interleave boards can route differently. While the order is derived, every rule write (create, edit, delete, reorder, or deleting a board with rules) derives it again. Setting the order with `PUT .../intake-order` fixes it: rule writes no longer change it. A board created later goes into the order just above the first board whose rules end in an enabled rule with no condition (a catch-all), or last when no board has one. Deleting a board deletes its rules, each with a `factory.intake_route.deleted` audit entry carrying `cause: "board_deleted"`, and drops it from the order.
1027
+
1028
+ | Request | What it does |
1029
+ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1030
+ | `GET /web/factory/projects/:id/intake-routes?boardKey=…` | One board's rules, in their order. |
1031
+ | `POST /web/factory/projects/:id/intake-routes/reorder` | With `boardKey`, `ids` names every rule of that board; they swap among the places that board's rules hold, and other boards' rules stay put. Admin only. |
1032
+ | `PATCH /web/factory/projects/:id/intake-routes/:routeId` | Under the intake order evaluator, a `target.boardKey` other than the rule's own board is refused with `intake_route_board_fixed` (422). |
1033
+ | `GET /web/factory/projects/:id/intake-order` | The boards in intake order, whether the order is `derived` or `explicit`, the evaluator in use with `evaluatorSource` (`option`, `env`, `project`, or `legacy` for a project with no setting) and the project's own `projectEvaluator`, and a comparison of both evaluators over the project's newest 200 items against that order (`compared`, `differing`, `notRouted`), worked out on every read. |
1034
+ | `PUT /web/factory/projects/:id/intake-order` | `{ boardKeys }`, every board once, refused with `intake_order_set_mismatch` (409) otherwise. Admin only; audited as `factory.intake_order.updated`. |
1035
+ | `GET /web/factory/projects/:id/intake/not-routed` | Items no board took and nobody has filed since, oldest first, with the reason. Paged: `limit` (default 50, at most 100) and `cursor`, the `nextCursor` of the page before (null on the last). |
1036
+ | `POST /web/factory/projects/:id/intake/not-routed/:decisionId/route-again` | Runs intake for the item again, by intake order whichever evaluator the replica runs. Refused with `intake_not_routed` (422) while no board's rules take it; otherwise 202, and the dispatcher files it where the rules say. Admin only; audited as `factory.intake.routed_again`. |
1037
+ | `GET /web/factory/projects/:id/intake/skipped` | Each card-move rule that matched but was skipped because its target couldn't take the card, in the last 30 days: `routeId`, `count`, and the newest skip as `latest`. |
1038
+
1039
+ Every arrival's decision (placed or Not routed) is recorded under both evaluators. Once a card is filed for an item, by Route again or by a later delivery a fixed rule takes, its Not routed record is resolved and leaves the list.
1040
+
1041
+ #### Checking intake rules before they file anything
1042
+
1043
+ A rule that never fires, because an earlier board takes everything it would match, can't be spotted by reading the rules. Two requests show it on real items, using the intake order evaluator's own code, so under that evaluator they answer exactly what filing would. They run intake order whichever evaluator files the project, and both responses say which one does in `evaluator`: under `route-list`, filing can land items elsewhere, such as on the default board. Neither files a card, records a decision, writes an audit entry, or writes to a provider.
1044
+
1045
+ | Request | What it does |
1046
+ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1047
+ | `POST /web/factory/projects/:id/intake/dry-run` | Runs the rules over the project's newest 200 items: its cards from a source plus the Not routed items nobody filed since, from their stored facts, without fetching anything. Per board and per rule: the items it takes, the items it matched that an earlier board or rule took (`lost`, by the board that took them), and `filed`, the cards it actually filed in the last 30 days. Also the items no board takes, and per item where it lands and every rule that matched. |
1048
+ | `POST /web/factory/projects/:id/intake/test` | "Where would this go?" for one item: `itemId` (a card's or a Not routed item's id) or `url`. Answers where it lands, or why nothing takes it, and what every rule on every board answered: `took`, `lost` (with the rule that took it), `no_match` (with each failed condition and the item's value for it), `phase_refuses`, or `disabled`. |
1049
+
1050
+ Both take unsaved edits: `boards` replaces the named boards' rules with drafts (other boards run their saved rules) and `order` replaces the intake order. With either, the dry run also reports `changed`, how many items land on a different board or phase than under the saved rules, and each item's `before`. Any member can run the saved rules; unsaved edits need the role that edits rules (organization admin).
1051
+
1052
+ A draft is held to the checks saving it faces: an order that misses or invents a board is refused with `intake_order_set_mismatch` (422), and two rules sharing an `id` with `intake_draft_rule_id_repeated` (422). A `url` already on a card, as its own source or one it holds since (such as a pull request linked to an issue card), reads the card's stored facts. A recent Not routed item's `url` is read again from its provider when it can be, since a label or a reopen takes it in again with the facts it has now; otherwise its stored arrival answers. A rule that files only issues (`work_item.opened`) or only pull requests (`pull_request.opened`) answers `no_match` for the other kind, with the `source.kind` it saw as the failed condition. Any other URL is read once from its provider, and only from a GitHub repository or GitLab project linked to this project, with that link's credentials; a URL for one that isn't linked is refused with `not_linked` (422) before anything is fetched. A fetched pull request is tested as a new arrival; if it closes an issue with a card, or comes from a card's branch, filing joins it to that card instead, which `note` says. Linear, Jira and incident.io items are tested from recent items by `itemId`.
1053
+
1054
+ On a card, the tester also replays card moves. It sends the card's 10 newest status events (`opened`, `updated` with the labels and assignees that changed, `reopened`, `closed`, and the pull request events), plus one `event` sent in the request to try, through the card-move rules on the card's board, replayed against the card's current phase and facts. Pending `updated` events replay as the dispatcher acts on them: a burst is folded into its newest event with the dispatcher's own fold, and one whose labels and assignees end where they started answers `ignored`. An update that already acted replays as it was folded then, not with newer updates folded in. The tester reads the card's 200 newest decisions; an update whose burst may reach back past them answers `unknown` instead of guessing. Each answers `moves` (to which board, phase and rule), `stays`, `rule_default` (no rule handles it, so the integration's own move applies), `ignored` (the event can't move a card in its state, such as reopening one that isn't finished) or `unknown`, and lists what every rule answered: `took`, `lost`, `no_match` with the failed conditions, `skipped` (its target board or phase can't take the card) or `disabled`. The dispatcher moves cards through the same code, so a replay of a pending event answers what the dispatcher will do with it. A URL finds the card holding that item in any form that names it: another tab of a pull request (`/files`, `/diffs`), a query string, `www.` or a different case. Sending an `event` for an item with no card is refused with `intake_event_needs_card` (422).
1055
+
1056
+ Stored facts are what Factory last saw of the item, so a dry run can differ from live data the provider changed since. A pull request's `closedIssue.*` facts come from the issue it closed at the time it arrived and aren't kept, so the dry run reads pull requests without them.
1057
+
1002
1058
  #### Status events move existing cards
1003
1059
 
1004
- Every integration reports issue status changes with the same names: `work_item.created` when an issue is first seen, `work_item.closed` when it closes, and `work_item.reopened` when it reopens (GitHub and GitLab; Linear, Jira and incident.io report opens and closes only). A close carries `event.reason`: `canceled` for GitHub's "not planned" and "duplicate" and for Linear, Jira and incident.io canceled states, `completed` otherwise (GitLab closes are always `completed`).
1060
+ Every integration reports issue status changes with the same names: `work_item.opened` when an issue is first seen, `work_item.closed` when it closes, and `work_item.reopened` when it reopens (GitHub and GitLab; Linear, Jira and incident.io report opens and closes only). A reopened GitHub or GitLab issue, pull request or merge request with no card is filed like a new one. A close carries `event.reason`: `canceled` for GitHub's "not planned" and "duplicate" and for Linear, Jira and incident.io canceled states, `completed` otherwise (GitLab closes are always `completed`).
1005
1061
 
1006
1062
  When one of these arrives for a card that already exists, the first enabled route on the card's board whose `on` names the event and whose `when` matches the card and the event moves the card to the route's phase:
1007
1063
 
@@ -1021,12 +1077,34 @@ Pull request events (GitHub and GitLab) work the same way, with these difference
1021
1077
  - A merge or close moves only an unfinished card. `pull_request.opened`, `pull_request.synchronized` and `pull_request.review_requested` move finished cards too, so a done pull request is re-reviewed on a push as before.
1022
1078
  - When the card's board has routes on the event but none enabled matches the card, the rule's own move still runs: disabling the merge route doesn't strand a merged card in review.
1023
1079
  - Pull request events never drop one another: each concerns its own pull request.
1024
- - Factory sees no pull request reopen, so there is no `pull_request.reopened`.
1080
+ - `pull_request.reopened` (GitHub) moves a card only where a route on its board names it; there is no default move. Like `synchronized`, it moves the card whatever its phase.
1025
1081
 
1026
- Only routes targeting the card's own board apply; a route naming another board is skipped. For issue status events (`work_item.closed` and `work_item.reopened`), a route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Pull request events differ, as above: when no enabled route takes the card, the rule's own move still runs. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
1082
+ Only routes on the card's own board apply; a route naming another board is skipped. A route on the card's board with `moveToBoardKey` sends the card to that board's phase, keeping the same card: the old phase's session sandbox stops, the target phase's runner starts, and the old board's `nextPhases` don't matter. The target board must take the card (its phase exists and its lanes take the card), otherwise the route is skipped and the next one is tried; the skip is kept in the project's intake decision log as a `rule_skipped` entry naming the route, the target board and why. A move to another board fires no further routes, so two boards whose rules send cards to each other move a card once per event. For issue status events (`work_item.closed` and `work_item.reopened`), a route on the card's board that names the event owns it even when it is disabled or its `when` doesn't match: the card stays put. Pull request events differ, as above: when no enabled route takes the card, the rule's own move still runs. Only on a board where no route names the event does the board's `sourceClosed` mapping apply, so custom boards keep closing as before. To stop closes from moving Work cards, disable both close routes: deleting them hands closes back to Work's `sourceClosed` mapping, which moves the card to Done or Canceled.
1027
1083
 
1028
1084
  A deployment that answers an event itself keeps routes out of it: a handler or `null` set explicitly on the integration's `rules` for `issueClosed`, `issueReopened`, `issueCommentCreated` and so on, or `null` on the card's board handlers. An override that moves nothing really moves nothing. A board handler that wraps or returns the stock close move is different: that move still goes to the routes, as the stock handler's own would.
1029
1085
 
1086
+ #### Label and assignee changes move existing cards
1087
+
1088
+ `work_item.updated` and `pull_request.updated` fire only when an item's labels or assignees change; title, body and draft edits never do. They carry what changed in `event.labels.added`, `event.labels.removed`, `event.assignees.added` and `event.assignees.removed`, so "move to Ship when `ship` is added" is `event.labels.added contains ship`. An issue's change reports `work_item.updated`; a pull or merge request's reports `pull_request.updated`, whether it has a card of its own or is attached to an issue's card. Don't confuse the board event `pull_request.updated` (a label or assignee change) with the provider rule key `pullRequestUpdated`, which is a push to the pull request and fires the board event `pull_request.synchronized`.
1089
+
1090
+ - An update moves a card whatever its phase, like `synchronized`; use `card.phase` to move only from one phase.
1091
+ - Changes Factory itself makes (the card's own session, through the Factory app) while the card's run is in flight are held and evaluated once when the run ends, as one combined update. "After Triage labels it, move it" works without racing the agent. The dispatcher checks for the run end about every 10 seconds, so a held update lands within about 10 seconds of the run ending.
1092
+ - Changes from people and other sources aren't held for the run: they're evaluated about 5 seconds after the last change, with several changes to one item in that window combined into one update. Like every route move, a move into a phase that isn't terminal still waits for a run in flight to end; a move to a terminal phase goes at once.
1093
+ - A combined update carries the net change: adding `bug` and removing it again is no change, and nothing fires.
1094
+ - An update never cancels a close or reopen, nor is cancelled by one.
1095
+ - A rule moving a card changes the card, not the source, so it never produces an update. Factory's own status labels (`status: needs approval`, `status: auto-triaged`) are bookkeeping in the same way: adding or removing them never counts as a change, whoever does it.
1096
+ - An update to an item with no card runs intake only when intake turned the item away (Not routed). GitHub and GitLab check the item's Not routed record: an open issue or pull request no board took that is later labelled to match a board's rule lands on that board, and its record is resolved. A closed one stays unfiled. Linear, Jira and incident.io already run intake for an item with no card on every sync that sees it change.
1097
+
1098
+ | Provider | `work_item.updated` | `pull_request.updated` | Held for the card's run |
1099
+ | ----------- | ----------------------------------------------------------- | ------------------------------ | --------------------------------------------------------- |
1100
+ | GitHub | issue `labeled`, `unlabeled`, `assigned`, `unassigned` | pull request, own or attached | when the Factory app made the change |
1101
+ | GitLab | issue hook whose `changes` carry labels or assignees | merge request, own or attached | when made as the user Factory's GitLab connection acts as |
1102
+ | Linear | a sync whose labels or assignee differ from the last sync's | no | never: polling can't tell who made the change |
1103
+ | Jira | same as Linear | no | never |
1104
+ | incident.io | same as Linear | no | never |
1105
+
1106
+ Linear, Jira and incident.io diff each sync against the labels and assignee the previous sync recorded on the card. The first sync after upgrading only records them, so existing cards don't all fire at once. Each sync records when the provider last changed the item, in the same write that queues the update, so a sync older than the one recorded, or one racing a newer sync, never rolls the card's labels back or reports a change in reverse. GitLab does the same with each hook's `updated_at`, and a redelivered hook writes nothing.
1107
+
1030
1108
  #### Activity reaches the card's session
1031
1109
 
1032
1110
  A new comment on a card's GitHub or GitLab issue, or an edit to its title or description, tells the session working the card, with pointers only:
@@ -1056,7 +1134,7 @@ A stale `expectedRevision` is refused with `409 revision_mismatch`. Each route r
1056
1134
  curl -X POST "$FACTORY_URL/web/factory/projects/$PROJECT/intake-routes" -H 'content-type: application/json' -d '{
1057
1135
  "name": "Trusted issues to Triage",
1058
1136
  "when": { "operator": "AND", "conditions": [
1059
- { "field": "author.trusted", "operator": "equals", "value": true },
1137
+ { "field": "item.trusted", "operator": "equals", "value": true },
1060
1138
  { "field": "source.kind", "operator": "equals", "value": "issue" }
1061
1139
  ] },
1062
1140
  "target": { "boardKey": "work", "phaseKey": "triage" }
@@ -1262,7 +1340,7 @@ Both integrations expose incidents and incident follow-ups as separate Intake so
1262
1340
 
1263
1341
  ### Linear workspace connections
1264
1342
 
1265
- For Platform-managed Linear connections, **Settings → Work Intake** connects and repairs workspaces in place. A disconnected workspace with saved sources shows **Reconnect** on the Linear card; healthy ones need no action. A disconnected workspace without saved sources has nothing paused, so it has no Reconnect; authorize it again with **Connect**. To add another workspace, choose **Connect** next to Linear under **Add a source**. During reconnection, choose the named workspace in Linear. Factory checks that workspace's connection when authorization returns.
1343
+ For Platform-managed Linear connections, **Settings → Work Intake** connects and repairs workspaces in place. A disconnected workspace with saved sources shows **Reconnect** on the Linear card; healthy ones need no action. A disconnected workspace without saved sources has nothing paused, so it has no Reconnect; authorize it again with **Connect**. To add another workspace, choose **Add workspace** on the Linear card. During reconnection, choose the named workspace in Linear. Factory checks that workspace's connection when authorization returns.
1266
1344
 
1267
1345
  Work Intake keeps disconnected workspaces' saved sources and routing. Their issues remain paused until access is restored. A request failure shows a retry action and does not mark the workspace disconnected. Sources and polling from healthy workspaces remain available when another workspace's source request fails.
1268
1346
 
@@ -1315,31 +1393,35 @@ A repository maintainer with write or admin access can start a Factory review fr
1315
1393
 
1316
1394
  A person's own Factory session (a user session) gets tools to find, file and manage the Factory's work items through its agent. Factory scopes the tools from the stored session row, never from the thread's `factoryProjectId` tag: the session must belong to a Factory in the caller's organization, and a private session only works for its owner. With authentication disabled, the shared `local` tenant applies. Sessions doing work for someone else, either bound to a work item's run or started as a side session, only get `factory_message_origin`, so they can report back and answer messages.
1317
1395
 
1318
- | Tool | Input |
1319
- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1320
- | `factory_list_work_items` | Optional `query` (title text or `#number`), `stage`, `board`, `role`, `active`, `requestedBy: 'me'`, `subscribed`, `limit` (default 25, max 50) |
1321
- | `factory_inspect_work_item` | `workItem` (id or `#number`) |
1322
- | `factory_list_attention` | Optional `limit` (max 50) |
1323
- | `factory_list_audit_events` | Optional `actor` (`me`, a user id or `agent:<threadId>`), `includeAgentRuns`, `namespace`, `actions`, `workItem`, `since`, `until`, `cursor`, `limit` (max 50) |
1324
- | `factory_create_work_item` | `title`, `description`, optional `repository` (`owner/name`, one this Factory links) |
1325
- | `factory_update_work_item` | `workItem` plus any of `title`, `description`, `repository`, `parentWorkItem` (or `null` to detach) |
1326
- | `factory_subscribe_work_item` | `workItem` |
1327
- | `factory_unsubscribe_work_item` | `workItem` |
1328
- | `factory_transition_work_item` | `workItem`, `stage` |
1329
- | `factory_retry_decision` | `decisionId` |
1330
- | `factory_dismiss_decision` | `decisionId` |
1331
- | `factory_resolve_proposal` | `decisionId`, `action` (`approve` or `dismiss`) |
1332
- | `factory_start_session` | `prompt` (up to 8000 characters), optional `title`, optional `model`; for a work-item role, `workItem` and `role` |
1333
- | `factory_answer_approval` | `sessionId`, `toolCallId`, `decision` (approve or decline), optional `reason` |
1334
- | `factory_switch_session_model` | `sessionId`, `modelId` |
1335
- | `factory_signal_session` | `sessionId`, `message` (up to 4000 characters), optional `priority` (`low`, `medium`, `high`, `urgent`; default `medium`) |
1336
- | `factory_message_origin` | `message`, optional `inReplyTo` (the message's notification id), optional `status` (`progress`, `blocked`, `done`, `failed`) |
1396
+ | Tool | Input |
1397
+ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1398
+ | `factory_list_work_items` | Optional `query` (title text, `#number`, or an issue or pull request reference), `stage`, `board`, `role`, `active`, `requestedBy: 'me'`, `subscribed`, `limit` |
1399
+ | `factory_inspect_work_item` | `workItem` (id, `#number`, or an issue or pull request reference) |
1400
+ | `factory_list_attention` | Optional `limit` (max 50) |
1401
+ | `factory_list_audit_events` | Optional `actor` (`me`, a user id or `agent:<threadId>`), `includeAgentRuns`, `namespace`, `actions`, `workItem`, `since`, `until`, `cursor`, `limit` (max 50) |
1402
+ | `factory_create_work_item` | `title`, `description`, optional `repository` (`owner/name`, one this Factory links) |
1403
+ | `factory_update_work_item` | `workItem` plus any of `title`, `description`, `repository`, `parentWorkItem` (or `null` to detach) |
1404
+ | `factory_subscribe_work_item` | `workItem` |
1405
+ | `factory_unsubscribe_work_item` | `workItem` |
1406
+ | `factory_transition_work_item` | `workItem`, `stage`, optional `rerun` |
1407
+ | `factory_retry_decision` | `decisionId` |
1408
+ | `factory_dismiss_decision` | `decisionId` |
1409
+ | `factory_resolve_proposal` | `decisionId`, `action` (`approve` or `dismiss`) |
1410
+ | `factory_start_session` | `prompt` (up to 8000 characters), optional `title`, optional `model` |
1411
+ | `factory_answer_approval` | `sessionId`, `toolCallId`, `decision` (approve or decline), optional `reason` |
1412
+ | `factory_switch_session_model` | `sessionId`, `modelId` |
1413
+ | `factory_signal_session` | `sessionId`, `message` (up to 4000 characters), optional `priority` (`low`, `medium`, `high`, `urgent`; default `medium`) |
1414
+ | `factory_message_origin` | `message`, optional `inReplyTo` (the message's notification id), optional `status` (`progress`, `blocked`, `done`, `failed`) |
1337
1415
 
1338
1416
  Read tools and `factory_message_origin` are available on every turn. The other tools only appear on turns a signed-in person started, so text arriving from a notification, webhook or channel can't drive them. The one exception is `factory_signal_session`: on those turns it can still message the side sessions this session started and the active sessions of work items it follows, so the session can answer the sessions it is waiting on. None of them asks for approval: they are allowed on the session when it's created, unless the person has set their own policy for the tool or for the `mcp` category.
1339
1417
 
1340
1418
  `factory_switch_session_model` changes the model of a side, work item or review session you own in the same Factory, without recreating it. It refuses a model this server can't run. A running session switches right away; a stopped one uses the model on its next run.
1341
1419
 
1342
- `factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when the Factory links more than one: a run can't start on a card that doesn't say which. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. A session that moves a card follows it from then on, so it hears from the run the move starts. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item.
1420
+ `factory_create_work_item` files the card as the caller where the project's [intake routes](#intake-routes) send it, or in the Work board's first phase when no route matches (a project without Work: its first board's), stores the description that its runs start from, and subscribes the session. Name the `repository` when you know it. A run on a card that names none starts in the environment's first repository, determines from the card which repository it belongs to, and records it on the card with its first push or change request. `factory_update_work_item` sets it afterwards, like choosing a repository on the card, and also edits the title, the description and the parent item. It can't pre-approve plans: a plan waits for a person unless the board's phase auto-approves it. Both refuse a repository the Factory doesn't link, and a card synced from an issue keeps the issue's repository. Stages, the board and role sessions aren't fields it edits; stages move with `factory_transition_work_item`. A session that moves a card follows it from then on, so it hears from the run the move starts. Subscriptions are stored per work item and session in the `factory_work_item_subscriptions` collection and are removed with the item, so any number of sessions can follow one item.
1421
+
1422
+ Every tool that takes `workItem` accepts the card's id, its `#number`, or the issue or pull request it tracks: its link (`https://github.com/acme/app/pull/12`, including links to a pull request's files or a comment), `owner/repo#12`, `group/project!7` for a GitLab merge request, or a tracker key such as `ENG-42`. A reference finds the issue's or pull request's own card first, then the card it is attached to, such as a pull request on its issue's card. A bare `#number` can belong to several repositories and prefers an issue's card, so with several repositories the link is the safe choice. A reference that matches more than one card is refused with the candidates' ids. `factory_list_work_items` takes the same references as its `query`.
1423
+
1424
+ `factory_transition_work_item` sends the requests the board's own buttons send, through the same rules: a move to another stage, or, with `rerun: true` and the stage the card is already in, a rerun of that stage, as **Start** does on the board. Asked for the card's own stage without `rerun`, it changes nothing and says so, including whether the stage's run is waiting for approval, so "move it to review" on a card that was already reviewed doesn't start another review. On a turn a person started, the run either one starts counts as approved by that person, so a run the board was holding for approval no longer waits, and a card that already has a run in flight or queued is refused as busy, as on the board. A rerun needs a person in the turn. Its result has the card's `url`, so a chat can link the card it moved. Approving a held run with `factory_resolve_proposal` starts it as the person. Retrying a failed one with `factory_retry_decision` keeps the run's original approver and needs no person in the turn. Either one makes the session follow the run's card in the same way, and their results carry the card's `url`. Following is what lets the run's report reach the session, which can then pass the outcome on in its chat. `factory_inspect_work_item` lists the card's stage, whether it can run again, and the stages its board lets it move to next, with the keys the tool takes. When someone asks for a card's own stage work without naming a session, such as a review of a pull request that has a card, the agent moves or reruns the card, so the review is recorded on the card and posted on the pull request. A side session is for work the person asks to run in one, and for work no stage does, such as pushing fixes to a pull request or taking it over.
1343
1425
 
1344
1426
  #### Messaging between sessions
1345
1427
 
@@ -1351,12 +1433,11 @@ How a message is delivered depends on its priority. `urgent` always delivers, ev
1351
1433
 
1352
1434
  #### Sub-sessions
1353
1435
 
1354
- `factory_start_session` starts another session for the caller and sends `prompt` as its first message. It has two modes:
1436
+ `factory_start_session` starts a side session for the caller and sends `prompt` as its first message: a standalone session with no work item, for work the person asks to run in a side session, or work no card stage does, such as an investigation or pushing fixes to an existing pull request. It uses the same repository as the session that started it. Factory stores that session on the new session's row (`origin_session_id`, `origin_thread_id`) and copies the parent's visibility. It runs on the model of the session that started it, or on `model` when one is passed. That model has to be one the session's credentials can run; an unknown or unrunnable model is refused before anything is created. When the parent has no model set, the side session keeps the Factory's default worker model.
1355
1437
 
1356
- - **Side session** (no `workItem`): a standalone session with no work item, for a one-off job. It uses the same repository as the session that started it. Factory stores that session on the new session's row (`origin_session_id`, `origin_thread_id`) and copies the parent's visibility. It runs on the model of the session that started it, or on `model` when one is passed. That model has to be one the session's credentials can run; an unknown or unrunnable model is refused before anything is created. When the parent has no model set, the side session keeps the Factory's default worker model.
1357
- - **Work-item role** (`workItem` and `role`): starts a role the item's board seats, the same way **Start** does in the Factory UI. The card does not move and no autonomy is armed. The tool refuses when the role already has a session, naming it so the agent can message it instead, and refuses an item linked to several repositories. The caller is subscribed to the item, and the run is recorded as `factory.run.started` with the caller as the person who started it.
1438
+ The tool doesn't start a card's roles. A card's work starts the way the board starts it, with `factory_transition_work_item`, so the board's rules (which stage the card is in, whether it is busy) decide it, and the card's session belongs to whoever the board's runs belong to.
1358
1439
 
1359
- A side session belongs to the caller and runs with the caller's credentials. A work-item role belongs to the caller only in a Factory on the `user` model scope. Where card work runs on the organization's keys (`factory` and `hybrid`), the role's session belongs to the Factory itself, as every phase session there does, whoever started or moved the card: the person is recorded as the one who started it, and their session follows the card so it hears when that run waits on someone and can approve or decline from there. Without an organization model key the start is refused with a message saying to add one. A work-item role keeps the Factory's default worker model. The first message runs with only the session's owner as its user, never the rest of the parent turn's context. The tool needs no approval but, like the other management tools, only appears on turns a signed-in person started.
1440
+ A side session belongs to the caller and runs with the caller's credentials. The first message runs with only the session's owner as its user, never the rest of the parent turn's context. The tool needs no approval but, like the other management tools, only appears on turns a signed-in person started.
1360
1441
 
1361
1442
  #### Reports
1362
1443
 
@@ -1393,9 +1474,9 @@ The tools take their scope as an argument rather than reading the request, so th
1393
1474
 
1394
1475
  ### Mastra Connect and your own tools in sessions
1395
1476
 
1396
- With Platform credentials and `MASTRA_PROJECT_ID`, every Factory session gets the [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect) tools of each connection attached to the Platform project. Attach and remove connections in Mastra Platform, on the project's **Connect** page. The organization's other connections reach sessions only once they're attached, and a new project has none. **Settings → Tools** lists what sessions get, read from the same Platform list. Platform deploys get both variables automatically. Anywhere else, including locally, set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_SECRET_KEY` or `MASTRA_PLATFORM_ACCESS_TOKEN`. Attach Linear, and a Slack thread, a web chat or a work item can ask about its issues.
1477
+ With Platform credentials and `MASTRA_PROJECT_ID`, every Factory session gets the [Mastra Connect](https://mastra.ai/docs/mastra-platform/connect) tools of each connection attached to the Platform project. Attach and remove connections in Mastra Platform, on the project's **Connect** page. The organization's other connections reach sessions only once they're attached, and a new project has none. **Settings → Tools** lists what sessions get, read from the same Platform list. Expand a connection to see its tools, resolved the way a session you start would resolve them: tools that ask for approval are marked, and tools Factory leaves out are listed with the reason. Platform deploys get both variables automatically. Anywhere else, including locally, set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_SECRET_KEY` or `MASTRA_PLATFORM_ACCESS_TOKEN`. Attach Linear, and a Slack thread, a web chat or a work item can ask about its issues.
1397
1478
 
1398
- Sessions run these tools without asking while automatic approval is on, so only attach accounts whose actions sessions may take. When a person turns approval off, the tools follow the `mcp` permission category, except in Slack with `adapterOptions.toolDisplay: 'text'`, where every tool call is approved automatically. Tools with `delete` or `archive` anywhere in their name, in any case, are left out. That check goes by name only, so it can't catch every destructive action, such as a SQL tool running a `DROP`. GitHub and GitLab Connect tools are left out too: Factory's own source-control tools enforce repository scope and self-review, and Connect's would skip both. Every user and organization on the Factory shares the project's connections, and a connection attached for another app on the same project reaches Factory sessions too. `GET /web/integrations/platform/connect-tools` backs the settings page.
1479
+ Sessions run these tools without asking while automatic approval is on, so only attach accounts whose actions sessions may take. When a person turns approval off, the tools follow the `mcp` permission category, except in Slack with `adapterOptions.toolDisplay: 'text'`, where every tool call is approved automatically. Tools with `delete` or `archive` anywhere in their name, in any case, are left out. That check goes by name only, so it can't catch every destructive action, such as a SQL tool running a `DROP`. GitHub and GitLab Connect tools are left out too: Factory's own source-control tools enforce repository scope and self-review, and Connect's would skip both. Every user and organization on the Factory shares the project's connections, and a connection attached for another app on the same project reaches Factory sessions too. `GET /web/integrations/platform/connect-tools` and `GET /web/integrations/platform/connect-tools/tools` back the settings page.
1399
1480
 
1400
1481
  Connect caches the connection list for 30 seconds. When a later refresh fails, sessions keep the last list it got, including a connection removed since, until a refresh succeeds. A run with no list yet waits at most 15 seconds for one, then goes on without Connect tools, and Factory logs why. If the Platform stalls instead of failing, later runs also go without them until that listing answers or fails.
1401
1482
 
@@ -1411,6 +1492,8 @@ const factory = new MastraFactory({
1411
1492
  });
1412
1493
  ```
1413
1494
 
1495
+ With `tools` set, **Settings → Tools** still lists the project's connections, and says sessions get tools from code: a connection reaches sessions only if your `tools` includes it, with the tools it narrows to. Each connection's tool list shows what your `tools` gives sessions from it, and tools from no listed connection, such as MCP tools, appear under **Other tools from code**. A `tools` function that reads the request sees the signed-in user's request there, not a session's. Without Platform credentials or `MASTRA_PROJECT_ID`, the page names whichever of the two is missing.
1496
+
1414
1497
  A tool named like one Factory already gives the session, such as `linear_get_issue` from a connected Linear integration, is not offered, and Factory logs that once per name. When resolving the tools you pass throws, the run fails with that error.
1415
1498
 
1416
1499
  Factory doesn't read MCP servers from the host's `mcp.json` files, and logs a warning at startup when `~/.mastracode/mcp.json` exists. Pass MCP tools through `tools` instead: