@grok/agent-sdk 0.2.29 → 0.4.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 (451) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  3. package/dist/channels/slack/slack-channel.js +27 -14
  4. package/dist/docs/404.html +2 -2
  5. package/dist/docs/assets/{app.DMrZKFjI.js → app.BSH__xV4.js} +4 -4
  6. package/dist/docs/assets/building-with-agents.md.Bo3ct-rf.js +6 -0
  7. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.Bo3ct-rf.lean.js} +1 -1
  8. package/dist/docs/assets/changelog.md.b6H_ea44.js +1 -0
  9. package/dist/docs/assets/changelog.md.b6H_ea44.lean.js +1 -0
  10. package/dist/docs/assets/chunks/@localSearchIndexroot.CiRGcfZg.js +1 -0
  11. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.Cadl7A0k.js} +1 -1
  12. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.K7t9nNY6.js} +1 -1
  13. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.SlHEknkX.js} +1 -1
  14. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.DJLRMLkz.js} +1 -1
  15. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.Bs6XxFpe.js} +1 -1
  16. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.CyLg6Ovc.js} +1 -1
  17. package/dist/docs/assets/chunks/channel.CVTdqYx0.js +1 -0
  18. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.DTQ4TinT.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.Es84IgcH.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.Clm3cGPQ.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DE4CRkS5.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.Bf8HCvqp.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.eub-7nSx.js} +1 -1
  24. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.WyP9VAS_.js} +1 -1
  25. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.LO9ohhDE.js} +1 -1
  26. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CsJJyx6-.js +1 -0
  27. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CsJJyx6-.js +1 -0
  28. package/dist/docs/assets/chunks/clone.Dk8KvtOB.js +1 -0
  29. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.D5za6aH0.js} +1 -1
  30. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.Dq1daUru.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.j1YL5BKS.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.Bi1aLdhC.js} +1 -1
  33. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.BOzMEkAr.js} +1 -1
  34. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.Dx2FVhCr.js} +1 -1
  35. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.DI4TNkye.js} +1 -1
  36. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.C58Z9uPK.js} +1 -1
  37. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.DXSpW809.js} +1 -1
  38. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B955oaFl.js} +1 -1
  39. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.BQXhKtxS.js} +1 -1
  40. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.Dozj_-Gm.js} +1 -1
  41. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D2140OzH.js} +1 -1
  42. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.DrqrMhCk.js} +1 -1
  43. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Dv-LTrlw.js} +1 -1
  44. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.CGtHp49X.js} +1 -1
  45. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.CHZLYB52.js} +1 -1
  46. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.D4Vt3eIy.js} +1 -1
  47. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BBfpYTea.js} +1 -1
  48. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.BVYvElmY.js} +1 -1
  49. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.C6Gc2mdY.js} +1 -1
  50. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.DWa8b4cn.js} +1 -1
  51. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.Bi-g4ajv.js} +1 -1
  52. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.DlU3vVN9.js} +1 -1
  53. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.CeqJRqnU.js} +1 -1
  54. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.DE0BnUZh.js +1 -0
  55. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DGq7D4tt.js} +2 -2
  56. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.Cqf2kjq9.js} +1 -1
  57. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.BeOpE_lM.js} +1 -1
  58. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.FMQXA-6q.js} +1 -1
  59. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.BXS65dAC.js} +1 -1
  60. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.haEiSxqc.js} +1 -1
  61. package/dist/docs/assets/deployment.md.DJtuDVLh.js +31 -0
  62. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.DJtuDVLh.lean.js} +1 -1
  63. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  64. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  65. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.DcB3nhOz.js} +8 -8
  66. package/dist/docs/assets/guides_agent-to-agent.md.DcB3nhOz.lean.js +1 -0
  67. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  68. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  69. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  70. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  71. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  72. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.CcuZ7keS.js} +11 -19
  74. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.CcuZ7keS.lean.js} +1 -1
  75. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  76. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  77. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  78. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  80. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  81. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.GVPMKcYl.js} +3 -5
  82. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.GVPMKcYl.lean.js} +1 -1
  83. package/dist/docs/assets/guides_migrate.md.B8CZxnnX.js +3 -0
  84. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.B8CZxnnX.lean.js} +1 -1
  85. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  86. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  87. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  88. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  89. package/dist/docs/assets/guides_slack.md.D7Rwyva4.js +82 -0
  90. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.D7Rwyva4.lean.js} +1 -1
  91. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  92. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  93. package/dist/docs/assets/hillclimbing.md.M51bF-oT.js +5 -0
  94. package/dist/docs/assets/hillclimbing.md.M51bF-oT.lean.js +1 -0
  95. package/dist/docs/assets/index.md.DnJPj_B6.js +14 -0
  96. package/dist/docs/assets/index.md.DnJPj_B6.lean.js +1 -0
  97. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  98. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  99. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  100. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  101. package/dist/docs/assets/reference_agent-config.md.BSNp2uJ7.js +27 -0
  102. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.BSNp2uJ7.lean.js} +1 -1
  103. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  104. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  105. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  106. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  107. package/dist/docs/assets/reference_cli.md.DHm6DmYk.js +83 -0
  108. package/dist/docs/assets/reference_cli.md.DHm6DmYk.lean.js +1 -0
  109. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  110. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  111. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  112. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  113. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  114. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  115. package/dist/docs/assets/reference_hooks.md.vbIM394-.js +39 -0
  116. package/dist/docs/assets/reference_hooks.md.vbIM394-.lean.js +1 -0
  117. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  118. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  119. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  120. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  121. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  122. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  123. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  124. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  125. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  126. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  127. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  128. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  129. package/dist/docs/assets/reference_schedules.md.Dd8_d0WG.js +45 -0
  130. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.Dd8_d0WG.lean.js} +1 -1
  131. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  132. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  133. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  134. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  135. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  136. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  137. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  138. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  139. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  140. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  141. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  142. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  143. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  144. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  145. package/dist/docs/building-with-agents.html +41 -44
  146. package/dist/docs/building-with-agents.md +11 -104
  147. package/dist/docs/changelog.html +37 -37
  148. package/dist/docs/changelog.md +14 -145
  149. package/dist/docs/deployment.html +54 -54
  150. package/dist/docs/deployment.md +97 -270
  151. package/dist/docs/evals.html +52 -71
  152. package/dist/docs/evals.md +33 -129
  153. package/dist/docs/guides/agent-to-agent.html +43 -43
  154. package/dist/docs/guides/agent-to-agent.md +29 -64
  155. package/dist/docs/guides/bitbucket.html +62 -62
  156. package/dist/docs/guides/bitbucket.md +73 -134
  157. package/dist/docs/guides/cloud-agents.html +37 -37
  158. package/dist/docs/guides/cloud-agents.md +23 -53
  159. package/dist/docs/guides/convert-automation.html +39 -56
  160. package/dist/docs/guides/convert-automation.md +31 -115
  161. package/dist/docs/guides/github.html +46 -54
  162. package/dist/docs/guides/github.md +49 -131
  163. package/dist/docs/guides/gitlab.html +98 -108
  164. package/dist/docs/guides/gitlab.md +104 -184
  165. package/dist/docs/guides/improve.html +38 -43
  166. package/dist/docs/guides/improve.md +24 -90
  167. package/dist/docs/guides/jev.html +55 -95
  168. package/dist/docs/guides/jev.md +53 -160
  169. package/dist/docs/guides/mcp-oauth.html +38 -40
  170. package/dist/docs/guides/mcp-oauth.md +33 -67
  171. package/dist/docs/guides/migrate.html +38 -43
  172. package/dist/docs/guides/migrate.md +56 -130
  173. package/dist/docs/guides/opentelemetry.html +41 -43
  174. package/dist/docs/guides/opentelemetry.md +32 -27
  175. package/dist/docs/guides/pagerduty.html +50 -49
  176. package/dist/docs/guides/pagerduty.md +65 -199
  177. package/dist/docs/guides/slack.html +51 -57
  178. package/dist/docs/guides/slack.md +76 -204
  179. package/dist/docs/guides/webhooks.html +42 -42
  180. package/dist/docs/guides/webhooks.md +64 -146
  181. package/dist/docs/hashmap.json +1 -1
  182. package/dist/docs/hillclimbing.html +40 -42
  183. package/dist/docs/hillclimbing.md +40 -102
  184. package/dist/docs/index.html +49 -61
  185. package/dist/docs/index.md +42 -82
  186. package/dist/docs/llms-full.txt +2272 -5711
  187. package/dist/docs/llms.txt +9 -14
  188. package/dist/docs/quickstart.html +95 -152
  189. package/dist/docs/quickstart.md +91 -180
  190. package/dist/docs/reference/access.html +36 -36
  191. package/dist/docs/reference/access.md +7 -12
  192. package/dist/docs/reference/agent-config.html +45 -58
  193. package/dist/docs/reference/agent-config.md +92 -176
  194. package/dist/docs/reference/artifacts.html +38 -39
  195. package/dist/docs/reference/artifacts.md +38 -62
  196. package/dist/docs/reference/channels.html +38 -39
  197. package/dist/docs/reference/channels.md +102 -151
  198. package/dist/docs/reference/cli.html +68 -84
  199. package/dist/docs/reference/cli.md +232 -697
  200. package/dist/docs/reference/connections.html +45 -57
  201. package/dist/docs/reference/connections.md +83 -164
  202. package/dist/docs/reference/evals.html +47 -54
  203. package/dist/docs/reference/evals.md +75 -141
  204. package/dist/docs/reference/extensions.html +41 -43
  205. package/dist/docs/reference/extensions.md +37 -70
  206. package/dist/docs/reference/hooks.html +40 -52
  207. package/dist/docs/reference/hooks.md +62 -133
  208. package/dist/docs/reference/http-api.html +38 -42
  209. package/dist/docs/reference/http-api.md +66 -118
  210. package/dist/docs/reference/instructions.html +39 -39
  211. package/dist/docs/reference/instructions.md +19 -29
  212. package/dist/docs/reference/limits.html +38 -38
  213. package/dist/docs/reference/limits.md +9 -21
  214. package/dist/docs/reference/memory.html +37 -38
  215. package/dist/docs/reference/memory.md +38 -75
  216. package/dist/docs/reference/playground.html +36 -36
  217. package/dist/docs/reference/playground.md +14 -22
  218. package/dist/docs/reference/project-layout.html +49 -48
  219. package/dist/docs/reference/project-layout.md +38 -84
  220. package/dist/docs/reference/schedules.html +44 -46
  221. package/dist/docs/reference/schedules.md +59 -90
  222. package/dist/docs/reference/sessions.html +37 -37
  223. package/dist/docs/reference/sessions.md +66 -113
  224. package/dist/docs/reference/skills.html +39 -39
  225. package/dist/docs/reference/skills.md +11 -31
  226. package/dist/docs/reference/subagents.html +37 -37
  227. package/dist/docs/reference/subagents.md +17 -31
  228. package/dist/docs/reference/tools.html +47 -64
  229. package/dist/docs/reference/tools.md +48 -130
  230. package/dist/docs/templates/agentic-owners.html +38 -38
  231. package/dist/docs/templates/agentic-owners.md +50 -74
  232. package/dist/docs/templates/reviews.html +69 -0
  233. package/dist/docs/templates/reviews.md +71 -0
  234. package/dist/docs/troubleshooting.html +38 -36
  235. package/dist/docs/troubleshooting.md +48 -101
  236. package/dist/filesystem.d.ts +7 -320
  237. package/dist/filesystem.d.ts.map +1 -1
  238. package/dist/filesystem.js +10 -691
  239. package/dist/index.d.ts +1 -1
  240. package/dist/index.d.ts.map +1 -1
  241. package/dist/index.js +1 -1
  242. package/dist/internal/authored-alias-hooks.d.ts +6 -0
  243. package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
  244. package/dist/internal/authored-alias-hooks.js +12 -0
  245. package/dist/internal/authored-loaders.js +10 -1
  246. package/dist/internal/cli/commands/scaffold.js +1 -1
  247. package/dist/internal/cli-deploy.js +1 -1
  248. package/dist/internal/cli-docs.js +1 -1
  249. package/dist/internal/cli-images.js +1 -1
  250. package/dist/internal/cli-skills.js +1 -1
  251. package/dist/internal/continuation-session-ids.d.ts +15 -0
  252. package/dist/internal/continuation-session-ids.d.ts.map +1 -0
  253. package/dist/internal/continuation-session-ids.js +43 -0
  254. package/dist/internal/cursor/credentials.js +1 -1
  255. package/dist/internal/deploy-manifest.d.ts +1 -0
  256. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  257. package/dist/internal/deploy-manifest.js +0 -1
  258. package/dist/internal/discovery/agent-config.d.ts +2 -6
  259. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  260. package/dist/internal/discovery/agent-config.js +8 -25
  261. package/dist/internal/discovery/agent.d.ts.map +1 -1
  262. package/dist/internal/discovery/agent.js +2 -3
  263. package/dist/internal/discovery/project.d.ts.map +1 -1
  264. package/dist/internal/discovery/project.js +15 -0
  265. package/dist/internal/filesystem/walk.d.ts +1 -5
  266. package/dist/internal/filesystem/walk.d.ts.map +1 -1
  267. package/dist/internal/filesystem/walk.js +1 -9
  268. package/dist/internal/hosted-catch-protocol.d.ts +3 -3
  269. package/dist/internal/hosted-catch-protocol.js +3 -3
  270. package/dist/internal/hosted-fetch.d.ts +7 -0
  271. package/dist/internal/hosted-fetch.d.ts.map +1 -0
  272. package/dist/internal/hosted-fetch.js +26 -0
  273. package/dist/internal/init-project.d.ts.map +1 -1
  274. package/dist/internal/init-project.js +7 -5
  275. package/dist/internal/install-cursor-skills.d.ts +5 -6
  276. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  277. package/dist/internal/install-cursor-skills.js +19 -4
  278. package/dist/internal/mcp-endpoint.js +4 -4
  279. package/dist/internal/model-config.d.ts.map +1 -1
  280. package/dist/internal/model-config.js +11 -4
  281. package/dist/internal/platform-timers.d.ts +3 -7
  282. package/dist/internal/platform-timers.d.ts.map +1 -1
  283. package/dist/internal/platform-timers.js +10 -51
  284. package/dist/internal/reminder-runner.js +1 -1
  285. package/dist/internal/server.d.ts.map +1 -1
  286. package/dist/internal/server.js +6 -1
  287. package/dist/internal/session-engine.d.ts +3 -0
  288. package/dist/internal/session-engine.d.ts.map +1 -1
  289. package/dist/internal/session-engine.js +13 -4
  290. package/dist/internal/shallow-clone.js +1 -1
  291. package/dist/playground/assets/index-Bno25Cg0.css +1 -0
  292. package/dist/playground/assets/index-SGKsaznh.js +62 -0
  293. package/dist/playground/index.html +2 -2
  294. package/dist/types.d.ts +6 -17
  295. package/dist/types.d.ts.map +1 -1
  296. package/dist/types.js +2 -2
  297. package/docs/README.md +42 -82
  298. package/docs/building-with-agents.md +11 -104
  299. package/docs/changelog.md +15 -146
  300. package/docs/deployment.md +97 -270
  301. package/docs/evals.md +34 -130
  302. package/docs/guides/agent-to-agent.md +29 -64
  303. package/docs/guides/bitbucket.md +73 -134
  304. package/docs/guides/cloud-agents.md +23 -53
  305. package/docs/guides/convert-automation.md +31 -115
  306. package/docs/guides/github.md +49 -131
  307. package/docs/guides/gitlab.md +104 -184
  308. package/docs/guides/improve.md +24 -90
  309. package/docs/guides/jev.md +53 -160
  310. package/docs/guides/mcp-oauth.md +33 -67
  311. package/docs/guides/migrate.md +56 -130
  312. package/docs/guides/opentelemetry.md +37 -27
  313. package/docs/guides/pagerduty.md +68 -200
  314. package/docs/guides/slack.md +76 -204
  315. package/docs/guides/webhooks.md +64 -146
  316. package/docs/hillclimbing.md +41 -103
  317. package/docs/quickstart.md +91 -180
  318. package/docs/reference/access.md +7 -12
  319. package/docs/reference/agent-config.md +92 -176
  320. package/docs/reference/artifacts.md +38 -62
  321. package/docs/reference/channels.md +102 -151
  322. package/docs/reference/cli.md +232 -697
  323. package/docs/reference/connections.md +83 -164
  324. package/docs/reference/evals.md +75 -141
  325. package/docs/reference/extensions.md +37 -70
  326. package/docs/reference/hooks.md +61 -132
  327. package/docs/reference/http-api.md +66 -118
  328. package/docs/reference/instructions.md +20 -30
  329. package/docs/reference/limits.md +10 -22
  330. package/docs/reference/memory.md +38 -75
  331. package/docs/reference/playground.md +14 -22
  332. package/docs/reference/project-layout.md +38 -84
  333. package/docs/reference/schedules.md +59 -90
  334. package/docs/reference/sessions.md +66 -113
  335. package/docs/reference/skills.md +12 -32
  336. package/docs/reference/subagents.md +17 -31
  337. package/docs/reference/tools.md +48 -130
  338. package/docs/templates/agentic-owners.md +50 -74
  339. package/docs/templates/reviews.md +76 -0
  340. package/docs/troubleshooting.md +48 -101
  341. package/package.json +4 -4
  342. package/skills/cli/SKILL.md +1 -1
  343. package/skills/create-agent/SKILL.md +61 -7
  344. package/skills/debug/SKILL.md +1 -1
  345. package/skills/deploy/SKILL.md +3 -3
  346. package/skills/evals/SKILL.md +1 -1
  347. package/skills/framework-map/SKILL.md +2 -2
  348. package/skills/github/SKILL.md +1 -1
  349. package/skills/hillclimb/SKILL.md +1 -1
  350. package/skills/mcp-auth/SKILL.md +1 -1
  351. package/skills/migrate-v2/SKILL.md +2 -3
  352. package/skills/otel/SKILL.md +1 -1
  353. package/skills/setup-slack/SKILL.md +2 -2
  354. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  355. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  356. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  357. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  358. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  359. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  360. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  361. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  362. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  363. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  364. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  365. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  366. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  367. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  368. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  369. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  370. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  371. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  372. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  373. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  374. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  375. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  376. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  377. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  378. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  379. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  380. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  381. package/dist/docs/assets/index.md.CAruw_rp.lean.js +0 -1
  382. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  383. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  384. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  385. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  386. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  387. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  388. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  389. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  390. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  391. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  392. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  393. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  394. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  395. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  396. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  397. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  398. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  399. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  400. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  401. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  402. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  403. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  404. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  405. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  406. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  407. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  408. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  409. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  410. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  411. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  412. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  413. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  414. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  415. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  416. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  417. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  418. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  419. package/dist/docs/guides/hooks.html +0 -113
  420. package/dist/docs/guides/hooks.md +0 -116
  421. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  422. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  423. package/dist/docs/package/skills/github/SKILL.md +0 -133
  424. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  425. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  426. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  427. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  428. package/dist/docs/reference/prompt.html +0 -68
  429. package/dist/docs/reference/prompt.md +0 -47
  430. package/dist/docs/templates/security-reviewer.html +0 -62
  431. package/dist/docs/templates/security-reviewer.md +0 -81
  432. package/dist/docs/templates/thermo-quality-review.html +0 -62
  433. package/dist/docs/templates/thermo-quality-review.md +0 -75
  434. package/dist/docs/templates/thermo-review.html +0 -62
  435. package/dist/docs/templates/thermo-review.md +0 -75
  436. package/dist/docs/templates/triage.html +0 -68
  437. package/dist/docs/templates/triage.md +0 -101
  438. package/dist/internal/filesystem/errors.d.ts +0 -64
  439. package/dist/internal/filesystem/errors.d.ts.map +0 -1
  440. package/dist/internal/filesystem/errors.js +0 -180
  441. package/dist/internal/filesystem/merge.d.ts +0 -34
  442. package/dist/internal/filesystem/merge.d.ts.map +0 -1
  443. package/dist/internal/filesystem/merge.js +0 -154
  444. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  445. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  446. package/docs/guides/hooks.md +0 -121
  447. package/docs/reference/prompt.md +0 -52
  448. package/docs/templates/security-reviewer.md +0 -86
  449. package/docs/templates/thermo-quality-review.md +0 -80
  450. package/docs/templates/thermo-review.md +0 -80
  451. package/docs/templates/triage.md +0 -106
@@ -1,394 +0,0 @@
1
- ---
2
- name: bdk-migrate-v2
3
- description: >-
4
- Migrate an Agent SDK project from hosted architecture v1 to v2: upgrade the
5
- package, remove v1-only code, and redeploy. Applies only to projects
6
- built during the early alpha, which depend on `@cursor/july`, run the
7
- legacy CLI, or set architecture "v1".
8
- alwaysApply: false
9
- ---
10
-
11
- # Migrate an Agent SDK agent to architecture v2
12
-
13
- This skill applies only to projects built during the Agent SDK early alpha,
14
- when hosted agents ran on architecture v1. Projects that never deployed
15
- on v1 already run on v2 and need nothing here.
16
-
17
- ## Confirm the project needs it
18
-
19
- Migrate when any of these is true:
20
-
21
- - `package.json` depends on `@cursor/july`.
22
- - `agent/agent.ts` sets `architecture: "v1"`.
23
- - `agent-sdk deployment get <slug>` for the hosted copy does not print
24
- `architecture: v2`.
25
-
26
- Stop when none is true. Your final message must start with
27
- `Nothing to migrate.` and must name the checks you ran. Open no pull
28
- request.
29
-
30
- `agent-sdk migrate` checks `--dir` before it starts an agent. It starts an
31
- agent when it finds any of these: an `@cursor/july` dependency or
32
- import, `architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
33
- `runtime: "grokbot"`, a literal or `() => process.env` SCM credential,
34
- `continuation: ".../v1"`, an anonymous reminder `run` or function
35
- `until`, or a `defineConnection` whose URL comes from a `*_MCP_URL`
36
- secret. When none of those is present it prints `Nothing to migrate.`
37
- and exits. When it cannot read a file, it starts the agent. It does
38
- not run `agent-sdk deployment`. A hosted copy can still be on v1 after the
39
- source has moved. Check with `agent-sdk deployment get <slug>`, and deploy when
40
- that output does not show `architecture: v2`.
41
-
42
- ## Know what changes
43
-
44
- A v1 deployment kept one long-lived process per agent. On v2 the platform
45
- starts a short-lived runtime when an event arrives, keeps sessions, KV,
46
- and files in Cursor-managed storage, and stops the runtime when the work
47
- ends. That model changes code in three places:
48
-
49
- - Module-scope state and files written outside `ctx.host.files` vanish
50
- between events. Keep durable state in `ctx.host.kv` or `ctx.host.files`.
51
- - Secrets arrive per request, after modules load. Read `process.env`
52
- inside the handler, tool, or callback that needs the value.
53
- - SCM webhook channels name their secrets instead of reading them.
54
- `githubChannel({ credentials })` fields and the `gitlabChannel` /
55
- `bitbucketChannel` `webhookSecret` take `{ secretName: "NAME" }`, so
56
- the platform can verify the provider signature at ingestion and flag
57
- an unset deployment secret before the first API call. A literal or a
58
- `() => process.env.X` getter is a validation error on v2.
59
- - The deployment URL serves only routes your channels declare. It
60
- answers `202` at once and runs the handler afterwards, so a route
61
- cannot send a response body back to its caller.
62
-
63
- ## Check what v2 supports
64
-
65
- | Capability | On v2 |
66
- | --- | --- |
67
- | Slack mentions, DMs, and channel posts | Supported. Provision a new Slack app after the first v2 deploy. |
68
- | GitHub channels, including `cursorAccount` | Supported. Every `credentials` field must be `{ secretName }`. |
69
- | GitLab and Bitbucket channels on Cursor hosting | Rolling out. Trial under a new slug first. `webhookSecret` must be `{ secretName }`. |
70
- | Custom HTTP channel routes | Supported. The caller gets `202`, not the handler's response. |
71
- | Tools, skills, subagents, MCP connections | Supported |
72
- | `ctx.host.kv`, `ctx.host.files`, artifacts | Supported, in platform-selected storage |
73
- | Reminders with `prompt` or a named `handler` | Supported |
74
- | Secrets and `hosting.egressDomains` | Supported. Same-slug deploys copy v1 secrets. |
75
- | `persistent: true` and `hosting.image` | Supported, one persistent deployment per team |
76
- | Local `agent-sdk dev`, `run`, `eval`, and the playground | Supported |
77
- | `defineStorage` in `agent/storage.ts` | Not supported. Delete the file. |
78
- | Reminders with inline `run` or a function `until` | Not supported. Use a named handler. |
79
- | Cron schedules in `agent/schedules/` on Cursor hosting | Supported with `@grok/agent-sdk` 0.2.14 or newer. Each fire runs in a new runtime and must finish in 26 minutes. |
80
- | Slack tool-approval buttons on Cursor hosting | Not supported yet |
81
- | `agent-sdk mcp oauth --store` for host MCP OAuth | Not supported. Connect Cursor-account MCP servers from **Deployed Agents** in the dashboard. |
82
- | Session, tool, and MCP APIs on the deployment URL | Not reachable |
83
- | Another Agent SDK agent reached through a deployment URL secret | Not supported. Declare `defineConnection({ agent: "<slug>" })`. Both agents must be team-owned and deployed on `@grok/agent-sdk` 0.2.18 or newer. |
84
- | `--prod` with `chat`, `tool call`, `skill`, `session get --view cost`, or `mcp` | Not supported. Use `session create`, `logs --prod`, `session list --prod`, `session get --prod`, and `session get --prod --web`. |
85
- | v1 sessions, KV, and files | Not carried over. v2 starts empty, and deleting v1 deletes them. |
86
-
87
- The steps below rewrite `defineStorage`, inline reminders, SCM channel
88
- credentials, secret reads, and peer calls that use a URL secret. Stop and
89
- ask before migrating an agent that depends on Slack tool-approval buttons,
90
- `mcp oauth --store`, or an
91
- HTTP route whose caller reads the response body. Name the row and the
92
- file that uses it.
93
-
94
- ## Update the project
95
-
96
- Keep the diff to the migration. Leave an `agent/` root in place; it
97
- still loads.
98
-
99
- 1. **Upgrade the package.** Remove the legacy v1 package from
100
- `package.json` and install the package this checkout publishes:
101
-
102
- ```bash
103
- npm uninstall @cursor/july
104
- npm install @grok/agent-sdk@latest
105
- ```
106
-
107
- Commit the lockfile the install writes, since deploys build from Git.
108
- Rewrite every `@cursor/july` import to `@grok/agent-sdk`; subpaths such as
109
- `/channels/slack`, `/evals`, and `/reminders` keep their names. Replace
110
- the legacy CLI command with `bdk` in scripts, CI jobs, and READMEs.
111
-
112
- The new types are stricter. `ctx.session.continuationKey` is
113
- `string | null`, so guard with `typeof key === "string"`, not
114
- `!== undefined`. Typecheck with `npx tsc --noEmit` even when the
115
- project has no script for it.
116
-
117
- 2. **Drop the v1 opt-in.** Delete `architecture: "v1"` from
118
- `defineAgent`. v2 is the default, so do not add `architecture: "v2"`.
119
-
120
- 3. **Delete `agent/storage.ts`.** v2 selects storage itself, and
121
- `ctx.host.kv` calls keep working against it. Data in a backend you
122
- run stays there. Data in Cursor-hosted storage is deleted with the v1
123
- deployment, so export what the agent still needs before deploying.
124
-
125
- 4. **Name inline reminders.** Move each inline `run` into
126
- `agent/reminders/<name>.ts` and pass that module as `handler` with
127
- serializable `args`. A named handler takes no `until`. Move a function
128
- `until` check into the handler and call `cancel()` when it holds.
129
-
130
- ```ts
131
- // agent/reminders/ci_recheck.ts
132
- import { defineReminder } from "@grok/agent-sdk/reminders";
133
-
134
- export default defineReminder({
135
- async run({ args, followup }) {
136
- await followup({ message: `Recheck CI on ${String(args.headSha)}` });
137
- return { action: "delivered" };
138
- },
139
- });
140
- ```
141
-
142
- ```ts
143
- // agent/tools/watch_ci.ts, inside execute
144
- await ctx.host.reminders?.create({
145
- purpose: "ci_recheck",
146
- channelId: ctx.session.channelId,
147
- continuationToken: key,
148
- delay: "2h",
149
- handler: ciRecheck, // import ciRecheck from "../reminders/ci_recheck.js"
150
- args: { headSha },
151
- });
152
- ```
153
-
154
- 5. **Rewrite `/v1` continuation selectors.** Delete an explicit
155
- `continuation: "<kind>.<scope>/v1"` on a channel so v2 picks its
156
- default, or change the suffix to `/v2`. By default, GitHub PR events,
157
- Slack threads, and deployment events still continue one session per
158
- PR, thread, or deployment.
159
-
160
- 6. **Name SCM channel credentials.** Replace every literal and
161
- `() => process.env.NAME` getter in `githubChannel({ credentials })`
162
- with `{ secretName: "NAME" }`, and do the same for the `webhookSecret`
163
- of `gitlabChannel` and `bitbucketChannel`. Keep the name the getter
164
- read; the channel reads that environment variable locally and the
165
- deployment secret of that name on Cursor hosting. A field you omit
166
- keeps its default name (`GITHUB_WEBHOOK_SECRET`, `GITHUB_TOKEN`,
167
- `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`), a numeric `appId` stays a
168
- number, and `cursorAccount` needs no credentials.
169
-
170
- ```ts
171
- // before (v1)
172
- credentials: {
173
- webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
174
- appId: () => process.env.GITHUB_APP_ID,
175
- privateKey: () => process.env.GITHUB_APP_PRIVATE_KEY,
176
- },
177
-
178
- // after (v2)
179
- credentials: {
180
- webhookSecret: { secretName: "GITHUB_WEBHOOK_SECRET" },
181
- appId: { secretName: "GITHUB_APP_ID" },
182
- privateKey: { secretName: "GITHUB_APP_PRIVATE_KEY" },
183
- },
184
- ```
185
-
186
- `agent-sdk validate` lists each field still in the old shape. While
187
- `architecture: "v1"` is set the finding is a warning, so you can run
188
- it before step 2 to see the full list; after step 2 the same finding
189
- is an error and blocks `deploy`. Do not set the values: a same-slug
190
- deploy copies the v1 secrets, and a new slug takes
191
- `agent-sdk secret set <new-slug> NAME` after the deploy.
192
-
193
- 7. **Move secret reads.** Replace module-scope `process.env.NAME` reads
194
- with reads inside the function that uses them. Give MCP connections a
195
- `${NAME}` header or env template instead. A URL that points at another
196
- Agent SDK agent's deployment is not one of those secrets. Step 8 replaces
197
- that connection, including a URL you templated here.
198
-
199
- 8. **Rewrite peer calls that use a URL secret.** Do this in the migration
200
- pull request. The deployment URL does not serve MCP, so a connection
201
- left on that URL fails after deploy.
202
-
203
- Treat the call as a peer when its URL comes from a `*_MCP_URL` secret
204
- or a similar name, a `${NAME}` template, `process.env.NAME`, or a
205
- string built from a deployment URL or slug, and the target is another
206
- Agent SDK agent. Leave a third-party MCP server as a URL connection and
207
- apply step 7 to its secrets.
208
-
209
- Use a slug only when the repo states it: the URL path, a `--slug`
210
- value, a sibling directory that deploy would use as the slug, or a
211
- comment that names the deployment. A secret name is a hint. Use
212
- `BUILDER_MCP_URL` as `builder` only when something else in the repo
213
- confirms that slug. When nothing confirms it, keep the URL connection
214
- and add a TODO that names the secret and asks for the slug. Name that
215
- TODO in the pull request body.
216
-
217
- ```ts
218
- // before (v1), agent/mcp-connections/builder.ts
219
- import { defineConnection } from "@grok/agent-sdk/connections";
220
-
221
- export default defineConnection({
222
- url: process.env.BUILDER_MCP_URL,
223
- headers: { authorization: `Bearer ${process.env.BUILDER_TOKEN}` },
224
- });
225
-
226
- // after (v2)
227
- import { defineConnection } from "@grok/agent-sdk/connections";
228
-
229
- export default defineConnection({
230
- agent: "builder",
231
- description: "Ask the builder agent to handle this work.",
232
- });
233
- ```
234
-
235
- `agent` is the peer's lowercase deployment slug. Keep an existing
236
- connection file in place. When the project has no connection file,
237
- add `bot/mcp-connections/<name>.ts`, or
238
- `agent/mcp-connections/<name>.ts` when the project root is `agent/`.
239
- Use `host-connections/` only when host code calls the peer and the
240
- model must not see it. The filename is the connection name.
241
-
242
- Hosting authenticates the peer call. Remove the URL, its headers, and
243
- any token this call was the only reader of. Point host code that
244
- called the deployment URL at
245
- `ctx.host.mcp.callTool("<name>", "ask", { message })`. The peer
246
- project needs no matching file. Do not edit a peer that sits outside
247
- this folder.
248
-
249
- Remove the unused URL secret from code and from `hosting.secretNames`
250
- on `defineAgent`, and from an extension `hosting` block that declares
251
- it. Leave every secret something else still reads.
252
-
253
- Do not change deployment secrets, and do not run `agent-sdk secret delete`.
254
- In the pull request body, list each secret this step stopped using,
255
- with the command `agent-sdk secret delete <slug> NAME`, so the user can
256
- unset it after both agents are deployed.
257
-
258
- Both agents must be team-owned and deployed with `@grok/agent-sdk` 0.2.18
259
- or newer before the connection resolves. This pull request does not
260
- deploy them.
261
-
262
- 9. **Stop answering from HTTP routes.** A custom route that returned
263
- computed data must deliver it another way, such as a callback URL or a
264
- tool the turn calls. Return `new Response(null, { status: 202 })` so
265
- local runs match the hosted response.
266
-
267
- ## Verify locally
268
-
269
- Run the project's installed CLI. Prefix each command with `npx` when
270
- `agent-sdk` is not on `PATH`.
271
-
272
- ```bash
273
- agent-sdk validate --dir .
274
- agent-sdk info --dir . --json
275
- agent-sdk run --dir . --message "<a representative request>"
276
- agent-sdk eval --dir .
277
- ```
278
-
279
- Fix every validation error, but never change `runtime` to pass
280
- validation; stop and report instead. An error ending in `requires a
281
- named secret` names a channel credential step 6 missed; it quotes the
282
- `{ secretName }` value to use. `run` and `eval` need a Cursor
283
- credential. When none is set, skip them and say so in the pull request.
284
- Run the project's own typecheck and tests.
285
-
286
- ## Open the pull request
287
-
288
- Describe each removed or changed behavior, each unsupported row the
289
- agent touched, and the deploy steps. For each peer URL you rewrote, name
290
- the slug and the connection file. List every secret name the rewrite
291
- left unused, and the `agent-sdk secret delete <slug> NAME` command for it.
292
- Name each TODO whose slug you could not determine. Do not deploy from
293
- the pull request branch, and do not change deployment secrets.
294
-
295
- Copy this post-merge checklist into the pull request body. One
296
- `agent-sdk deploy --dir <agent-folder>` per agent. Do not use `agent-sdk deploy --all`.
297
- Then `agent-sdk slack create --env prod --dir <agent-folder> [--team <team-id>]`
298
- for each agent that uses Slack. Then `agent-sdk secret delete <slug> NAME` for
299
- each unused peer URL secret, and `agent-sdk secret list <slug>` plus
300
- `agent-sdk secret set <slug> NAME` when the slug is new. Do not tell the user
301
- to deploy again after Slack setup or after `agent-sdk secret set`. The server
302
- redeploys after Slack setup, and a secret is injected on the next
303
- request.
304
-
305
- ## Deploy after merge
306
-
307
- Deploy from a pushed ref. `agent-sdk deploy` reads Git and never uploads the
308
- working tree.
309
-
310
- When the folder contains one agent:
311
-
312
- ```bash
313
- agent-sdk login
314
- agent-sdk validate --dir .
315
- agent-sdk deploy --dir . --slug <existing-slug> \
316
- --cursor-events-repo <owner/repo>
317
- ```
318
-
319
- When the folder contains more than one agent, deploy each agent alone.
320
- Run the command one time for each agent folder. A `agent-sdk deploy` on the
321
- parent folder prints those commands and does not deploy. Do not run
322
- `agent-sdk deploy --all`. Repeat `agent-sdk slack create --env prod` for each agent
323
- folder too.
324
- The app slug is the folder name, so that name must match the deployed
325
- slug.
326
-
327
- ```bash
328
- agent-sdk deploy --dir <agent-folder> --slug <that-agent-slug> \
329
- --cursor-events-repo <owner/repo>
330
- ```
331
-
332
- When this migration declares `defineConnection({ agent: "<slug>" })`,
333
- deploy the caller and the peer. Both deployments must be team-owned and
334
- must run `@grok/agent-sdk` 0.2.18 or newer. The connection file is already
335
- in the merged source. The caller reaches the peer after the peer
336
- deployment is running. The peer needs no matching file. After both
337
- deploys are running, unset each URL secret the pull request lists:
338
-
339
- ```bash
340
- agent-sdk secret delete <slug> NAME
341
- ```
342
-
343
- Pass every `--cursor-events-repo` value the v1 deployment used. `agent-sdk deploy`
344
- has no `--allow-domain` flag. Add every egress domain that the v1
345
- deployment allowed to `hosting.egressDomains` in the agent config, and
346
- merge that change before you deploy. Print only those two fields,
347
- because the full output holds credentials:
348
-
349
- ```bash
350
- agent-sdk deployment get <slug> --json --fields cursorEventRepos,egressAllowedDomains
351
- ```
352
-
353
- Choose a cutover before you deploy:
354
-
355
- - **Same slug.** One command, and it can't be undone. The deploy copies
356
- the v1 secrets, switches traffic once v2 is running, then deletes the
357
- v1 deployment along with its Cursor-hosted sessions, KV, files, and
358
- eval runs. Slack and webhook traffic stops until you finish the steps
359
- below. If the command reports that same-slug replacement is
360
- unavailable, use a new slug.
361
- - **New slug.** v1 keeps serving while you test. Set secrets with
362
- `agent-sdk secret set <new-slug> NAME`. Both deployments act on events from
363
- the same repositories, so point the trial at a test repository with
364
- `--cursor-events-repo`. Then move senders over and run
365
- `agent-sdk deployment delete <old-slug>`, which deletes v1's hosted data the same way.
366
-
367
- Prefer a new slug when the agent serves Slack, receives webhooks, or
368
- keeps data in `ctx.host.kv`.
369
-
370
- After the deploy is running:
371
-
372
- - Store the alias token the deploy prints. Point every webhook sender
373
- and HTTP caller at the new alias URL.
374
- - For Slack, log in as a person. A team service-account key cannot
375
- create the app. Run `agent-sdk slack create --env prod --dir <agent-folder>`
376
- once per agent (`--team <team-id>` selects the Cursor team that owns
377
- the deployment). The server redeploys by itself. Do not deploy again
378
- for Slack. The new app is a different bot. Uninstall the old Slack app
379
- and invite the new bot to the channels the old one joined. The copied
380
- v1 Slack secrets go unused.
381
- - For secrets, a same-slug deploy copies the v1 secrets. A new slug
382
- needs `agent-sdk secret set <slug> NAME`. Check with
383
- `agent-sdk secret list <slug> [--team <team-id>]`. `deploy` warns when a
384
- declared secret is unset. A secret is injected on the next request.
385
- Do not deploy again after `agent-sdk secret set`.
386
- - Reconnect Cursor-account MCP servers from **Deployed Agents** in the
387
- dashboard.
388
- - Start a turn with `agent-sdk session create --slug <slug> --message "..." --wait`.
389
- It prints the `sessionId` once the delivery names it. Then read the turn
390
- with `agent-sdk session get <ses_...> --prod --slug <slug>` until the latest run
391
- finishes.
392
-
393
- The deploy skill (`skills/deploy/SKILL.md`) covers deploys with an attached
394
- service account.
@@ -1,136 +0,0 @@
1
- ---
2
- name: bdk-setup-slack
3
- description: >-
4
- Wire Slack to an Agent SDK agent. Mint a dedicated Socket Mode app
5
- with slack create, then doctor and smoke. Use slack init --manual
6
- only when the user owns the Slack app. Use when adding Slack.
7
- ---
8
-
9
- # Setup Slack for the Agent SDK
10
-
11
- Dedicated Socket Mode bot. `agent-sdk slack create` opens the
12
- signed-in dashboard wizard. Tokens land in `.env.local` and as
13
- deployment secrets. Never print token values.
14
-
15
- Do not generate manifests or ask anyone to paste tokens unless
16
- they asked for `slack init --manual`.
17
-
18
- Existing `<PREFIX>_SLACK_BOT_TOKEN` + `_SLACK_APP_TOKEN` in
19
- `.env.local` keep working. Do not force those onto the wizard.
20
-
21
- Guide: `docs/guides/slack.md`.
22
-
23
- ## 1. Wizard (default)
24
-
25
- ```bash
26
- agent-sdk login
27
- agent-sdk slack create --dir .
28
- ```
29
-
30
- Same Cursor account in the browser. **Add Slack to this agent**,
31
- approve Slack, pick the bot name. CLI writes
32
- `<PREFIX>_SLACK_BOT_TOKEN` / `<PREFIX>_SLACK_APP_TOKEN` and runs
33
- `doctor`.
34
-
35
- Prefix is the directory basename in upper snake (`jenny` →
36
- `JENNY`, `pr-approver` → `PR_APPROVER` → `PR_APPROVER_SLACK_*`).
37
- `--prefix` / `--no-prefix` override. Dev and prod are separate
38
- apps; `--prod` is the prod app. `--name` / `--icon` /
39
- `--channel-posts` / `--slack-team` prefill the wizard.
40
-
41
- If Slack needs workspace-admin approval, keep the CLI running.
42
- Open the **Request approval** link it prints. Managed install
43
- does not file the request. After approval, **Retry** in the
44
- wizard.
45
-
46
- `create` scaffolds `bot/channels/slack.ts` when missing:
47
-
48
- ```ts
49
- export default slackChannel({
50
- envPrefix: "JENNY",
51
- suggestedPrompts: [{ title: "Help", message: "How can you help me?" }],
52
- });
53
- ```
54
-
55
- Return from dispatch handlers. Do not await long work in the
56
- handler.
57
-
58
- A second `slack create` for the same agent and env overwrites the
59
- app (same Slack app id, new manifest and tokens).
60
- `agent-sdk slack destroy` deletes it.
61
-
62
- Local serve does not need a hosted engine. Next
63
- `agent-sdk deploy` injects the stored secrets.
64
-
65
- ## 2. Manual (`slack init --manual`)
66
-
67
- Only when they own the app. Preferred: Slack CLI
68
- (`~/.slack/bin/slack`). Paste at api.slack.com if the CLI is
69
- missing. Never `slack deploy`; Agent SDK serve owns Socket Mode.
70
-
71
- ```bash
72
- agent-sdk slack init --manual --dir . --name "My Agent"
73
- # --slack-team T0123ABCD when several workspaces are logged in
74
- # --no-install to scaffold only
75
- ```
76
-
77
- Writes `bot/channels/slack.ts` (`envPrefix` from the directory),
78
- manifests, a `.slack/` project (`get-manifest` → those JSON files),
79
- and `env.example`. `--channel-posts` subscribes `message.channels`
80
- / `message.groups`. If Slack CLI is logged in, this installs the
81
- app. `--install` fails when that cannot run.
82
-
83
- Human gates, one at a time. Stop after each.
84
-
85
- 1. **Install the app.** If `next` starts with "Ask the user to
86
- install this Slack app", stop and prompt them. Slack CLI: they
87
- run `slack login --no-prompt`, send `/slackauthticket <ticket>`,
88
- then `slack login --ticket <ticket> --challenge <code>`, then
89
- `slack app install --environment local --team <T> --force`.
90
- Prod: `SLACK_ENV=deployed slack app install --environment
91
- deployed --team <T> --force`. Fallback: Create New App → From a
92
- manifest, start with `.slack/manifest.dev.json`.
93
- 2. **Tokens.** Slack CLI leaves xoxb / xapp in that process only.
94
- Copy the bot token from the app's OAuth page. Mint an app-level
95
- token with `connections:write`. Put both in `.env.local` using
96
- `env.example` names. If Slack CLI wrote `SLACK_*` to `.env`,
97
- copy those values to the prefixed keys.
98
- 3. **Doctor.**
99
-
100
- ## 3. Doctor and smoke
101
-
102
- ```bash
103
- agent-sdk slack doctor --prefix JENNY
104
- agent-sdk serve --dir . --dev
105
- ```
106
-
107
- Green: `app_token`, `connections_open`, `bot_token`, `auth_test`.
108
- Log: `[bdk/slack] Socket Mode connected`. Missing tokens
109
- idle the channel; `serve` continues.
110
-
111
- 1. Invite the bot
112
- 2. `@mention` or DM
113
- 3. Thinking / Working, then a threaded reply
114
- 4. Logs: `inbound kind=app_mention`, `session start`,
115
- `reply delivered via postMessage|stream`
116
-
117
- ## Watch channels (opt-in)
118
-
119
- Default is mentions + DMs only. To wake on new posts:
120
-
121
- ```ts
122
- export default slackChannel({
123
- envPrefix: "JENNY",
124
- engagement: {
125
- channelPosts: {
126
- allow: ["C0123ABCDEF", "#alerts"], // ≥1 channel id required, ≤10 ids
127
- posts: "top-level",
128
- },
129
- },
130
- onChannelPost: async (ctx, message) => ({}), // null = skip
131
- });
132
- ```
133
-
134
- Pass `--channel-posts` on `create` / `init --manual`. Invite the
135
- bot to each watched channel. Mentions stay on `app_mention`; a
136
- later mention continues the watch thread.