@grok/agent-sdk 0.2.29 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (396) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/docs/404.html +2 -2
  3. package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
  4. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  5. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  6. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  7. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  8. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  9. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  10. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
  11. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  12. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
  13. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  14. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  15. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  16. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  17. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  18. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  24. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  25. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  26. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  27. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  28. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  29. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  30. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  33. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  34. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  35. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  36. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  37. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
  38. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  39. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  40. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  41. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  42. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
  43. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
  44. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
  45. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  46. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  47. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  48. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  49. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  50. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  51. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  52. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  53. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
  54. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  55. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  56. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  57. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  58. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  59. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  60. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  61. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  62. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  63. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  64. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  65. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  66. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  67. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  68. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  69. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  70. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  72. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  74. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  75. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  76. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  77. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  78. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  80. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  81. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  82. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  83. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  84. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  85. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  86. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  87. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  88. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  89. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  90. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  91. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  92. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  93. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  94. package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
  95. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  96. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  97. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  98. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  99. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  100. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  101. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  102. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  103. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  104. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  105. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  106. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  107. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  108. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  109. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  110. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  111. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  112. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  113. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  114. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  115. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  116. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  117. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  118. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  119. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  120. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  121. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  122. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  123. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  124. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  125. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  126. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  127. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  128. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  129. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  130. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  131. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  132. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  133. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  134. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  135. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  136. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  137. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  138. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  139. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  140. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  141. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  142. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  143. package/dist/docs/building-with-agents.html +41 -44
  144. package/dist/docs/building-with-agents.md +11 -104
  145. package/dist/docs/changelog.html +37 -37
  146. package/dist/docs/changelog.md +5 -155
  147. package/dist/docs/deployment.html +54 -54
  148. package/dist/docs/deployment.md +83 -262
  149. package/dist/docs/evals.html +52 -71
  150. package/dist/docs/evals.md +33 -129
  151. package/dist/docs/guides/agent-to-agent.html +43 -43
  152. package/dist/docs/guides/agent-to-agent.md +27 -64
  153. package/dist/docs/guides/bitbucket.html +62 -62
  154. package/dist/docs/guides/bitbucket.md +73 -134
  155. package/dist/docs/guides/cloud-agents.html +37 -37
  156. package/dist/docs/guides/cloud-agents.md +23 -53
  157. package/dist/docs/guides/convert-automation.html +39 -56
  158. package/dist/docs/guides/convert-automation.md +31 -115
  159. package/dist/docs/guides/github.html +46 -54
  160. package/dist/docs/guides/github.md +49 -131
  161. package/dist/docs/guides/gitlab.html +98 -108
  162. package/dist/docs/guides/gitlab.md +104 -184
  163. package/dist/docs/guides/improve.html +38 -43
  164. package/dist/docs/guides/improve.md +24 -90
  165. package/dist/docs/guides/jev.html +55 -95
  166. package/dist/docs/guides/jev.md +53 -160
  167. package/dist/docs/guides/mcp-oauth.html +38 -40
  168. package/dist/docs/guides/mcp-oauth.md +33 -67
  169. package/dist/docs/guides/migrate.html +38 -43
  170. package/dist/docs/guides/migrate.md +56 -130
  171. package/dist/docs/guides/opentelemetry.html +41 -43
  172. package/dist/docs/guides/opentelemetry.md +32 -27
  173. package/dist/docs/guides/pagerduty.html +50 -49
  174. package/dist/docs/guides/pagerduty.md +65 -199
  175. package/dist/docs/guides/slack.html +51 -57
  176. package/dist/docs/guides/slack.md +76 -204
  177. package/dist/docs/guides/webhooks.html +42 -42
  178. package/dist/docs/guides/webhooks.md +64 -146
  179. package/dist/docs/hashmap.json +1 -1
  180. package/dist/docs/hillclimbing.html +40 -42
  181. package/dist/docs/hillclimbing.md +40 -102
  182. package/dist/docs/index.html +55 -61
  183. package/dist/docs/index.md +49 -83
  184. package/dist/docs/llms-full.txt +2262 -5721
  185. package/dist/docs/llms.txt +9 -14
  186. package/dist/docs/quickstart.html +95 -152
  187. package/dist/docs/quickstart.md +91 -180
  188. package/dist/docs/reference/access.html +36 -36
  189. package/dist/docs/reference/access.md +7 -12
  190. package/dist/docs/reference/agent-config.html +43 -56
  191. package/dist/docs/reference/agent-config.md +91 -174
  192. package/dist/docs/reference/artifacts.html +38 -39
  193. package/dist/docs/reference/artifacts.md +38 -62
  194. package/dist/docs/reference/channels.html +38 -39
  195. package/dist/docs/reference/channels.md +102 -151
  196. package/dist/docs/reference/cli.html +68 -84
  197. package/dist/docs/reference/cli.md +232 -697
  198. package/dist/docs/reference/connections.html +45 -57
  199. package/dist/docs/reference/connections.md +83 -164
  200. package/dist/docs/reference/evals.html +47 -54
  201. package/dist/docs/reference/evals.md +75 -141
  202. package/dist/docs/reference/extensions.html +41 -43
  203. package/dist/docs/reference/extensions.md +37 -70
  204. package/dist/docs/reference/hooks.html +40 -52
  205. package/dist/docs/reference/hooks.md +62 -133
  206. package/dist/docs/reference/http-api.html +38 -42
  207. package/dist/docs/reference/http-api.md +66 -118
  208. package/dist/docs/reference/instructions.html +39 -39
  209. package/dist/docs/reference/instructions.md +19 -29
  210. package/dist/docs/reference/limits.html +38 -38
  211. package/dist/docs/reference/limits.md +9 -21
  212. package/dist/docs/reference/memory.html +37 -38
  213. package/dist/docs/reference/memory.md +38 -75
  214. package/dist/docs/reference/playground.html +36 -36
  215. package/dist/docs/reference/playground.md +14 -22
  216. package/dist/docs/reference/project-layout.html +49 -48
  217. package/dist/docs/reference/project-layout.md +38 -84
  218. package/dist/docs/reference/schedules.html +46 -48
  219. package/dist/docs/reference/schedules.md +59 -90
  220. package/dist/docs/reference/sessions.html +37 -37
  221. package/dist/docs/reference/sessions.md +66 -113
  222. package/dist/docs/reference/skills.html +39 -39
  223. package/dist/docs/reference/skills.md +11 -31
  224. package/dist/docs/reference/subagents.html +37 -37
  225. package/dist/docs/reference/subagents.md +17 -31
  226. package/dist/docs/reference/tools.html +47 -64
  227. package/dist/docs/reference/tools.md +48 -130
  228. package/dist/docs/templates/agentic-owners.html +38 -38
  229. package/dist/docs/templates/agentic-owners.md +50 -74
  230. package/dist/docs/templates/reviews.html +69 -0
  231. package/dist/docs/templates/reviews.md +71 -0
  232. package/dist/docs/troubleshooting.html +38 -36
  233. package/dist/docs/troubleshooting.md +48 -101
  234. package/dist/internal/cli-deploy.js +1 -1
  235. package/dist/internal/cli-docs.js +1 -1
  236. package/dist/internal/cli-images.js +1 -1
  237. package/dist/internal/cli-skills.js +1 -1
  238. package/dist/internal/cursor/credentials.js +1 -1
  239. package/dist/internal/deploy-manifest.d.ts +1 -0
  240. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  241. package/dist/internal/deploy-manifest.js +0 -1
  242. package/dist/internal/discovery/agent-config.d.ts +2 -6
  243. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  244. package/dist/internal/discovery/agent-config.js +8 -25
  245. package/dist/internal/discovery/agent.d.ts.map +1 -1
  246. package/dist/internal/discovery/agent.js +2 -3
  247. package/dist/internal/discovery/project.d.ts.map +1 -1
  248. package/dist/internal/discovery/project.js +15 -0
  249. package/dist/internal/init-project.d.ts.map +1 -1
  250. package/dist/internal/init-project.js +7 -5
  251. package/dist/internal/reminder-runner.js +1 -1
  252. package/dist/internal/session-engine.js +1 -1
  253. package/dist/internal/shallow-clone.js +1 -1
  254. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  255. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  256. package/dist/playground/index.html +2 -2
  257. package/dist/types.d.ts +4 -17
  258. package/dist/types.d.ts.map +1 -1
  259. package/docs/README.md +49 -83
  260. package/docs/building-with-agents.md +11 -104
  261. package/docs/changelog.md +6 -156
  262. package/docs/deployment.md +83 -262
  263. package/docs/evals.md +34 -130
  264. package/docs/guides/agent-to-agent.md +27 -64
  265. package/docs/guides/bitbucket.md +73 -134
  266. package/docs/guides/cloud-agents.md +23 -53
  267. package/docs/guides/convert-automation.md +31 -115
  268. package/docs/guides/github.md +49 -131
  269. package/docs/guides/gitlab.md +104 -184
  270. package/docs/guides/improve.md +24 -90
  271. package/docs/guides/jev.md +53 -160
  272. package/docs/guides/mcp-oauth.md +33 -67
  273. package/docs/guides/migrate.md +56 -130
  274. package/docs/guides/opentelemetry.md +37 -27
  275. package/docs/guides/pagerduty.md +68 -200
  276. package/docs/guides/slack.md +76 -204
  277. package/docs/guides/webhooks.md +64 -146
  278. package/docs/hillclimbing.md +41 -103
  279. package/docs/quickstart.md +91 -180
  280. package/docs/reference/access.md +7 -12
  281. package/docs/reference/agent-config.md +91 -174
  282. package/docs/reference/artifacts.md +38 -62
  283. package/docs/reference/channels.md +102 -151
  284. package/docs/reference/cli.md +232 -697
  285. package/docs/reference/connections.md +83 -164
  286. package/docs/reference/evals.md +75 -141
  287. package/docs/reference/extensions.md +37 -70
  288. package/docs/reference/hooks.md +61 -132
  289. package/docs/reference/http-api.md +66 -118
  290. package/docs/reference/instructions.md +20 -30
  291. package/docs/reference/limits.md +10 -22
  292. package/docs/reference/memory.md +38 -75
  293. package/docs/reference/playground.md +14 -22
  294. package/docs/reference/project-layout.md +38 -84
  295. package/docs/reference/schedules.md +59 -90
  296. package/docs/reference/sessions.md +66 -113
  297. package/docs/reference/skills.md +12 -32
  298. package/docs/reference/subagents.md +17 -31
  299. package/docs/reference/tools.md +48 -130
  300. package/docs/templates/agentic-owners.md +50 -74
  301. package/docs/templates/reviews.md +76 -0
  302. package/docs/troubleshooting.md +48 -101
  303. package/package.json +2 -2
  304. package/skills/deploy/SKILL.md +1 -1
  305. package/skills/migrate-v2/SKILL.md +0 -1
  306. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  307. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  308. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  309. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  310. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  311. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  312. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  313. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  314. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  315. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  316. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  317. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  318. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  319. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  320. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  321. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  322. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  323. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  324. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  325. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  326. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  327. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  328. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  329. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  330. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  331. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  332. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  333. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  334. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  335. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  336. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  337. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  338. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  339. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  340. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  341. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  342. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  343. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  344. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  345. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  346. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  347. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  348. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  349. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  350. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  351. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  352. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  353. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  354. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  355. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  356. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  357. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  358. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  359. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  360. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  361. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  362. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  363. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  364. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  365. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  366. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  367. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  368. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  369. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  370. package/dist/docs/guides/hooks.html +0 -113
  371. package/dist/docs/guides/hooks.md +0 -116
  372. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  373. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  374. package/dist/docs/package/skills/github/SKILL.md +0 -133
  375. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  376. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  377. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  378. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  379. package/dist/docs/reference/prompt.html +0 -68
  380. package/dist/docs/reference/prompt.md +0 -47
  381. package/dist/docs/templates/security-reviewer.html +0 -62
  382. package/dist/docs/templates/security-reviewer.md +0 -81
  383. package/dist/docs/templates/thermo-quality-review.html +0 -62
  384. package/dist/docs/templates/thermo-quality-review.md +0 -75
  385. package/dist/docs/templates/thermo-review.html +0 -62
  386. package/dist/docs/templates/thermo-review.md +0 -75
  387. package/dist/docs/templates/triage.html +0 -68
  388. package/dist/docs/templates/triage.md +0 -101
  389. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  390. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  391. package/docs/guides/hooks.md +0 -121
  392. package/docs/reference/prompt.md +0 -52
  393. package/docs/templates/security-reviewer.md +0 -86
  394. package/docs/templates/thermo-quality-review.md +0 -80
  395. package/docs/templates/thermo-review.md +0 -80
  396. package/docs/templates/triage.md +0 -106
@@ -5,24 +5,24 @@ description: "Let your agent read pull requests and CI, then write back reviews,
5
5
 
6
6
  # GitHub agents
7
7
 
8
- GitHub agents work both directions. They wake from repo events, read the
9
- latest PR and CI state, then write back reviews, comments, checks, or
10
- pushes. Pull events from Cursor, so you don't expose a public webhook
11
- URL.
8
+ A GitHub agent wakes from repo events, reads the latest PR and CI state,
9
+ then writes back reviews, comments, checks, or pushes. Every wake for the
10
+ same pull request resumes one session, so the open, later comments, and
11
+ CI results share one conversation.
12
12
 
13
13
  Connect GitHub in Cursor for the repos you care about (Settings or
14
- [cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in
15
- with `agent-sdk login`. `cursorAccount` reuses that connection for
16
- events and API calls. You don't set up a GitHub App or a PAT.
14
+ [cursor.com/dashboard](https://cursor.com/dashboard)), then sign the host
15
+ in with `agent-sdk login`. `cursorAccount` reuses that connection for
16
+ events and API calls, so you don't need a public webhook URL, a GitHub
17
+ App, or a personal access token.
17
18
 
18
- Start from a template when one fits:
19
- [security reviewer](../templates/security-reviewer.md) or
20
- [issue triager](../templates/triage.md).
19
+ For a complete reviewer or issue triager, start from the
20
+ [review and triage templates](../templates/reviews.md).
21
21
 
22
22
  ## Review a pull request
23
23
 
24
- Wake when a PR is ready for review. Fetch the latest diff in a tool,
25
- then post a verdict.
24
+ When someone opens a pull request or marks it ready for review, the agent
25
+ starts a turn, reads the change, and posts its verdict as a review.
26
26
 
27
27
  ```ts
28
28
  // bot/channels/github.ts
@@ -86,8 +86,8 @@ export default defineTool({
86
86
  });
87
87
  ```
88
88
 
89
- The wake tells you the PR changed. Fetch title, files, and checks inside
90
- the turn or a tool.
89
+ The event only tells you that the pull request changed. Read the title,
90
+ files, and checks during the turn.
91
91
 
92
92
  ## Answer a mention
93
93
 
@@ -135,31 +135,21 @@ export default defineTool({
135
135
  });
136
136
  ```
137
137
 
138
- Resolve owner, repo, and number from the session. Do not take a PR URL
139
- from the model. A later mention on the same PR resumes this
140
- conversation.
138
+ The tool reads the pull request from the session, so the model never
139
+ picks where the comment goes.
141
140
 
142
141
  ## Triage a failing check
143
142
 
144
- Start a model turn when CI fails. Run host code when the next step is
145
- already decided.
143
+ When CI fails, this hook labels the pull request with host code and no
144
+ model turn. Return `{ auth: defaultGitHubAuth(ctx) }` instead when the
145
+ agent should read the logs and decide what to do.
146
146
 
147
147
  ```ts
148
148
  onCheckSuite: (ctx, suite) => {
149
149
  if (suite.conclusion !== "failure") {
150
150
  return null;
151
151
  }
152
- // `auth` starts a model turn to read logs and comment.
153
- return { auth: defaultGitHubAuth(ctx) };
154
- },
155
- ```
156
-
157
- ```ts
158
- onCheckSuite: (ctx, suite) => {
159
- if (suite.conclusion !== "failure") {
160
- return null;
161
- }
162
- // `task` runs host code instead of a model turn. No chat session.
152
+ // `task` runs host code instead of a model turn.
163
153
  return { task: () => labelFailure(ctx, suite) };
164
154
  },
165
155
  ```
@@ -184,37 +174,18 @@ async function labelFailure(ctx, suite) {
184
174
 
185
175
  Declare a hook for each event that should wake the agent:
186
176
  `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`, `onCheckRun`,
187
- `onWorkflowRun`, `onStatus`, and the catch-all `onEvent`.
188
-
189
- Each hook returns one of three outcomes:
190
-
191
- | Return | Use when |
192
- | ---------- | ----------------------------------------------------------------------------- |
193
- | `{ auth }` | The model should reason about the event. The turn shows up in the playground. |
194
- | `{ task }` | Host code can handle the wake. No chat session. |
195
- | `null` | Skip the event. |
196
-
197
- [Channels](../reference/channels.md) covers the shared session behavior.
177
+ `onWorkflowRun`, `onStatus`, and the catch-all `onEvent`. Each hook
178
+ returns `{ auth }`, `{ task }`, or `null`, as
179
+ [handler results](../reference/channels.md#handler-results) describes.
198
180
 
199
181
  ## Choose watched repositories
200
182
 
201
- The examples above list their repositories in the channel with
202
- `cursorAccount: { repos: [...] }`. A hosted deployment receives events for the
203
- repositories set at deploy time, so pass each one to `agent-sdk deploy`:
204
-
205
- ```text
206
- agent-sdk deploy --dir . --cursor-events-repo acme/checkout
207
- ```
208
-
209
- To keep the list out of source, set `cursorAccount: true` and pass the
210
- repositories on the command line instead. `agent-sdk serve` takes repeatable
211
- `--repo` flags:
212
-
213
- ```ts
214
- export default githubChannel({
215
- cursorAccount: true,
216
- });
217
- ```
183
+ The examples above list their repositories with
184
+ `cursorAccount: { repos: [...] }`, and every repository in one channel
185
+ must share one GitHub owner. To keep the list out of source, set
186
+ `cursorAccount: true` and pass `--repo` to `agent-sdk serve`. A hosted
187
+ deployment watches the repositories you pass to `agent-sdk deploy` in
188
+ both cases.
218
189
 
219
190
  ```text
220
191
  agent-sdk serve --dir . --cursor-events \
@@ -224,26 +195,15 @@ agent-sdk deploy --dir . \
224
195
  --cursor-events-repo acme/payments
225
196
  ```
226
197
 
227
- The `--cursor-events-repo` flags on a deploy form its complete list and
228
- replace the previous one, so pass every repository on each redeploy. A deploy
229
- without the flag watches the agent's GitHub source repository instead. Use
230
- [`agent-sdk deployment update`](../reference/cli.md#deployment-update) to change or clear the
231
- list without redeploying.
232
-
233
- ## PR and agent affinity
234
-
235
- Every wake for the same repo and PR number resumes the same session. The
236
- channel keys turns as `github-pr:acme/checkout#42`. Opens, comments, and
237
- CI results share that conversation.
198
+ Each deploy replaces the previous list, so pass every repository each
199
+ time. Use [`agent-sdk deployment update`](../reference/cli.md#deployment-update)
200
+ to change the list without redeploying.
238
201
 
239
202
  ## Call GitHub from deterministic code via `ctx`
240
203
 
241
- `cursorAccount` puts one credential on both surfaces:
204
+ With `cursorAccount`, hooks (`ctx.github.getOctokit()`) and tools (`ctx.host.github.getOctokit()`) share one credential. Hooks can also use `ctx.thread.post()`, `ctx.repository`, and `ctx.conversation`.
242
205
 
243
- - Channel hooks: `ctx.github.getOctokit()`, `ctx.thread.post()`,
244
- `ctx.repository`, and `ctx.conversation`
245
-
246
- - Tools: `ctx.host.github.getOctokit()`
206
+ This hook reads the pull request, skips a draft, and posts before the model turn:
247
207
 
248
208
  ```ts
249
209
  onPullRequest: async (ctx, pr) => {
@@ -264,16 +224,9 @@ onPullRequest: async (ctx, pr) => {
264
224
  },
265
225
  ```
266
226
 
267
- Re-read the PR here when the hook must decide. Tools use the host
268
- client for the same API during the turn.
269
-
270
227
  ## Batch events
271
228
 
272
- A change to a single request typically fans out multiple events, sometimes hundreds. A push can fire `synchronize`, several check runs,
273
- and comments in a few seconds. By default, individual channel hooks or webhooks do not debounce for you.
274
-
275
- Coalesce per PR. Flush the latest wake. Skip a flush when a turn for
276
- that PR is already running.
229
+ GitHub can send many events for one pull request within a few seconds. Coalesce them per pull request:
277
230
 
278
231
  ```ts
279
232
  const pending = new Map();
@@ -294,12 +247,12 @@ function enqueue(pr, flush) {
294
247
  }
295
248
  ```
296
249
 
297
- Persist that buffer across restarts and drop the queue when the PR
298
- closes.
250
+ Persist that buffer across restarts, and drop it when the pull request closes.
299
251
 
300
252
  ## Test with replay
301
253
 
302
- Use Agent SDK to replay a PR you can read.
254
+ `agent-sdk github replay` reads a pull request you can access and posts
255
+ GitHub-shaped events to your channel.
303
256
 
304
257
  ```text
305
258
  agent-sdk github replay https://github.com/acme/checkout/pull/42 --dir . --action opened
@@ -307,27 +260,15 @@ agent-sdk github replay https://github.com/acme/checkout/pull/42 --dir . --actio
307
260
  # Replay everything the channel listens for, with CI failing
308
261
  agent-sdk github replay acme/checkout#42 --dir . --events '*' --conclusion failure
309
262
 
310
- # Snapshot payloads as fixtures instead of POSTing
263
+ # Save the payloads as fixtures instead of posting them
311
264
  agent-sdk github replay acme/checkout#42 --dir . --events '*' --dry-run --fixtures-dir fixtures/github
312
265
  ```
313
266
 
314
- ## Practices
315
-
316
- - Re-read GitHub in the turn or a tool. Do not stuff the event payload
317
- into the prompt.
318
-
319
- - Set `botName` so replies do not re-wake the agent.
320
-
321
- - Watch an explicit repo list (`cursorAccount.repos`). Repos under one
322
- channel must share one GitHub owner.
323
-
324
- - Cancel leftover work on `pull_request.closed`.
325
-
326
-
327
267
  ## Other hosts
328
268
 
329
- The same hooks work on GitHub Enterprise Server. Point the channel at
330
- your server and add a repo webhook:
269
+ The same hooks work on GitHub Enterprise Server, and on github.com when
270
+ you already receive GitHub webhooks yourself. Point the channel at your
271
+ server:
331
272
 
332
273
  ```ts
333
274
  export default githubChannel({
@@ -343,36 +284,13 @@ export default githubChannel({
343
284
 
344
285
  Add a repository webhook for
345
286
  `https://<your-host>/<slug>/v1/channels/github` with the same secret.
346
- Event pull and `github replay` target GitHub.com, so test Enterprise
347
- Server with saved fixtures.
348
-
349
- Prefer event pull on github.com. Use the channel route directly when
350
- you already terminate GitHub webhooks yourself. Set a webhook secret on
351
- both sides and name it, as above, rather than reading it: locally the
352
- channel reads that environment variable, and on Cursor hosting the
353
- platform verifies `X-Hub-Signature-256` with the deployment secret of
354
- that name at ingestion, so an unsigned or mis-signed delivery gets a
355
- `401` back to GitHub before any compute starts. A literal or function
356
- value keeps verification inside the handler only. The
357
- [Webhooks guide](./webhooks.md) covers the shared mechanism.
358
-
359
- Name the API credentials the same way. Every `credentials` field —
360
- `token`, `installationToken`, `appId`, `privateKey`, `webhookSecret` —
361
- takes `{ secretName: "NAME" }`: locally the channel reads that
362
- environment variable, and on Cursor hosting the deployment secret of
363
- that name. `deploy` then lists the names the agent expects and warns
364
- about any that are not set yet, before the first API call fails inside
365
- the guest. `architecture: "v2"` requires the named form (a numeric
366
- `appId` is configuration and stays allowed); omitting a field keeps its
367
- env fallback. `architecture: "v1"` still accepts literals and
368
- `() => process.env.X` getters.
287
+ On Cursor hosting, a delivery with a missing or wrong signature gets a
288
+ `401` and never reaches your agent. Event pull and `github replay` only
289
+ reach github.com, so test Enterprise Server with saved fixtures.
290
+
291
+ Pass each credential as `{ secretName: "NAME" }`. When you run locally, the channel reads the environment variable with that name, and on Cursor hosting it reads the deployment secret with that name. To set those secrets on a deployment, see [Add egress and secrets](../deployment.md#add-egress-and-secrets).
369
292
 
370
293
  ## Related
371
294
 
372
- - [Build a PR reviewer](../quickstart.md): the full read and write
373
- loop, one step at a time
374
- - [Webhooks and custom channels](./webhooks.md): the HTTP mechanism
375
- under this pack
376
- - [Evals](../evals.md): turn replay snapshots into regression fixtures
377
- - [`skills/github/SKILL.md`](../../skills/github/SKILL.md): the companion
378
- skill for coding agents
295
+ - [Build a PR reviewer](../quickstart.md) covers the full loop.
296
+ - Ask a coding agent to follow the `bdk-github` skill for the GitHub setup steps.
@@ -5,17 +5,42 @@ description: "Review merge requests, answer notes, and triage failed pipelines o
5
5
 
6
6
  # GitLab agents
7
7
 
8
- A GitLab agent wakes from a verified project event, reads the current
9
- project or merge-request state, and writes the result back to GitLab.
10
- `gitlabChannel()` supports the same hooks on GitLab.com and self-managed
11
- GitLab.
8
+ A GitLab agent wakes on merge request, note, and pipeline events from
9
+ GitLab.com or a self-managed server, then writes its results back to the
10
+ project. Declare `onMergeRequest`, `onNote`, or `onPipeline` on
11
+ `gitlabChannel()` for each event that should wake it.
12
+
13
+ ## Connect a project
14
+
15
+ Name the project hook secret and list the projects that may wake the
16
+ agent. Set `apiBaseUrl` for a self-managed server, and leave it out for
17
+ GitLab.com.
18
+
19
+ ```ts
20
+ // bot/channels/gitlab.ts
21
+ import { gitlabChannel } from "@grok/agent-sdk/channels/gitlab";
22
+
23
+ export default gitlabChannel({
24
+ projects: ["acme/platform"],
25
+ webhookSecret: { secretName: "GITLAB_WEBHOOK_SECRET" },
26
+ apiBaseUrl: "https://gitlab.example.com/api/v4",
27
+ });
28
+ ```
29
+
30
+ Add a project webhook for
31
+ `https://<your-host>/<slug>/v1/channels/gitlab` with the same secret. On
32
+ Cursor hosting, a delivery with the wrong secret gets a `401` and never
33
+ reaches your agent. `ctx.gitlab` calls the API with the token in
34
+ `GITLAB_TOKEN`. To set both secrets on a deployment, see
35
+ [Add egress and secrets](../deployment.md#add-egress-and-secrets).
36
+
37
+ For GitLab.com on Cursor hosting, you can skip the project webhook. Set
38
+ `cursorAccount: { projects: ["acme/platform"] }`, and events and
39
+ `ctx.gitlab` calls go through your signed-in Cursor account.
12
40
 
13
41
  ## Review a merge request
14
42
 
15
- Opening, reopening, or pushing commits to a merge request starts a
16
- review. The hook reads the latest diff through the project-bound GitLab
17
- client, the model returns a verdict, and the completed answer appears
18
- as a note on the merge request.
43
+ Read the latest diff, then post the finished review as a note:
19
44
 
20
45
  ```ts
21
46
  // bot/channels/gitlab.ts
@@ -23,12 +48,8 @@ import {
23
48
  createGitLabApi,
24
49
  defaultGitLabAuth,
25
50
  gitlabChannel,
26
- gitlabChannelStateForEvent,
27
51
  } from "@grok/agent-sdk/channels/gitlab";
28
- import {
29
- postMergeRequestNote,
30
- setPipelineTriageStatus,
31
- } from "../lib/gitlab.js";
52
+ import { postMergeRequestNote } from "../lib/gitlab.js";
32
53
 
33
54
  export default gitlabChannel({
34
55
  projects: ["acme/platform"],
@@ -84,17 +105,11 @@ export default gitlabChannel({
84
105
  });
85
106
  ```
86
107
 
87
- `postMergeRequestNote` is a small wrapper around the GitLab REST API.
88
- Configure it with the same API token and base described under
89
- [Connect](#connect). It uses the project and MR IID stored from the
90
- verified event, so the model never chooses where its review is posted.
108
+ `postMergeRequestNote` is a helper you write that posts through the GitLab API with `GITLAB_TOKEN`. It uses the project and merge request stored from the event.
91
109
 
92
110
  ## Answer a note
93
111
 
94
- Mentioning `@cursor-reviewer` in an MR note resumes that merge
95
- request's conversation, and the reply sink from the first example posts
96
- the answer back to the same MR. The author guard drops notes written by
97
- the agent itself, preventing each reply from starting another turn.
112
+ Skip the agent's own notes, and answer a note that mentions the agent:
98
113
 
99
114
  ```ts
100
115
  const AGENT_USERNAME = "cursor-reviewer";
@@ -113,38 +128,42 @@ onNote: (ctx, note) => {
113
128
  },
114
129
  ```
115
130
 
116
- `onNote` receives merge-request notes by default. Add this property to
117
- the same `gitlabChannel()` declaration as the review handler.
131
+ Add this property to the same `gitlabChannel()` as the review handler.
118
132
 
119
133
  ## Triage a failed pipeline
120
134
 
121
- When a pipeline fails, GitLab immediately shows a running
122
- `cursor/pipeline-triage` status on the commit. The webhook is
123
- acknowledged while the model investigates, then the status changes to
124
- success or failure based on whether that triage turn completed.
135
+ When a pipeline fails, the example marks the commit status as `running`
136
+ and starts a triage turn. When the turn finishes, it sets the status to
137
+ success or failure.
125
138
 
126
139
  ```ts
127
- onPipeline: (ctx, pipeline) => {
128
- if (pipeline.status !== "failed" || pipeline.sha === undefined) {
129
- return null;
130
- }
131
- const sha = pipeline.sha;
132
-
133
- return {
134
- // `task` runs this host sequence after the webhook is acknowledged.
135
- task: async ({ send }) => {
136
- await ctx.gitlab.setCommitStatus({
137
- sha,
138
- state: "running",
139
- name: "cursor/pipeline-triage",
140
- description: "Investigating failed pipeline",
141
- });
140
+ // bot/channels/gitlab.ts
141
+ import {
142
+ defaultGitLabAuth,
143
+ gitlabChannel,
144
+ gitlabChannelStateForEvent,
145
+ } from "@grok/agent-sdk/channels/gitlab";
146
+ import { setPipelineTriageStatus } from "../lib/gitlab.js";
142
147
 
143
- await send(
144
- `Triage failed GitLab pipeline ${pipeline.id}.`,
145
- {
148
+ export default gitlabChannel({
149
+ projects: ["acme/platform"],
150
+ webhookSecret: { secretName: "GITLAB_WEBHOOK_SECRET" },
151
+ onPipeline: (ctx, pipeline) => {
152
+ if (pipeline.status !== "failed" || pipeline.sha === undefined) {
153
+ return null;
154
+ }
155
+ const sha = pipeline.sha;
156
+ return {
157
+ // `task` runs host code, and `send` starts the model turn.
158
+ task: async ({ send }) => {
159
+ await ctx.gitlab.setCommitStatus({
160
+ sha,
161
+ state: "running",
162
+ name: "cursor/pipeline-triage",
163
+ description: "Investigating failed pipeline",
164
+ });
165
+ await send(`Triage failed GitLab pipeline ${pipeline.id}.`, {
146
166
  auth: defaultGitLabAuth(ctx),
147
- title: `GitLab pipeline ${pipeline.id}`,
148
167
  state: {
149
168
  ...gitlabChannelStateForEvent({
150
169
  project: ctx.project,
@@ -152,153 +171,54 @@ onPipeline: (ctx, pipeline) => {
152
171
  eventType: ctx.eventType,
153
172
  }),
154
173
  },
155
- }
156
- );
174
+ });
175
+ },
176
+ };
177
+ },
178
+ events: {
179
+ async "message.completed"(event, channel, ctx) {
180
+ if (
181
+ ctx.session.purpose === "eval" ||
182
+ channel.state.eventType !== "pipeline" ||
183
+ channel.state.headSha === null ||
184
+ event.data.finishReason === "tool_call"
185
+ ) {
186
+ return;
187
+ }
188
+ await setPipelineTriageStatus(channel.state.projectPath, channel.state.headSha, "success");
189
+ },
190
+ async "turn.failed"(_event, channel, ctx) {
191
+ if (
192
+ ctx.session.purpose === "eval" ||
193
+ channel.state.eventType !== "pipeline" ||
194
+ channel.state.headSha === null
195
+ ) {
196
+ return;
197
+ }
198
+ await setPipelineTriageStatus(channel.state.projectPath, channel.state.headSha, "failed");
157
199
  },
158
- };
159
- },
160
- ```
161
-
162
- Extend the `events` map so the turn's terminal event concludes the
163
- status through the same provider wrapper:
164
-
165
- ```ts
166
- async "message.completed"(event, channel, ctx) {
167
- if (
168
- ctx.session.purpose !== "eval" &&
169
- channel.state.eventType === "pipeline" &&
170
- channel.state.headSha !== null &&
171
- event.data.finishReason !== "tool_call"
172
- ) {
173
- await setPipelineTriageStatus(
174
- channel.state.projectPath,
175
- channel.state.headSha,
176
- "success",
177
- "Pipeline triage complete"
178
- );
179
- return;
180
- }
181
-
182
- // Continue with the merge-request reply branch from the first example.
183
- },
184
- async "turn.failed"(_event, channel, ctx) {
185
- if (
186
- ctx.session.purpose === "eval" ||
187
- channel.state.eventType !== "pipeline" ||
188
- channel.state.headSha === null
189
- ) {
190
- return;
191
- }
192
- await setPipelineTriageStatus(
193
- channel.state.projectPath,
194
- channel.state.headSha,
195
- "failed",
196
- "Pipeline triage failed"
197
- );
198
- },
199
- ```
200
-
201
- The status reports whether triage completed; it does not change the
202
- failed pipeline's own result.
203
-
204
- ## Events
205
-
206
- Use `onMergeRequest`, `onNote`, or `onPipeline` for the events shown
207
- above. Each hook returns one of three decisions:
208
-
209
- | Return | What happens |
210
- | --- | --- |
211
- | `{ auth }` | Start a model turn as the GitLab event sender |
212
- | `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
213
- | `null` | Skip the event |
214
-
215
- The [Channels reference](../reference/channels.md) covers the remaining
216
- hook and session behavior.
217
-
218
- ## Merge request affinity
219
-
220
- Every merge-request event and note for the same project path and MR IID
221
- resumes one agent session. An open, a new commit, and a later mention
222
- therefore share the same conversation.
223
-
224
- ## Call GitLab through `ctx.gitlab`
225
-
226
- Each hook receives a GitLab client already bound to the project from
227
- the verified delivery. Use `ctx.gitlab.request()` for REST calls,
228
- `setCommitStatus()` for one status update, or `createCheck()` when you
229
- need a status handle that changes throughout longer work.
230
-
231
- The project does not come from model output. Keep API calls on this
232
- bound client so the event decides where reads and writes go.
233
-
234
- ## Connect
235
-
236
- On Cursor-managed hosting, use the signed-in Cursor account and list
237
- the GitLab.com projects that may wake the agent:
238
-
239
- ```ts
240
- export default gitlabChannel({
241
- cursorAccount: {
242
- projects: ["acme/platform"],
243
200
  },
244
201
  });
245
202
  ```
246
203
 
247
- `cursorAccount` covers event delivery and API calls made through
248
- `ctx.gitlab` inside hooks. The `postMergeRequestNote` and
249
- `setPipelineTriageStatus` wrappers are separate REST clients, so
250
- configure their GitLab API credential too.
251
-
252
- For direct webhooks or self-managed GitLab, configure the project hook
253
- secret, API token, and allowed projects. Add the API base for a
254
- self-managed host:
255
-
256
- ```ts
257
- export default gitlabChannel({
258
- projects: ["acme/platform"],
259
- webhookSecret: { secretName: "GITLAB_WEBHOOK_SECRET" },
260
- token: () => process.env.GITLAB_TOKEN ?? "",
261
- apiBaseUrl: "https://gitlab.example.com/api/v4",
262
- });
263
- ```
264
-
265
- Without `webhookSecret`, the direct production route stays
266
- loopback-only. Setting it admits deliveries that carry the matching
267
- project-hook secret; `token` authorizes the API reads and writes in the
268
- examples.
269
-
270
- Name the secret rather than reading it. Locally the channel reads that
271
- environment variable, and on Cursor hosting the platform compares
272
- `X-Gitlab-Token` with the deployment secret of that name at ingestion,
273
- so a delivery with the wrong token gets a `401` before any compute
274
- starts. `architecture: "v2"` requires the named form and `agent-sdk validate`
275
- rejects a literal or `() => process.env.X` getter there; set the value
276
- with `agent-sdk secret set <slug> GITLAB_WEBHOOK_SECRET`.
204
+ `setPipelineTriageStatus` is a small helper you write in
205
+ `bot/lib/gitlab.ts`. It updates the same `cursor/pipeline-triage` status
206
+ through the GitLab API with `GITLAB_TOKEN`, using the project and commit
207
+ from the session state, so the model never picks where it writes.
277
208
 
278
- Register the project webhook at
279
- `https://<your-host>/<slug>/v1/channels/gitlab` with the same secret.
280
- For GitLab.com, omit `apiBaseUrl`.
209
+ Each hook returns `{ auth }`, `{ task }`, or `null`, as
210
+ [handler results](../reference/channels.md#handler-results) describes.
211
+ Every event and note on one merge request resumes the same session.
281
212
 
282
- ## Test locally
213
+ ## Test with replay
283
214
 
284
- Replay lets you exercise the same channel hooks with a merge request
285
- you can read before registering a live project webhook.
215
+ Replay a merge request you can read against your local agent, or save the
216
+ payloads as fixtures.
217
+ [`gitlab replay`](../reference/cli.md#replay-other-webhooks) lists every
218
+ flag.
286
219
 
287
220
  ```text
288
221
  agent-sdk dev
289
- agent-sdk gitlab replay \
290
- https://gitlab.example.com/acme/platform/-/merge_requests/42 \
291
- --events '*'
222
+ agent-sdk gitlab replay acme/platform!42 --events pipeline --conclusion failed
223
+ agent-sdk gitlab replay acme/platform!42 --events '*' --dry-run --fixtures-dir fixtures/gitlab
292
224
  ```
293
-
294
- Use `--dry-run --out fixtures/gitlab` to save the payloads instead of
295
- posting them. `GITLAB_TOKEN` needs read access to the merge request.
296
-
297
- ## Related
298
-
299
- - [Channels reference](../reference/channels.md): channel hooks,
300
- dispatch decisions, and session behavior
301
- - [Webhooks and custom channels](./webhooks.md): direct webhook auth
302
- and reply delivery
303
- - [Evals](../evals.md): turn saved GitLab payloads into regression
304
- fixtures