@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
@@ -1,20 +1,13 @@
1
1
  # PagerDuty agents
2
2
 
3
- A PagerDuty agent wakes when an incident triggers, investigates it, and
4
- writes what it found back to the incident. `pagerdutyChannel()` receives
5
- PagerDuty's v3 webhooks, verifies them, and keeps every later event for
6
- the same incident in one session, so the agent sees an acknowledgement,
7
- a note, or a responder's reply in the context of the investigation it
8
- already started. Every setting has a default read from a well-known secret, so
9
- the channel needs no configuration beyond its hooks; see
10
- [Connect](#connect) for the variables.
3
+ A PagerDuty agent wakes when an incident triggers, investigates it, and writes what it found back to
4
+ the incident. `pagerdutyChannel()` verifies PagerDuty's v3 webhooks and sends every later event for
5
+ that incident to the session that started the investigation.
11
6
 
12
7
  ## Investigate a new incident
13
8
 
14
- When an incident triggers, the agent starts a turn with the incident's
15
- title, service, urgency, and link. It reads whatever the investigation
16
- needs, and with `deliverReplies: true` its reply is posted as a note on
17
- the incident, where the person on call already looks.
9
+ When an incident triggers, the agent starts a turn with the incident's title, service, urgency, and
10
+ link.
18
11
 
19
12
  ```ts
20
13
  // bot/channels/pagerduty.ts
@@ -36,23 +29,13 @@ export default pagerdutyChannel({
36
29
  });
37
30
  ```
38
31
 
39
- Reply notes are off unless you set `deliverReplies: true`, so the channel
40
- writes nothing to PagerDuty on its own. An agent that writes to PagerDuty
41
- through its own path, such as a service that audits each write, leaves it
42
- off and posts only what it chooses, from `events` or `ctx.pagerduty`.
32
+ With `deliverReplies: true`, the channel posts each reply as a note on the incident. It doesn't post
33
+ anything until it knows the agent's own PagerDuty user, because each note comes back as a webhook
34
+ event and would otherwise start another turn. Handlers you write in `events` replace the built-in
35
+ ones.
43
36
 
44
- With `deliverReplies: true`, the channel posts each completed reply as a
45
- note on the session's incident, and a short note if a turn fails, using
46
- the `PAGERDUTY_TOKEN` secret. The note goes to the incident in the
47
- verified event's state, so the model never chooses which incident it
48
- writes to. Eval runs and agents without a token post nothing. Nothing is
49
- posted until the channel knows the agent's own PagerDuty user (see
50
- [Ignore your own actions](#ignore-your-own-actions)), because each note
51
- comes back as a webhook event that only the echo skip keeps from starting
52
- another turn. Handlers you write in `events` replace the built-in ones.
53
-
54
- Hooks also get `ctx.pagerduty`, a REST client with the channel's
55
- credentials, for reads and writes of their own:
37
+ Hooks also get `ctx.pagerduty`, a REST client with the channel's credentials. Use the incident from
38
+ the event or channel state when you write, so the model can't choose the target.
56
39
 
57
40
  ```ts
58
41
  onIncident: async (ctx, event) => {
@@ -61,14 +44,13 @@ onIncident: async (ctx, event) => {
61
44
  },
62
45
  ```
63
46
 
64
- Hosted, the agent also declares PagerDuty's API host and the token:
47
+ On Cursor hosting, declare PagerDuty's API host and the token:
65
48
 
66
49
  ```ts
67
50
  // bot/agent.ts
68
51
  import { defineAgent } from "@grok/agent-sdk";
69
52
 
70
53
  export default defineAgent({
71
- architecture: "v2",
72
54
  hosting: {
73
55
  egressDomains: ["api.pagerduty.com"],
74
56
  secretNames: ["PAGERDUTY_TOKEN"],
@@ -78,11 +60,8 @@ export default defineAgent({
78
60
 
79
61
  ## Follow the incident in one session
80
62
 
81
- People act on an incident while the agent investigates: someone
82
- acknowledges it, adds a note, pulls in a responder, or resolves it.
83
- Return a dispatch for those events too, and each one arrives in the
84
- session that is already working on the incident, with the earlier
85
- findings in context.
63
+ People acknowledge, annotate, reassign, and resolve an incident while the agent investigates. Return
64
+ a dispatch for those events too, and each one reaches the session already working on the incident.
86
65
 
87
66
  ```ts
88
67
  onIncident: (ctx, event) => {
@@ -103,185 +82,94 @@ onNote: (ctx, note) => {
103
82
  },
104
83
  ```
105
84
 
106
- Add these to the same `pagerdutyChannel()` declaration as the
107
- investigation handler.
85
+ Add both to the same `pagerdutyChannel()` call. A re-trigger after a resolve is a new PagerDuty
86
+ incident, so it starts a new session. `ctx.incidentKey` carries the alert's dedup key, so the agent
87
+ can recall what it found the last time the same alert fired.
108
88
 
109
89
  ## Ignore your own actions
110
90
 
111
- PagerDuty sends the agent's own changes back as webhook events: the
112
- note it posted, or an acknowledgement or resolve made through its
113
- PagerDuty user. The channel acknowledges those events without running a
114
- hook or starting a turn. The same action by a person is still delivered.
115
-
116
- The channel finds the agent's user in this order, on each delivery:
117
-
118
- 1. The `selfUserIds` option, when you pass one. Nothing below is used.
119
- 2. The `PAGERDUTY_USER_ID` secret: one PagerDuty user id.
120
- 3. The user `PAGERDUTY_TOKEN` acts as, which PagerDuty reports at
121
- `GET /users/me`.
122
-
123
- When none of these names a user, echo skip is off. `agent-sdk deploy` warns
124
- while neither `PAGERDUTY_USER_ID` nor `PAGERDUTY_TOKEN` is set, and the
125
- agent logs a warning when its token names no single user.
126
-
127
- Inference depends on the kind of token:
128
-
129
- | `PAGERDUTY_TOKEN` | Inferred user |
130
- | --- | --- |
131
- | User token REST API key | The key's own user |
132
- | OAuth user token (Classic User OAuth or Scoped OAuth), written as `Bearer <token>` | The user who authorized the app |
133
- | General access (account-level) REST API key | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
134
- | Scoped OAuth app token (client credentials) | The user whose email is exactly `PAGERDUTY_FROM_EMAIL`, if set |
135
-
136
- PagerDuty serves
137
- [`GET /users/me`](https://developer.pagerduty.com/api-reference/0b6f8b0c3e8d1-get-the-current-user)
138
- only to a user-level API key or a token from an OAuth flow, not to an
139
- account-level key. An app token
140
- [acts as the app](https://docs.pagerduty.com/developer/private-apps),
141
- not as a user. With either, the channel looks up `PAGERDUTY_FROM_EMAIL`,
142
- the `From` user the token writes as, through `GET /users?query=` and uses
143
- the one user whose email matches exactly. The inferred id is kept in the
144
- agent's memory for an hour per token, never in agent storage, and an
145
- unresolved answer is retried after five minutes. Hosted, the lookup needs
146
- `api.pagerduty.com` (or your `PAGERDUTY_API_BASE_URL` host) in
147
- `hosting.egressDomains`, the same entry write-backs need.
148
-
149
- A read-only agent with no token sets the id directly:
150
-
151
- ```bash
152
- agent-sdk secret set incident-responder PAGERDUTY_USER_ID
153
- ```
154
-
155
- `PAGERDUTY_USER_ID` holds one id because a deployment has one token
156
- and so acts as one PagerDuty user. To skip several users, or to keep the
157
- id in code, pass `selfUserIds`:
91
+ PagerDuty sends the agent's own changes back as webhook events, such as a note it posted or an
92
+ incident it resolved. The channel acknowledges those events without starting a turn, and the same
93
+ action by a person still arrives.
158
94
 
159
95
  ```ts
160
96
  export default pagerdutyChannel({
97
+ // Events caused by the agent's own PagerDuty user are skipped.
98
+ // The user comes from, in order: selfUserIds, PAGERDUTY_USER_ID,
99
+ // or the user PAGERDUTY_TOKEN acts as (GET /users/me).
161
100
  selfUserIds: ["PBOT001"],
162
101
  onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
163
102
  });
164
103
  ```
165
104
 
166
- `selfUserIds: { secretName: "OTHER_NAME" }` reads one id from another
167
- secret and never falls back to inference.
105
+ A user-level API key or an OAuth user token acts as one user. An account-level key or an app token
106
+ acts as no user, so the channel uses the user whose email matches `PAGERDUTY_FROM_EMAIL`. A
107
+ read-only agent with no token sets `PAGERDUTY_USER_ID` instead. When none of these names a user, the
108
+ channel skips nothing.
168
109
 
169
110
  ## Events
170
111
 
171
112
  Each hook receives one family of v3 events:
172
113
 
173
- | Hook | Events |
174
- | --- | --- |
175
- | `onIncident` | `incident.triggered`, `.acknowledged`, `.unacknowledged`, `.escalated`, `.reassigned`, `.delegated`, `.resolved`, `.reopened`, `.priority_updated`, `.incident_type.changed` |
176
- | `onNote` | `incident.annotated` |
177
- | `onResponder` | `incident.responder.added`, `incident.responder.replied` |
178
- | `onEvent` | Everything else, such as status updates and workflow events |
179
-
180
- Without `onIncident`, a triggered or reopened incident starts a turn and
181
- other lifecycle events are acknowledged. Notes, responder events, and
182
- the rest are acknowledged until you add their hook. Each hook returns
183
- one of three decisions:
184
-
185
- | Return | What happens |
186
- | --- | --- |
187
- | `{ auth }` | Start or continue a model turn as the event's actor |
188
- | `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
189
- | `null` | Skip the event |
190
-
191
- ## Incident affinity
192
-
193
- Every event for one incident joins one session, keyed on the incident
194
- id. Lifecycle events carry the incident, and notes and responder events
195
- name it by reference, so all of them reach the same session.
114
+ | Hook | Events |
115
+ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `onIncident` | `incident.triggered`, `.acknowledged`, `.unacknowledged`, `.escalated`, `.reassigned`, `.delegated`, `.resolved`, `.reopened`, `.priority_updated`, `.incident_type.changed` |
117
+ | `onNote` | `incident.annotated` |
118
+ | `onResponder` | `incident.responder.added`, `incident.responder.replied` |
119
+ | `onEvent` | Everything else, such as status updates and workflow events |
196
120
 
197
- A re-trigger after a resolve is a new PagerDuty incident, so it starts a
198
- new session. `ctx.incidentKey` carries the dedup key of the alert that
199
- opened an incident (its `incident_key`, set per alert by a Datadog
200
- monitor, a Sentry issue, or a Grafana rule), for an agent that wants to
201
- recall what it found the last time the same alert fired.
121
+ Without `onIncident`, a triggered or reopened incident starts a turn. The channel acknowledges every
122
+ other event until you add its hook. Each hook returns `{ auth }`, `{ task }`, or `null`, as
123
+ [Handler results](/docs/reference/channels.md#handler-results) describes.
202
124
 
203
125
  ## Connect
204
126
 
205
- Create a v3 webhook subscription in PagerDuty for the services that
206
- should wake the agent, and point it at
207
- `https://<your-host>/<slug>/v1/channels/pagerduty`. Then set the
208
- channel's secrets on the deployment. Locally the same names are
209
- environment variables.
127
+ Create a v3 webhook subscription in PagerDuty for the services the agent should respond to, and
128
+ point it at `https://<your-host>/<slug>/v1/channels/pagerduty`. Set the channel's secrets on the
129
+ deployment, or as environment variables locally.
210
130
 
211
- | Variable | Used for | Override |
212
- | --- | --- | --- |
213
- | `PAGERDUTY_WEBHOOK_SECRET` | Verifying `X-PagerDuty-Signature`. Hosted, the platform checks it before any compute starts and answers a bad delivery with `401` | `webhookSecret: { secretName }` |
214
- | `PAGERDUTY_USER_ID` | Skipping the agent's own actions: its PagerDuty user id. Optional when `PAGERDUTY_TOKEN` names a user | `selfUserIds: [ids]` or `{ secretName }` |
215
- | `PAGERDUTY_TOKEN` | Reply notes (with `deliverReplies: true`), `ctx.pagerduty`, and inferring the agent's user: a REST API key, or an OAuth token as `Bearer <token>` | `token: { secretName }` |
216
- | `PAGERDUTY_FROM_EMAIL` | The `From` user PagerDuty requires for writes made with an account-level key or app token, and the user inferred for those tokens | `from: { secretName }` |
217
- | `PAGERDUTY_API_BASE_URL` | The REST host, such as `https://api.eu.pagerduty.com`. Defaults to `https://api.pagerduty.com` | `apiBaseUrl` |
131
+ | Variable | Used for | Override |
132
+ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
133
+ | `PAGERDUTY_WEBHOOK_SECRET` | Verifying `X-PagerDuty-Signature`. On Cursor hosting, a delivery with a bad signature gets a `401`. | `webhookSecret: { secretName }` |
134
+ | `PAGERDUTY_USER_ID` | The agent's own PagerDuty user ID. Optional when `PAGERDUTY_TOKEN` names a user. | `selfUserIds: [ids]` or `{ secretName }` |
135
+ | `PAGERDUTY_TOKEN` | Reply notes, `ctx.pagerduty`, and finding the agent's user. Use a REST API key, or an OAuth token as `Bearer <token>`. | `token: { secretName }` |
136
+ | `PAGERDUTY_FROM_EMAIL` | The `From` user for writes with an account-level key or app token. | `from: { secretName }` |
137
+ | `PAGERDUTY_API_BASE_URL` | The REST host, such as `https://api.eu.pagerduty.com`. Defaults to `https://api.pagerduty.com`. | `apiBaseUrl` |
218
138
 
219
- Set `token`, `from`, and `apiBaseUrl` on `pagerdutyChannel()`; they cover
220
- reply notes, `ctx.pagerduty`, and inference. `createPagerDutyClient()`
221
- takes the same options for code outside the channel.
139
+ `createPagerDutyClient()` takes the same options for code outside the channel.
222
140
 
223
141
  ```bash
224
142
  agent-sdk deploy --dir . --slug incident-responder
225
143
  agent-sdk secret set incident-responder PAGERDUTY_WEBHOOK_SECRET PAGERDUTY_TOKEN
226
- agent-sdk secret list incident-responder
227
144
  ```
228
145
 
229
- `agent-sdk deploy` warns until `PAGERDUTY_WEBHOOK_SECRET` is set, and until
230
- either `PAGERDUTY_USER_ID` or `PAGERDUTY_TOKEN` is. The next delivery
231
- uses a new value without another deploy.
146
+ The next delivery picks up a new value without another deploy. Until the webhook secret is set, the
147
+ route accepts only loopback deliveries under `agent-sdk dev`.
232
148
 
233
149
  ### Several subscriptions
234
150
 
235
- PagerDuty gives each webhook subscription its own signing secret, so an
236
- agent fed by several subscriptions (one per service, say) needs all of
237
- them. Put them in `PAGERDUTY_WEBHOOK_SECRET`, one per line:
151
+ PagerDuty gives each webhook subscription its own signing secret. Put one secret on each line of
152
+ `PAGERDUTY_WEBHOOK_SECRET`:
238
153
 
239
154
  ```text
240
155
  <signing secret of subscription 1>
241
156
  <signing secret of subscription 2>
242
157
  ```
243
158
 
244
- A delivery is admitted when any `v1=` signature in its
245
- `X-PagerDuty-Signature` header matches any line. Each line is trimmed,
246
- blank lines are ignored, and a value without a line break is one secret,
247
- used as-is. The value holds at most 32 secrets. Past that, every delivery
248
- is rejected rather than checked against only some of them.
249
-
250
- Keep the list in a file, since `agent-sdk secret list` never shows values,
251
- and set it from stdin, which keeps the line breaks:
159
+ A delivery passes when its signature matches any line. Set the value from that file:
252
160
 
253
161
  ```bash
254
162
  agent-sdk secret set incident-responder PAGERDUTY_WEBHOOK_SECRET < pagerduty-webhook-secrets.txt
255
163
  ```
256
164
 
257
- Rotate by adding before removing. Add the new secret as a line before
258
- PagerDuty starts signing with it, for example before creating the
259
- replacement subscription. Remove the old line only once nothing signs
260
- with the old secret, for example after deleting the subscription it
261
- replaced. While both are live, a delivery signed with either secret
262
- verifies, including one whose header carries both signatures. Removing
263
- the old line first rejects those deliveries until the new one is added.
264
-
265
- The same format works for every `hmacSignatureAuth()` secret, including
266
- `GITHUB_WEBHOOK_SECRET` and `BITBUCKET_WEBHOOK_SECRET`. It needs
267
- `@grok/agent-sdk` 0.2.25 or later. Earlier versions check the signature again
268
- in the agent with the whole value as one secret, so they reject every
269
- delivery once the value has a second line.
270
-
271
- Only signature checks read the value as a list. Everywhere else it is
272
- used whole: a `sharedSecretAuth()` header compares the entire value, and
273
- a `${NAME}` template in an MCP connection's `headers` would put the line
274
- breaks into the header. Keep a list secret for webhook signing only.
275
-
276
- Until `PAGERDUTY_WEBHOOK_SECRET` is set, the route accepts only local
277
- traffic: loopback deliveries under `agent-sdk dev`, nothing in production.
165
+ To rotate a secret, add the new one before PagerDuty signs with it, and remove the old one once
166
+ nothing signs with it.
278
167
 
279
168
  ## Test locally
280
169
 
281
- `agent-sdk pagerduty replay` posts synthesized v3 deliveries for one incident
282
- to the running agent, in order. With `PAGERDUTY_WEBHOOK_SECRET` unset,
283
- `agent-sdk dev` admits them unsigned from loopback; with it set, replay signs
284
- them the way PagerDuty does:
170
+ `agent-sdk pagerduty replay` posts synthesized v3 deliveries for one incident to the running agent,
171
+ in order. Without `PAGERDUTY_WEBHOOK_SECRET`, `agent-sdk dev` admits them unsigned from loopback.
172
+ With it set, replay signs them the way PagerDuty does.
285
173
 
286
174
  ```bash
287
175
  agent-sdk dev &
@@ -289,15 +177,11 @@ agent-sdk pagerduty replay --events triggered,acknowledged,annotated,resolved \
289
177
  --comment "Rolled back the 09:30 deploy."
290
178
  ```
291
179
 
292
- The trigger comes from PagerDuty itself, and the later events come from a
293
- person, so each one joins the session the trigger started. Pass an
294
- incident id to start another session, `--dry-run` to print the bodies,
295
- or `--out fixtures/pagerduty` to save them as fixtures for
296
- [evals](/docs/evals.md). `agent-sdk pagerduty events` lists the channels and the
297
- events each accepts.
180
+ Each event joins the session the trigger started. Pass an incident ID to start another session,
181
+ `--dry-run` to print the bodies, or `--fixtures-dir fixtures/pagerduty` to save them as fixtures for
182
+ [evals](/docs/evals.md).
298
183
 
299
- To post a real delivery saved from the webhook's delivery log, sign it
300
- with the secret:
184
+ To post a delivery you saved from the webhook log, sign it:
301
185
 
302
186
  ```bash
303
187
  export PAGERDUTY_WEBHOOK_SECRET=local-test-secret
@@ -305,32 +189,14 @@ agent-sdk dev &
305
189
 
306
190
  body=fixtures/pagerduty/incident-triggered.json
307
191
  signature=$(openssl dgst -sha256 -hmac "$PAGERDUTY_WEBHOOK_SECRET" -hex < "$body" | awk '{print $NF}')
308
- curl -X POST http://127.0.0.1:3000/v1/channels/pagerduty \
192
+ curl -X POST http://127.0.0.1:3000/<slug>/v1/channels/pagerduty \
309
193
  -H 'content-type: application/json' \
310
194
  -H "x-pagerduty-signature: v1=$signature" \
311
195
  --data-binary @"$body"
312
196
  ```
313
197
 
314
- Set `event.agent.id` in a saved body to the agent's own user id to see
315
- the delivery skipped as an echo.
316
-
317
- ## Practices
318
-
319
- - Write back from host code with the incident in channel state or
320
- `ctx`, never from an incident id the model produced.
321
-
322
- - Make sure the agent knows its own user before it acts on incidents, so
323
- its own notes and resolves do not wake it again: a user-level token, a
324
- `PAGERDUTY_FROM_EMAIL` with an account-level key, or `PAGERDUTY_USER_ID`.
325
-
326
- - Scope the webhook subscription to the services the agent responds to;
327
- every delivery it sends reaches the channel.
328
-
329
198
  ## Related
330
199
 
331
- - [Channels reference](/docs/reference/channels.md): channel hooks,
332
- dispatch decisions, and session behavior
333
- - [Webhooks and custom channels](/docs/guides/webhooks.md): direct webhook auth
334
- and reply delivery
335
- - [Evals](/docs/evals.md): turn saved PagerDuty payloads into regression
336
- fixtures
200
+ - [Channels reference](/docs/reference/channels.md)
201
+ - [Webhooks and custom channels](/docs/guides/webhooks.md)
202
+ - [Evals](/docs/evals.md)