@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,17 +5,7 @@ description: "Define custom channel routes, schemas, state, events, and authenti
5
5
 
6
6
  # Channels
7
7
 
8
- A channel connects an external surface to agent sessions. A file at
9
- `bot/channels/<id>.ts` defines channel `<id>` and mounts its routes
10
- under `/v1/channels/<id>`. The built-in HTTP session channel is always
11
- available alongside any custom or prebuilt channels.
12
-
13
- ## Built-in HTTP channel
14
-
15
- The built-in channel serves the session, tool, and discovery routes. In
16
- a multi-agent host, each agent's routes sit under its
17
- slug. See the [HTTP API](./http-api.md) for request and response
18
- contracts.
8
+ A channel connects an external surface to agent sessions. A file at `bot/channels/<id>.ts` defines channel `<id>` and mounts its routes under `/v1/channels/<id>`, and the built-in HTTP channel serves the [HTTP API](./http-api.md) routes and is always available.
19
9
 
20
10
  ## Define a custom channel
21
11
 
@@ -30,12 +20,11 @@ export default defineChannel({
30
20
  POST("/review", {
31
21
  description: "Review a pull request on this channel",
32
22
  bodySchema: z.object({
33
- message: z.string(),
34
23
  prUrl: z.string().url(),
35
24
  }),
36
25
  handler: async (_request, { send, waitUntil, body }) => {
37
26
  waitUntil(
38
- send(`${body.message}\n\nPull request: ${body.prUrl}`, {
27
+ send(`Review ${body.prUrl}`, {
39
28
  continuationToken: `pr:${body.prUrl}`,
40
29
  })
41
30
  );
@@ -46,194 +35,156 @@ export default defineChannel({
46
35
  });
47
36
  ```
48
37
 
49
- The route above is
50
- `POST /v1/channels/<id>/review`. Calls for the same pull request reuse
51
- one conversation because they pass the same continuation token.
38
+ This route is `POST /v1/channels/<id>/review`. Calls for the same pull request
39
+ pass the same [continuation token](./sessions.md#session-identifiers), so they
40
+ share one conversation.
52
41
 
53
42
  ## Route responses
54
43
 
55
- A custom route acknowledges the caller and nothing more. On
56
- Cursor-managed hosting, the deployment answers every custom route with
57
- `202 Accepted` and an empty body as soon as the request arrives, then
58
- runs the handler. The caller never receives the handler's `Response`,
59
- so a route can't return a session ID, a computed result, or an error
60
- status. Requests rejected before the handler runs, such as a missing
61
- alias token or a failed `sharedSecretAuth` or `hmacSignatureAuth`
62
- check, still get `401`. A request with a bad `X-BDK-Session-Key` header
63
- gets `400`. See [Hosted session keys](#hosted-session-keys).
64
-
65
- Deliver results through the channel's [`events`](#events) handlers, a
66
- callback to the system that sent the request, or a tool the turn calls.
67
- Local `serve` passes the handler's response through, so return
68
- `new Response(null, { status: 202 })` to keep local calls matching
69
- hosted ones.
44
+ On Cursor hosting, the deployment
45
+ answers every custom route with an empty `202 Accepted` as soon as the request
46
+ arrives, then runs the handler. The caller never sees the handler's `Response`,
47
+ so a route can't return a session ID, a result, or an error status. A request
48
+ that fails the alias token, `sharedSecretAuth`, or `hmacSignatureAuth` check
49
+ still gets `401`.
50
+
51
+ Deliver results through [`events`](#events) handlers, a callback to the sender,
52
+ or a tool the turn calls. Local `serve` returns the handler's response, so
53
+ return `new Response(null, { status: 202 })` to match hosting.
70
54
 
71
55
  ## Route verbs and schemas
72
56
 
73
- Route paths must begin with `/`. The method helper determines which Zod
74
- schemas the route accepts:
57
+ Route paths must begin with `/`.
75
58
 
76
- | Helper | Schema contract |
77
- | --- | --- |
78
- | `GET` | `querySchema` is required |
79
- | `POST`, `PUT`, `PATCH` | `bodySchema` is required; `querySchema` is optional |
80
- | `DELETE` | Both schemas are optional |
59
+ `GET` requires a `querySchema`.
60
+
61
+ `POST`, `PUT`, and `PATCH` require a `bodySchema`. They also accept a `querySchema`.
81
62
 
82
- Plain JSON Schema objects don't type-check. Use `z.object({})` or
83
- `z.unknown()` for an open surface. The host validates the body and query
84
- before calling the handler, and an empty body is read as `{}`. A request
85
- that fails validation never reaches the handler; local `serve` answers it
86
- with `400`, while a hosted caller has already received its `202`. Declared schemas also appear in `GET /v1/info` for
87
- playground requests and slash commands.
63
+ `DELETE` takes a `bodySchema`, a `querySchema`, either, or neither.
64
+
65
+ Plain JSON Schema objects don't type-check, so use `z.object({})` or
66
+ `z.unknown()` for an open surface. The host validates input before the handler
67
+ runs, and declared schemas appear in `GET /v1/info` for the playground and
68
+ slash commands.
88
69
 
89
70
  ## Handler arguments
90
71
 
91
- Each handler receives the Fetch `Request` and a typed arguments object.
72
+ A handler receives the Fetch `Request` and these arguments:
92
73
 
93
74
  | Member | Contract |
94
75
  | --- | --- |
95
76
  | `send(message, options?)` | Start or resume a session on this channel |
96
- | `getSession(sessionId)` | Return this channel's session, or `null` |
77
+ | `getSession(sessionId)` | This channel's session, or `null` |
97
78
  | `receive(channel, input)` | Hand work to another channel |
98
79
  | `callTool(name, input, options?)` | [Call a server tool](./tools.md#call-a-tool-without-a-model-turn) without a model turn |
99
80
  | `body`, `query`, `params` | Validated inputs and `:param` path segments |
100
- | `auth` | The `AuthContext` returned by the route's auth chain |
81
+ | `auth` | The `AuthContext` from the route's auth chain |
101
82
  | `requestIp` | The TCP peer address, or `null` |
102
- | `host` | Shared MCP, provider, storage, telemetry, and reminder services |
83
+ | `host` | Host services such as MCP, storage, telemetry, and reminders |
103
84
  | `waitUntil(promise)` | Keep work running after the handler returns |
104
- | `sessionUrls(request, sessionId)` | Build absolute playground and trace URLs for this mount |
105
- | `artifacts` | List or tag [artifacts](./artifacts.md); pass `sessionId` when attributing one |
85
+ | `sessionUrls(request, sessionId)` | Playground and trace URLs for a session |
86
+ | `artifacts` | List or tag [artifacts](./artifacts.md) |
106
87
 
107
88
  ### `send` options
108
89
 
109
90
  | Option | Contract |
110
91
  | --- | --- |
111
- | `continuationToken` | Resume the session with this channel-local key, or create one when the key is new |
112
- | `admission` | `"preempt"` interrupts a busy turn; `"coalesce"` queues behind it. The default is `"preempt"` |
113
- | `workspaceFiles` | Add relative files for the next turn |
114
- | `workspaceDir` | Use an absolute local working directory |
115
- | `auth` | Set the session principal; defaults to the request principal |
116
- | `state` | Set starting channel state for a new session |
117
- | `title` | Set the display title for a new session |
118
- | `purpose` | Use `"eval"` to mark a new session as regression traffic |
119
- | `dryRun` | Run read tools and stub write tools for a new session |
120
- | `asOf` | Freeze a new session at an ISO-8601 instant with a timezone |
121
- | `deliveryId` | Name this send on the session's events, at most 256 characters. Defaults to a fresh `dlv_…` ID |
122
-
123
- `send` returns a `ChannelSession`. Its `id` identifies the session,
124
- `continuationToken` contains its current channel key, and `isNew` says
125
- whether this call created it. A coalesced call also returns
126
- `coalesced: true`. `deliveryId` names this send on the event where the
127
- message reaches the agent; see
128
- [Track which follow-up reached the agent](./sessions.md#track-which-follow-up-reached-the-agent).
129
- A hosted channel's `send` returns the same ID before the session exists.
92
+ | `continuationToken` | Channel-local key that resumes its session, or creates one when new |
93
+ | `admission` | `"preempt"` (the default) interrupts a busy turn. `"coalesce"` queues behind it |
94
+ | `workspaceFiles` | Relative files to add before the next turn |
95
+ | `workspaceDir` | Absolute local working directory |
96
+ | `auth` | Session principal. Defaults to the request principal |
97
+ | `state` | Starting channel state for a new session |
98
+ | `title`, `purpose`, `dryRun`, `asOf` | Set up a new session, as in the [`POST /v1/session` body](./http-api.md#start-a-session) |
99
+ | `deliveryId` | Names this send on the session's [events](./sessions.md#track-which-follow-up-reached-the-agent), up to 256 characters. Defaults to a fresh `dlv_…` ID |
100
+
101
+ `send` returns a `ChannelSession` with `id`, the current `continuationToken`,
102
+ `isNew`, and `coalesced: true` for a coalesced call. On Cursor hosting, it
103
+ returns the ID before the session exists.
130
104
 
131
105
  ## Events
132
106
 
133
- The `events` map subscribes the channel to stream events for the
134
- sessions it owns. Keys are event types from the
135
- [event vocabulary](./sessions.md#stream-events), or `"*"`. Each handler
136
- receives `(event, channel, ctx)`, including the session's
137
- `channel.state`, session info, and shared host services. Use these
138
- handlers to deliver progress and replies to the surface that owns the
139
- channel.
140
-
141
- ## Session state
142
-
143
- `state` on the channel definition supplies starting JSON for each new
144
- session. A route can instead pass `state` to `send`; event handlers read
145
- and update the active value through `channel.state`.
107
+ The `events` map subscribes the channel to stream events for its sessions. Keys
108
+ are types from the [event vocabulary](./sessions.md#stream-events), or `"*"`.
109
+ Each handler receives `(event, channel, ctx)` with `channel.state`, session
110
+ info, and host services, so it can post progress and replies. `state` on the
111
+ channel definition is each new session's starting JSON, unless a route passes
112
+ `state` to `send`, and handlers update it through `channel.state`.
146
113
 
147
114
  ## Start and stop a channel
148
115
 
149
- `onStart(args)` runs when the channel mounts, and `onStop()` runs when
150
- the host stops. `onStart` receives the route helpers plus these
151
- transport controls:
152
-
153
- | Helper | Contract |
154
- | --- | --- |
155
- | `emitAssistantMessage(sessionId, text)` | Append final assistant text without starting a model turn |
156
- | `hasContinuationSession(token)` | Check whether a token maps to a session |
157
- | `isContinuationBusy(token)` | Check whether a turn is active for a token |
158
- | `interruptContinuation(token)` | Stop the active turn and clear queued coalesced follow-ups |
116
+ `onStart(args)` runs when the channel mounts, and `onStop()` runs when the host
117
+ stops. Besides the route helpers, `onStart` receives
118
+ `emitAssistantMessage(sessionId, text)`, which appends assistant text without a
119
+ model turn, and `hasContinuationSession`, `isContinuationBusy`, and
120
+ `interruptContinuation`, which check or stop the session behind a token.
159
121
 
160
122
  ## Auth policies
161
123
 
162
- Every route runs the channel's `auth` array. The default is
163
- `[localDevStrict()]`. Policies may be asynchronous; the first one to
164
- return an `AuthContext` admits the request, and an all-null result
165
- returns `401`.
124
+ Every route runs the channel's `auth` array, which defaults to `[localDevStrict()]`. The first policy to return an `AuthContext` admits the request, and if every policy returns `null`, the route answers `401`.
166
125
 
167
126
  | Policy | Admits |
168
127
  | --- | --- |
169
- | `localDevStrict()` | Direct loopback requests with a loopback hostname and no proxy-forwarding headers |
170
- | `localDev()` | Direct loopback requests with no proxy-forwarding headers, without checking the hostname |
171
- | `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
172
- | `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
173
- | `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
174
- | `hmacSignatureAuth({ header, secret, prefix?, separator? })` | A hex HMAC-SHA256 signature over the raw body using the named secret. With `separator`, any of several signatures in the header. A secret holding one value per line verifies under any of them (at most 32, `@grok/agent-sdk` 0.2.25 or later) |
175
- | `allowAll()` | Every caller as an anonymous principal |
176
- | `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
177
-
178
- Use `allowAll()` only for an intentionally public surface or one
179
- protected upstream. With `publicEndpoint()`, the handler must verify the
180
- provider's signature. The policy applies only to custom channel routes;
181
- it doesn't open the built-in session or tool API.
182
-
183
- The resolved `AuthContext` (`{ authenticator, principalId,
184
- principalType, attributes? }`) becomes the request principal. Sessions
185
- belong to the principal that created them, and other principals receive
186
- `403` on owned routes.
187
-
188
- Server flags interact with authored auth: `--bearer-token` swaps the
189
- default `localDevStrict()` for `bearerAuth(...)` on channels that don't
190
- author their own chain, and `--allow-anonymous` swaps it for
191
- `allowAll()`. An authored `auth` array always takes precedence.
128
+ | `localDevStrict()` | Direct loopback requests with a loopback hostname and no forwarding headers |
129
+ | `localDev()` | The same, with any hostname |
130
+ | `loopbackOnly()` | Any loopback peer, including relays that add forwarding headers |
131
+ | `bearerAuth(tokenOrVerify)` | A matching bearer token, or one the verifier accepts |
132
+ | `sharedSecretAuth({ header, secret })` | A header that matches the named secret |
133
+ | `hmacSignatureAuth({ header, secret, prefix?, separator? })` | A hex HMAC-SHA256 signature of the raw body under the named secret, or any of several signatures split by `separator`. The secret can hold up to 32 values, one per line, and any of them verifies |
134
+ | `allowAll()` | Every caller, as an anonymous principal |
135
+ | `publicEndpoint()` | Every caller, with no alias token on hosting. The handler must verify the provider's signature |
136
+
137
+ Use `allowAll()` only for a public surface or one protected upstream. `publicEndpoint()` applies only to custom channel routes and doesn't
138
+ open the built-in session or tool API.
139
+
140
+ The admitted `AuthContext` becomes the request principal, which
141
+ [owns the sessions it creates](./sessions.md#session-contents).
142
+
143
+ On a channel without its own `auth`, `--bearer-token` swaps the default for
144
+ `bearerAuth(...)` and `--allow-anonymous` swaps it for `allowAll()`.
192
145
 
193
146
  ## Prebuilt channels
194
147
 
195
- | Import | Function | Surface |
196
- | --- | --- | --- |
197
- | `@grok/agent-sdk/channels/slack` | `slackChannel()` | Slack messages, threads, and streaming replies. See [Slack](../guides/slack.md) |
198
- | `@grok/agent-sdk/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](../guides/github.md) |
199
- | `@grok/agent-sdk/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](../guides/gitlab.md) |
200
- | `@grok/agent-sdk/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](../guides/bitbucket.md) |
201
- | `@grok/agent-sdk/channels/pagerduty` | `pagerdutyChannel()` | PagerDuty v3 incident webhooks. Replies post as incident notes only with `deliverReplies: true`. See [PagerDuty](../guides/pagerduty.md) |
202
- | `@grok/agent-sdk/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
148
+ Import each one from `@grok/agent-sdk/channels/<name>`.
203
149
 
204
- For other platforms like Discord or Teams, use the authored
205
- `defineChannel` route form.
150
+ | Function | Details |
151
+ | --- | --- |
152
+ | `slackChannel()` | [Slack](../guides/slack.md) |
153
+ | `githubChannel()` | [GitHub](../guides/github.md) |
154
+ | `gitlabChannel()` | [GitLab](../guides/gitlab.md) |
155
+ | `bitbucketChannel()` | [Bitbucket](../guides/bitbucket.md) |
156
+ | `pagerdutyChannel()` | [PagerDuty](../guides/pagerduty.md) |
157
+ | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
206
158
 
207
- ## Continuation tokens
159
+ Use `defineChannel` for other platforms, such as Discord.
208
160
 
209
- Each channel defines its continuation-token format. The same token
210
- resumes the same conversation; the built-in HTTP channel rotates its
211
- opaque token after every accepted follow-up and returns `409` for a
212
- stale token. See [Session identifiers](./sessions.md#session-identifiers)
213
- for the full contract.
161
+ ## Handler results
214
162
 
215
- ### Hosted session keys
163
+ Hooks on the GitHub, GitLab, Bitbucket, and PagerDuty channels, such as
164
+ `onPullRequest` or `onIncident`, return one of three results:
216
165
 
217
- On Cursor-managed hosting, each request to a `defineChannel` route
218
- starts a new session unless the request carries `X-BDK-Session-Key`.
219
- Requests with the same header value on one channel go to one session,
220
- in arrival order. The handler's `continuationToken` does not change
221
- this choice, and local `serve` ignores the header.
166
+ | Return value | What happens |
167
+ | --- | --- |
168
+ | `{ auth }` | Runs the model turn with that auth. It can also set the turn's `message`, `title`, or `context` |
169
+ | `{ task }` | Runs your function on the host. That function can call `send` to start a model turn |
170
+ | `null` | Ignores the event |
171
+
172
+ ## Hosted session keys
173
+
174
+ On Cursor hosting, each request to a `defineChannel` route starts a new session
175
+ unless it carries `X-BDK-Session-Key`. Requests with the same value on one
176
+ channel share one session, in arrival order. The handler's
177
+ `continuationToken` doesn't change that choice, and local `serve` ignores the
178
+ header.
222
179
 
223
180
  | Rule | Contract |
224
181
  | --- | --- |
225
- | Auth | The alias token or `sharedSecretAuth()`. Routes that admit the request with `hmacSignatureAuth()` or `publicEndpoint()` answer `400` |
226
- | Value | 1 to 256 printable ASCII characters, with no space and no comma. Any other value gets `400` |
227
- | Scope | One channel on one deployment |
228
- | Channels | `defineChannel` routes only. Prebuilt channels ignore the header |
229
- | Handler | `request.headers` still contains the header |
230
- | Retries | Hosting does not deduplicate. A retried request runs a second turn |
231
-
232
- See [Keep one hosted session per thread](../guides/webhooks.md#keep-one-hosted-session-per-thread).
182
+ | Auth | The alias token or `sharedSecretAuth()`. Routes admitted by `hmacSignatureAuth()` or `publicEndpoint()` answer `400` |
183
+ | Value | 1 to 256 printable ASCII characters with no space or comma, or the request gets `400`. Hosting stores the value, so keep secrets and personal data out of it |
184
+ | Scope | One channel on one deployment. Prebuilt channels ignore the header |
185
+ | Retries | Hosting doesn't deduplicate. A retry runs a second turn |
233
186
 
234
187
  ## Related
235
188
 
236
189
  - [Webhooks](../guides/webhooks.md)
237
- - [HTTP API](./http-api.md)
238
190
  - [Sessions](./sessions.md)
239
- - [Hooks](./hooks.md)