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