@grok/agent-sdk 0.2.29 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (396) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/docs/404.html +2 -2
  3. package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
  4. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  5. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  6. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  7. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  8. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  9. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  10. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
  11. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  12. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
  13. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  14. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  15. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  16. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  17. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  18. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  24. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  25. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  26. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  27. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  28. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  29. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  30. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  33. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  34. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  35. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  36. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  37. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
  38. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  39. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  40. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  41. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  42. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
  43. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
  44. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
  45. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  46. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  47. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  48. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  49. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  50. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  51. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  52. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  53. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
  54. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  55. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  56. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  57. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  58. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  59. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  60. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  61. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  62. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  63. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  64. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  65. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  66. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  67. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  68. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  69. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  70. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  72. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  74. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  75. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  76. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  77. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  78. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  80. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  81. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  82. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  83. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  84. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  85. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  86. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  87. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  88. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  89. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  90. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  91. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  92. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  93. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  94. package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
  95. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  96. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  97. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  98. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  99. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  100. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  101. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  102. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  103. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  104. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  105. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  106. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  107. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  108. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  109. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  110. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  111. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  112. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  113. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  114. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  115. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  116. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  117. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  118. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  119. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  120. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  121. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  122. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  123. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  124. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  125. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  126. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  127. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  128. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  129. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  130. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  131. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  132. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  133. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  134. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  135. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  136. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  137. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  138. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  139. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  140. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  141. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  142. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  143. package/dist/docs/building-with-agents.html +41 -44
  144. package/dist/docs/building-with-agents.md +11 -104
  145. package/dist/docs/changelog.html +37 -37
  146. package/dist/docs/changelog.md +5 -155
  147. package/dist/docs/deployment.html +54 -54
  148. package/dist/docs/deployment.md +83 -262
  149. package/dist/docs/evals.html +52 -71
  150. package/dist/docs/evals.md +33 -129
  151. package/dist/docs/guides/agent-to-agent.html +43 -43
  152. package/dist/docs/guides/agent-to-agent.md +27 -64
  153. package/dist/docs/guides/bitbucket.html +62 -62
  154. package/dist/docs/guides/bitbucket.md +73 -134
  155. package/dist/docs/guides/cloud-agents.html +37 -37
  156. package/dist/docs/guides/cloud-agents.md +23 -53
  157. package/dist/docs/guides/convert-automation.html +39 -56
  158. package/dist/docs/guides/convert-automation.md +31 -115
  159. package/dist/docs/guides/github.html +46 -54
  160. package/dist/docs/guides/github.md +49 -131
  161. package/dist/docs/guides/gitlab.html +98 -108
  162. package/dist/docs/guides/gitlab.md +104 -184
  163. package/dist/docs/guides/improve.html +38 -43
  164. package/dist/docs/guides/improve.md +24 -90
  165. package/dist/docs/guides/jev.html +55 -95
  166. package/dist/docs/guides/jev.md +53 -160
  167. package/dist/docs/guides/mcp-oauth.html +38 -40
  168. package/dist/docs/guides/mcp-oauth.md +33 -67
  169. package/dist/docs/guides/migrate.html +38 -43
  170. package/dist/docs/guides/migrate.md +56 -130
  171. package/dist/docs/guides/opentelemetry.html +41 -43
  172. package/dist/docs/guides/opentelemetry.md +32 -27
  173. package/dist/docs/guides/pagerduty.html +50 -49
  174. package/dist/docs/guides/pagerduty.md +65 -199
  175. package/dist/docs/guides/slack.html +51 -57
  176. package/dist/docs/guides/slack.md +76 -204
  177. package/dist/docs/guides/webhooks.html +42 -42
  178. package/dist/docs/guides/webhooks.md +64 -146
  179. package/dist/docs/hashmap.json +1 -1
  180. package/dist/docs/hillclimbing.html +40 -42
  181. package/dist/docs/hillclimbing.md +40 -102
  182. package/dist/docs/index.html +55 -61
  183. package/dist/docs/index.md +49 -83
  184. package/dist/docs/llms-full.txt +2262 -5721
  185. package/dist/docs/llms.txt +9 -14
  186. package/dist/docs/quickstart.html +95 -152
  187. package/dist/docs/quickstart.md +91 -180
  188. package/dist/docs/reference/access.html +36 -36
  189. package/dist/docs/reference/access.md +7 -12
  190. package/dist/docs/reference/agent-config.html +43 -56
  191. package/dist/docs/reference/agent-config.md +91 -174
  192. package/dist/docs/reference/artifacts.html +38 -39
  193. package/dist/docs/reference/artifacts.md +38 -62
  194. package/dist/docs/reference/channels.html +38 -39
  195. package/dist/docs/reference/channels.md +102 -151
  196. package/dist/docs/reference/cli.html +68 -84
  197. package/dist/docs/reference/cli.md +232 -697
  198. package/dist/docs/reference/connections.html +45 -57
  199. package/dist/docs/reference/connections.md +83 -164
  200. package/dist/docs/reference/evals.html +47 -54
  201. package/dist/docs/reference/evals.md +75 -141
  202. package/dist/docs/reference/extensions.html +41 -43
  203. package/dist/docs/reference/extensions.md +37 -70
  204. package/dist/docs/reference/hooks.html +40 -52
  205. package/dist/docs/reference/hooks.md +62 -133
  206. package/dist/docs/reference/http-api.html +38 -42
  207. package/dist/docs/reference/http-api.md +66 -118
  208. package/dist/docs/reference/instructions.html +39 -39
  209. package/dist/docs/reference/instructions.md +19 -29
  210. package/dist/docs/reference/limits.html +38 -38
  211. package/dist/docs/reference/limits.md +9 -21
  212. package/dist/docs/reference/memory.html +37 -38
  213. package/dist/docs/reference/memory.md +38 -75
  214. package/dist/docs/reference/playground.html +36 -36
  215. package/dist/docs/reference/playground.md +14 -22
  216. package/dist/docs/reference/project-layout.html +49 -48
  217. package/dist/docs/reference/project-layout.md +38 -84
  218. package/dist/docs/reference/schedules.html +46 -48
  219. package/dist/docs/reference/schedules.md +59 -90
  220. package/dist/docs/reference/sessions.html +37 -37
  221. package/dist/docs/reference/sessions.md +66 -113
  222. package/dist/docs/reference/skills.html +39 -39
  223. package/dist/docs/reference/skills.md +11 -31
  224. package/dist/docs/reference/subagents.html +37 -37
  225. package/dist/docs/reference/subagents.md +17 -31
  226. package/dist/docs/reference/tools.html +47 -64
  227. package/dist/docs/reference/tools.md +48 -130
  228. package/dist/docs/templates/agentic-owners.html +38 -38
  229. package/dist/docs/templates/agentic-owners.md +50 -74
  230. package/dist/docs/templates/reviews.html +69 -0
  231. package/dist/docs/templates/reviews.md +71 -0
  232. package/dist/docs/troubleshooting.html +38 -36
  233. package/dist/docs/troubleshooting.md +48 -101
  234. package/dist/internal/cli-deploy.js +1 -1
  235. package/dist/internal/cli-docs.js +1 -1
  236. package/dist/internal/cli-images.js +1 -1
  237. package/dist/internal/cli-skills.js +1 -1
  238. package/dist/internal/cursor/credentials.js +1 -1
  239. package/dist/internal/deploy-manifest.d.ts +1 -0
  240. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  241. package/dist/internal/deploy-manifest.js +0 -1
  242. package/dist/internal/discovery/agent-config.d.ts +2 -6
  243. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  244. package/dist/internal/discovery/agent-config.js +8 -25
  245. package/dist/internal/discovery/agent.d.ts.map +1 -1
  246. package/dist/internal/discovery/agent.js +2 -3
  247. package/dist/internal/discovery/project.d.ts.map +1 -1
  248. package/dist/internal/discovery/project.js +15 -0
  249. package/dist/internal/init-project.d.ts.map +1 -1
  250. package/dist/internal/init-project.js +7 -5
  251. package/dist/internal/reminder-runner.js +1 -1
  252. package/dist/internal/session-engine.js +1 -1
  253. package/dist/internal/shallow-clone.js +1 -1
  254. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  255. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  256. package/dist/playground/index.html +2 -2
  257. package/dist/types.d.ts +4 -17
  258. package/dist/types.d.ts.map +1 -1
  259. package/docs/README.md +49 -83
  260. package/docs/building-with-agents.md +11 -104
  261. package/docs/changelog.md +6 -156
  262. package/docs/deployment.md +83 -262
  263. package/docs/evals.md +34 -130
  264. package/docs/guides/agent-to-agent.md +27 -64
  265. package/docs/guides/bitbucket.md +73 -134
  266. package/docs/guides/cloud-agents.md +23 -53
  267. package/docs/guides/convert-automation.md +31 -115
  268. package/docs/guides/github.md +49 -131
  269. package/docs/guides/gitlab.md +104 -184
  270. package/docs/guides/improve.md +24 -90
  271. package/docs/guides/jev.md +53 -160
  272. package/docs/guides/mcp-oauth.md +33 -67
  273. package/docs/guides/migrate.md +56 -130
  274. package/docs/guides/opentelemetry.md +37 -27
  275. package/docs/guides/pagerduty.md +68 -200
  276. package/docs/guides/slack.md +76 -204
  277. package/docs/guides/webhooks.md +64 -146
  278. package/docs/hillclimbing.md +41 -103
  279. package/docs/quickstart.md +91 -180
  280. package/docs/reference/access.md +7 -12
  281. package/docs/reference/agent-config.md +91 -174
  282. package/docs/reference/artifacts.md +38 -62
  283. package/docs/reference/channels.md +102 -151
  284. package/docs/reference/cli.md +232 -697
  285. package/docs/reference/connections.md +83 -164
  286. package/docs/reference/evals.md +75 -141
  287. package/docs/reference/extensions.md +37 -70
  288. package/docs/reference/hooks.md +61 -132
  289. package/docs/reference/http-api.md +66 -118
  290. package/docs/reference/instructions.md +20 -30
  291. package/docs/reference/limits.md +10 -22
  292. package/docs/reference/memory.md +38 -75
  293. package/docs/reference/playground.md +14 -22
  294. package/docs/reference/project-layout.md +38 -84
  295. package/docs/reference/schedules.md +59 -90
  296. package/docs/reference/sessions.md +66 -113
  297. package/docs/reference/skills.md +12 -32
  298. package/docs/reference/subagents.md +17 -31
  299. package/docs/reference/tools.md +48 -130
  300. package/docs/templates/agentic-owners.md +50 -74
  301. package/docs/templates/reviews.md +76 -0
  302. package/docs/troubleshooting.md +48 -101
  303. package/package.json +2 -2
  304. package/skills/deploy/SKILL.md +1 -1
  305. package/skills/migrate-v2/SKILL.md +0 -1
  306. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  307. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  308. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  309. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  310. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  311. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  312. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  313. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  314. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  315. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  316. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  317. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  318. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  319. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  320. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  321. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  322. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  323. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  324. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  325. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  326. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  327. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  328. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  329. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  330. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  331. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  332. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  333. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  334. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  335. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  336. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  337. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  338. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  339. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  340. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  341. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  342. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  343. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  344. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  345. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  346. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  347. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  348. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  349. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  350. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  351. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  352. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  353. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  354. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  355. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  356. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  357. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  358. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  359. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  360. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  361. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  362. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  363. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  364. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  365. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  366. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  367. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  368. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  369. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  370. package/dist/docs/guides/hooks.html +0 -113
  371. package/dist/docs/guides/hooks.md +0 -116
  372. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  373. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  374. package/dist/docs/package/skills/github/SKILL.md +0 -133
  375. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  376. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  377. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  378. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  379. package/dist/docs/reference/prompt.html +0 -68
  380. package/dist/docs/reference/prompt.md +0 -47
  381. package/dist/docs/templates/security-reviewer.html +0 -62
  382. package/dist/docs/templates/security-reviewer.md +0 -81
  383. package/dist/docs/templates/thermo-quality-review.html +0 -62
  384. package/dist/docs/templates/thermo-quality-review.md +0 -75
  385. package/dist/docs/templates/thermo-review.html +0 -62
  386. package/dist/docs/templates/thermo-review.md +0 -75
  387. package/dist/docs/templates/triage.html +0 -68
  388. package/dist/docs/templates/triage.md +0 -101
  389. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  390. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  391. package/docs/guides/hooks.md +0 -121
  392. package/docs/reference/prompt.md +0 -52
  393. package/docs/templates/security-reviewer.md +0 -86
  394. package/docs/templates/thermo-quality-review.md +0 -80
  395. package/docs/templates/thermo-review.md +0 -80
  396. package/docs/templates/triage.md +0 -106
@@ -5,18 +5,14 @@ description: "Let an agent propose a change to its own source through a branch a
5
5
 
6
6
  # Self-improvement
7
7
 
8
- The `improve` extension teaches an agent how to turn "change how you
9
- work" into a source change. The agent prepares a brief, a Cursor cloud
10
- agent edits a checkout and opens a pull request, and the running agent
11
- reports the verified PR for human review.
12
-
13
- Durable behavior does not change until that source is merged and
14
- deployed.
8
+ The `improve` extension lets an agent turn "change how you work" into a change
9
+ to its own source. The agent writes a brief, a Cursor cloud agent edits a
10
+ checkout and opens a pull request, and the agent reports the pull request.
15
11
 
16
12
  ## Mount it
17
13
 
18
- Mount Cloud agents with the agent's own repository allowlisted, then
19
- mount `improve` with the source directory.
14
+ Mount [Cloud agents](./cloud-agents.md) with the agent's own repository in
15
+ `cloud.repos`, then mount `improve` with its source directory.
20
16
 
21
17
  ```ts
22
18
  // bot/extensions/cloud.ts
@@ -24,12 +20,7 @@ import cursorCloudAgents from "@grok/agent-sdk/extensions/cursor-cloud-agents";
24
20
 
25
21
  export default cursorCloudAgents({
26
22
  cloud: {
27
- repos: [
28
- {
29
- url: "https://github.com/acme/agents",
30
- startingRef: "main",
31
- },
32
- ],
23
+ repos: [{ url: "https://github.com/acme/agents", startingRef: "main" }],
33
24
  autoCreatePR: true,
34
25
  },
35
26
  });
@@ -46,89 +37,32 @@ export default improve({
46
37
  });
47
38
  ```
48
39
 
49
- Mounted as `improve`, the extension contributes the
50
- `improve__yourself` skill. It does not contribute a tool that can bypass
51
- the normal repository workflow.
52
-
53
- ## Ask for one behavioral change
54
-
55
- State the change, how to tell it worked, and what behavior must stay
56
- fixed. The agent maps the request to instructions, a skill, a tool,
57
- channel configuration, or the model setting before preparing the coding
58
- brief.
59
-
60
- > Improve yourself: stop opening incident replies with a summary.
61
- > Start with the decision, keep the existing evidence bullets, and
62
- > preserve every current eval.
63
-
64
- The success criterion and freeze line keep the cloud agent from turning
65
- a narrow behavior request into an unrelated refactor.
40
+ `improve` adds the `improve__yourself` skill and no tools.
66
41
 
67
- ## Follow the source change
42
+ ## Ask for one change
68
43
 
69
- The agent launches one cloud agent on the configured repository and
70
- ref. It reports the complete cloud-agent ID
71
- and URL immediately, then checks the same run instead of launching
72
- another agent for follow-up work.
44
+ Say what to change, how to tell it worked, and what must not change.
73
45
 
74
- When the cloud agent opens a pull request, the running agent reads the
75
- result and the PR before reporting what changed and which checks passed.
76
- The pull request, not the delegation transcript, is the durable
77
- deliverable.
46
+ > Improve yourself. Stop opening incident replies with a summary. Start with
47
+ > the decision, keep the existing evidence bullets, and preserve every current
48
+ > eval.
78
49
 
79
- Use the [Cloud agents guide](./cloud-agents.md) for launch, status,
80
- transcript, steering, and cancellation behavior.
50
+ The agent launches one cloud agent and reports its URL. When the pull request
51
+ opens, the agent tells you what changed and which checks passed.
81
52
 
82
53
  ## Review, merge, then deploy
83
54
 
84
- The workflow stops at a pull request. A human reviews the diff and
85
- decides whether to merge it; a separate deployment action decides when
86
- the new behavior becomes live.
87
-
88
- This separation gives each boundary a real control:
89
-
90
- - Repository permissions limit who can push the branch.
91
- - Branch protection and review policy govern the merge.
92
- - Deployment authorization governs the running agent.
93
-
94
- After deployment, repeat the original request or regression eval to
95
- confirm the behavior changed without crossing the freeze line.
55
+ The agent can open a pull request, but it can't merge or deploy. Someone on your
56
+ team reviews and merges it, and the change goes live on your next deploy.
57
+ Afterward, repeat the original request to confirm the change.
96
58
 
97
59
  ## Configure it
98
60
 
99
61
  - `repo` is the source repository URL.
100
- - `path` is the agent's repository-relative directory.
101
- - `ref` is the deployed branch or ref that new branches and pull
102
- requests target; it defaults to `main`.
103
- - `notes` adds tree-specific guidance to every coding brief, such as a
104
- required test command or PR convention.
105
- - `deploy` tells the skill who deploys a merged change and when it
106
- becomes live.
107
-
108
- `notes` and `deploy` insert prose into the contributed skill. They do
109
- not run checks, merge a branch, or trigger a deployment.
110
-
111
- Validation checks the URL and path shape. It does not prove the source
112
- exists, matches the current deployment, or appears in the Cloud agents
113
- repository allowlist, so keep those values aligned yourself.
114
-
115
- ## What the extension enforces
116
-
117
- `improve__yourself` is model guidance for locating the change, writing a
118
- brief, following repository rules, opening a PR, and reporting it. Rules
119
- such as "never merge" are instructions, not framework-enforced
120
- permissions.
121
-
122
- Use repository and deployment controls for hard enforcement. The
123
- extension provides a repeatable path through those controls; it does not
124
- replace them.
125
-
126
- ## What's next
127
-
128
- - [Cloud agents](./cloud-agents.md): delegation and steering
129
- - [Build with a coding agent](../building-with-agents.md): have an
130
- external coding agent edit the project directly
131
- - [Extensions](../reference/extensions.md): namespaces and overlays
132
- - [Deployment](../deployment.md): make a merged source change live
133
- - [Evals](../evals.md): protect the requested behavior before and after
134
- the change
62
+ - `path` is the agent's directory in that repository.
63
+ - `ref` is the branch new pull requests target, `main` by default.
64
+ - `notes` adds guidance to every brief, such as a required test command.
65
+ - `deploy` tells the skill who deploys a merged change and when.
66
+
67
+ Validation checks only the shape of `repo` and `path`, so make sure they match
68
+ the deployed agent and `cloud.repos`.
@@ -6,17 +6,16 @@ description: "Use typed Jev decisions to filter findings, route pull requests, a
6
6
  # Use Jev in review tools
7
7
 
8
8
  > [!WARNING]
9
- > **Experimental.** `@grok/agent-sdk/extensions/jev` is experimental. Its
9
+ > Experimental. `@grok/agent-sdk/extensions/jev` is experimental. Its
10
10
  > exports and behavior can change in any release, without a deprecation
11
11
  > period.
12
12
 
13
- Use Jev when a review workflow needs a typed decision instead of prose.
14
- A review agent can filter speculative findings, classify pull request
15
- risk, choose a reviewer, or decide whether a merge needs a documentation
16
- follow-up. Jev returns a choice, score, or probability; your TypeScript
17
- decides what happens next.
13
+ Use Jev when a review workflow needs a typed decision instead of prose. Jev
14
+ returns a choice, a score, or a probability, and your TypeScript decides what
15
+ happens next.
18
16
 
19
- Set `TYPESAFE_API_KEY`. The default model is `jev-latest`.
17
+ Set `TYPESAFE_API_KEY`, then mount the extension. The default model is
18
+ `jev-latest`.
20
19
 
21
20
  ```ts
22
21
  // bot/extensions/jev.ts
@@ -25,21 +24,17 @@ import jev from "@grok/agent-sdk/extensions/jev";
25
24
  export default jev();
26
25
  ```
27
26
 
28
- On Cursor-managed hosting, this mount adds `api.typesafe.ai` to the
29
- deployment's egress allowlist and `TYPESAFE_API_KEY` to the secrets it
30
- expects, so `agent-sdk deploy` warns until you set the key. A project that
31
- imports `decide` or `evaluate` without mounting the extension has to
32
- list `api.typesafe.ai` in `hosting.egressDomains` itself; see
33
- [Add egress and secrets](../deployment.md#add-egress-and-secrets).
27
+ On Cursor hosting, the mount adds `api.typesafe.ai` to egress and
28
+ `TYPESAFE_API_KEY` to the expected secrets. Without the mount,
29
+ [add `api.typesafe.ai`](../deployment.md#add-egress-and-secrets) to
30
+ `hosting.egressDomains` yourself.
34
31
 
35
32
  ## Start only the review turns you need
36
33
 
37
- Call Jev from a channel hook before a model turn starts. When a pull
38
- request opens or becomes ready for review, this hook sends its title,
39
- body, labels, and filenames to Jev to decide whether the change needs
40
- security review. A result that clears the threshold starts the review
41
- turn; otherwise, the hook returns `null`, so the agent doesn't run or
42
- post to GitHub.
34
+ Call Jev from a channel hook before a model turn starts. This hook asks Jev
35
+ whether a new pull request needs security review, based on its title, body, and
36
+ file names. Below the threshold, the hook returns `null`, so the agent doesn't
37
+ run or post anything.
43
38
 
44
39
  ```ts
45
40
  // bot/channels/github.ts
@@ -50,7 +45,6 @@ import {
50
45
  import { above, decide } from "@grok/agent-sdk/extensions/jev";
51
46
 
52
47
  export default githubChannel({
53
- botName: "security-reviewer",
54
48
  cursorAccount: { repos: ["acme/checkout"] },
55
49
  onPullRequest: async (ctx, pr) => {
56
50
  if (pr.action !== "opened" && pr.action !== "ready_for_review") {
@@ -58,30 +52,21 @@ export default githubChannel({
58
52
  }
59
53
 
60
54
  const octokit = await ctx.github.getOctokit();
61
- const [{ data }, files] = await Promise.all([
62
- octokit.rest.pulls.get({
63
- owner: ctx.repository.owner,
64
- repo: ctx.repository.name,
65
- pull_number: pr.number,
66
- }),
67
- octokit.paginate(octokit.rest.pulls.listFiles, {
68
- owner: ctx.repository.owner,
69
- repo: ctx.repository.name,
70
- pull_number: pr.number,
71
- }),
72
- ]);
55
+ const files = await octokit.paginate(octokit.rest.pulls.listFiles, {
56
+ owner: ctx.repository.owner,
57
+ repo: ctx.repository.name,
58
+ pull_number: pr.number,
59
+ });
73
60
  const answers = await decide({
74
61
  state: {
75
- title: data.title,
76
- body: data.body,
77
- labels: data.labels.map(label => label.name),
62
+ title: pr.title,
63
+ body: pr.body,
78
64
  files: files.map(file => file.filename),
79
65
  },
80
66
  questions: {
81
67
  review: {
82
68
  type: "boolean",
83
- instructions:
84
- "Does this change need security review? Answer yes for auth, permissions, secrets, request parsing, or external inputs.",
69
+ instructions: "Does this change touch auth, permissions, secrets, or external input?",
85
70
  },
86
71
  },
87
72
  });
@@ -89,20 +74,15 @@ export default githubChannel({
89
74
  if (!above(answers.review, 0.8)) {
90
75
  return null;
91
76
  }
92
- // `auth` starts a model turn running as the pull request sender.
93
77
  return { auth: defaultGitHubAuth(ctx) };
94
78
  },
95
79
  });
96
80
  ```
97
81
 
98
- Jev receives only the pull request metadata shown here, not the diff.
99
-
100
82
  ## Filter findings before you post them
101
83
 
102
- Let the chat model draft a finding, then ask Jev whether the finding is
103
- a real bug in the new code. Below your threshold, the tool returns and
104
- the author never sees the draft. Above it, the finding becomes a review
105
- comment.
84
+ Let the model draft a finding, then ask Jev whether it's a real bug in the new
85
+ code. The tool posts only the drafts that clear your threshold.
106
86
 
107
87
  ```ts
108
88
  // bot/tools/post_finding.ts
@@ -112,14 +92,12 @@ import { defineTool } from "@grok/agent-sdk/tools";
112
92
  import { z } from "zod";
113
93
 
114
94
  export default defineTool({
115
- description:
116
- "Post one security finding on this session's pull request. Call once. Hold when it is not a real bug.",
95
+ description: "Post one security finding on this session's pull request.",
117
96
  inputSchema: z.object({
118
- title: z.string(),
119
- summary: z.string().describe("What the pull request changes."),
120
- draft: z.string().describe("The finding to post, one or two sentences."),
97
+ summary: z.string(),
98
+ draft: z.string().describe("The finding, in one or two sentences."),
121
99
  }),
122
- async execute({ title, summary, draft }, ctx) {
100
+ async execute({ summary, draft }, ctx) {
123
101
  if (ctx.session.purpose === "eval") {
124
102
  return { posted: false, reason: "eval" };
125
103
  }
@@ -130,12 +108,11 @@ export default defineTool({
130
108
  }
131
109
 
132
110
  const answers = await decide({
133
- state: { title, summary, draft },
111
+ state: { summary, draft },
134
112
  questions: {
135
113
  real: {
136
114
  type: "boolean",
137
- instructions:
138
- "Is the draft an exploitable bug in the new code, not a style note or a hypothetical?",
115
+ instructions: "Is the draft an exploitable bug in the new code?",
139
116
  },
140
117
  },
141
118
  });
@@ -152,19 +129,14 @@ export default defineTool({
152
129
  event: "COMMENT",
153
130
  body: draft,
154
131
  });
155
- return {
156
- posted: true,
157
- pr: `${ref.owner}/${ref.repo}#${ref.number}`,
158
- };
132
+ return { posted: true };
159
133
  },
160
134
  });
161
135
  ```
162
136
 
163
137
  ## Approve changes by risk tier
164
138
 
165
- You can use the same pattern for Agentic Owners. Ask Jev to put the
166
- pull request in a closed set of risk tiers. Approve only a confident
167
- `very-low` or `low`; send everything else to a person.
139
+ Ask Jev for one risk tier. Approve only a confident `very-low` or `low`.
168
140
 
169
141
  ```ts
170
142
  import { decide, needsHuman } from "@grok/agent-sdk/extensions/jev";
@@ -192,117 +164,38 @@ if (needsHuman(answers.risk) || tier === "medium" || tier === "high") {
192
164
  return { verdict: "approve", tier };
193
165
  ```
194
166
 
195
- Your GitHub tool resolves the pull request from `ctx.session` and posts
196
- that verdict. The model does not choose the repository, pull request, or
197
- approval event.
198
-
199
- ## Open documentation follow-ups selectively
200
-
201
- After a pull request merges, a code-wiki agent can ask whether the
202
- change introduced a durable fact that belongs in the docs. A low
203
- probability skips the follow-up, while a high probability opens a
204
- documentation pull request.
205
-
206
- ```ts
207
- import { above, decide } from "@grok/agent-sdk/extensions/jev";
208
- import { openDocsPullRequest } from "../lib/wiki";
209
-
210
- const answers = await decide({
211
- state: { title, summary },
212
- questions: {
213
- updateDocs: {
214
- type: "boolean",
215
- instructions:
216
- "Does this merge change a durable contract that the project docs should explain?",
217
- },
218
- },
219
- });
220
-
221
- if (!above(answers.updateDocs, 0.8)) {
222
- return { action: "skip" };
223
- }
224
- return openDocsPullRequest({ title, summary });
225
- ```
167
+ Your tool resolves the pull request from the session and posts that verdict, as the [Agentic Owners template](../templates/agentic-owners.md) does.
226
168
 
227
169
  ## Write tools with Jev
228
170
 
229
- Call `decide` from a channel hook, server tool, or router when you want
230
- the answer map directly. Use `evaluate` when you want `{ answers }`.
171
+ Call `decide` to get the answer map, or `evaluate` to get `{ answers }`. Use a
172
+ boolean for a yes-or-no gate, a choice for a closed set such as risk tiers, and
173
+ a score for an ordered rubric. `above` returns `true` when a probability or
174
+ score meets your threshold. `needsHuman` returns `true` when the answer's
175
+ confidence falls below `0.7` by default. Calibrate both on pull requests you've
176
+ already labeled.
231
177
 
232
- Use a boolean for a yes-or-no gate, a choice for a closed set such as
233
- risk tiers or owners, and a score for an ordered rubric. `above` returns
234
- `true` when a boolean probability or score meets the threshold.
235
- `needsHuman` returns `true` when a boolean probability or the selected
236
- choice's probability falls below the confidence threshold.
237
-
238
- Keep the questions atomic and combine them in TypeScript. For example,
239
- ask separately whether a finding is real, whether its impact is
240
- user-visible, and whether the changed line is new. Your code owns the
241
- rule that decides whether all three are enough to post.
178
+ Ask Jev one question per call, and write the rule that combines the answers in
179
+ your own code.
242
180
 
243
181
  ## Let the agent ask Jev
244
182
 
245
- Mounting the extension adds a read-only harness tool named
246
- `<namespace>__evaluate`. With the `bot/extensions/jev.ts` mount shown
247
- earlier, the model sees `jev__evaluate`.
248
-
249
- The tool accepts one state and a list of boolean, choice, or score
250
- questions. It returns `{ answers }` and never posts, approves, or opens
251
- a pull request. Use it when the agent needs the result during the turn.
252
- Use `decide` inside a project tool when the answer and the write belong
253
- in one operation.
254
-
255
- ## Skills included with the extension
256
-
257
- The extension adds two skills by default:
258
-
259
- - `jev__questions` teaches the model how to structure atomic questions,
260
- choose a question type, and read the answers.
261
-
262
- - `jev__gated-write` teaches the model to put `decide` and the write in
263
- one server tool, hold on low confidence, and skip writes during evals.
264
-
265
- The model sees each skill's description and loads the full procedure
266
- when it applies.
183
+ The mount also gives the model a read-only tool named `<namespace>__evaluate`,
184
+ which is `jev__evaluate` with the mount shown earlier. The model can call it
185
+ during a turn, and it never posts or approves anything. When the answer and the
186
+ write belong together, call `decide` inside a project tool instead.
267
187
 
268
188
  ## Choose what to mount
269
189
 
270
- Both contribution groups are on by default. Turn off the harness tool
271
- when Jev should only run inside tools you wrote. Turn off the skills
272
- when your agent already has its own Jev instructions.
190
+ Mounting Jev also adds two skills. `jev__questions` teaches the model to write
191
+ atomic questions and read the answers, and `jev__gated-write` teaches it to put
192
+ `decide` and the write in one server tool. Set `harnessTools: false` to keep Jev
193
+ inside your own tools, or `skills: false` if your agent has its own Jev
194
+ instructions.
273
195
 
274
196
  ```ts
275
- // bot/extensions/jev.ts
276
- import jev from "@grok/agent-sdk/extensions/jev";
277
-
278
- export default jev({
279
- harnessTools: false,
280
- skills: true,
281
- });
197
+ export default jev({ harnessTools: false, skills: true });
282
198
  ```
283
199
 
284
- `harnessTools: false` removes `jev__evaluate` from discovery.
285
- `skills: false` removes both Jev skills. These switches do not remove
286
- the exported helpers, so project tools can still import `decide`,
287
- `above`, and `needsHuman`.
288
-
289
- ## Practices
290
-
291
- - Pass the pull request title, a short summary, and the draft finding.
292
- Don't send the checkout.
293
-
294
- - Calibrate `above` and `needsHuman` on pull requests you have already
295
- labeled. `needsHuman` defaults to `0.7`.
296
-
297
- ## Related
298
-
299
- - [Agentic owners](../templates/agentic-owners.md): a risk tier, then
300
- the host approves or asks for reviewers
301
- - [Security reviewer](../templates/security-reviewer.md): a finding, or
302
- no comment
303
- - [Thermo review](../templates/thermo-review.md): bugs and breakage,
304
- posted the same way
305
- - [Code wiki](../reference/cli.md#init): documentation
306
- follow-ups after a merge
307
- - [Evals](../evals.md): checks on the full turn
308
- - [GitHub agents](./github.md): how the review gets onto the pull request
200
+ Neither switch removes the exported helpers, so project tools can still import
201
+ `decide`, `above`, and `needsHuman`.
@@ -5,16 +5,12 @@ description: "Authorize a private MCP server locally, constrain its tools, and c
5
5
 
6
6
  # Connect a private MCP server with OAuth
7
7
 
8
- Host MCP OAuth lets an Agent SDK process authorize a remote MCP server
9
- without putting tokens in the agent's source or workspace. Use it when
10
- the server speaks OAuth and its credentials should belong to the serve
11
- host instead of a person's Cursor account.
8
+ Host MCP OAuth lets the machine running your agent authorize a remote
9
+ MCP server without putting tokens in your source or workspace.
12
10
 
13
11
  ## Use a private MCP tool locally
14
12
 
15
- Declare the remote server, authorize it once in the browser, and start
16
- the agent. The next local turn can call the server's named tools with
17
- the credentials stored on that host.
13
+ Declare the server and authorize it once in the browser.
18
14
 
19
15
  ```ts
20
16
  // bot/mcp-connections/inventory.ts
@@ -27,47 +23,37 @@ export default defineConnection({
27
23
  });
28
24
  ```
29
25
 
30
- ```text
26
+ ```bash
31
27
  agent-sdk mcp oauth inventory
32
- agent-sdk run --dir . \
33
- --message "Which east-coast warehouse has SKU-142 in stock?"
34
28
  ```
35
29
 
36
- The filename is the connection name used by the CLI and
37
- `ctx.host.mcp`. Changing the server URL invalidates its saved
38
- authorization, so run `mcp oauth` again after moving the endpoint.
30
+ The filename is the connection name. If you change the server URL, run
31
+ `mcp oauth` again.
39
32
 
40
33
  ## Connect on first use
41
34
 
42
- You can also let the first unauthenticated call ask for authorization.
43
- The turn parks and the playground shows **Connect**. Finish the browser
44
- flow, return to the playground, and confirm **Connected**; the same call
45
- retries and the turn continues without restarting the agent.
46
-
47
- ```text
48
- agent-sdk serve --dir . --dev
49
- ```
50
-
51
- Connect authorizes the process that is running now.
35
+ Without a prior `mcp oauth`, the first call to the server pauses the
36
+ turn, and the playground shows **Connect**. Finish the browser flow,
37
+ and the call retries in the running process.
52
38
 
53
39
  A turn waits for Connect only when a person can click it:
54
40
 
55
41
  - A playground or HTTP chat turn.
56
- - A Slack message, when the channel shows Connect. `slackChannel({ toolApprovals: true })` shows
57
- Connect, and so does `buildToolApprovalEvents` in `events`.
42
+ - A Slack message, when the channel shows Connect through
43
+ `slackChannel({ toolApprovals: true })` or `buildToolApprovalEvents`
44
+ in `events`.
58
45
 
59
- The wait stops after 10 minutes, or when the turn is interrupted. Other
60
- turns do not wait. These are schedules, reminders, webhooks, evals, and
61
- Slack channels without Connect. A required connection fails the call with
62
- `Reconnect <connection>`. An `optional` connection is skipped, also in the
63
- playground. Authorize those connections ahead of time with `mcp oauth`.
46
+ The wait stops after 10 minutes or when the turn is interrupted.
47
+ Schedules, reminders, webhooks, evals, and Slack channels without
48
+ Connect don't wait. A required connection fails the call with
49
+ `Reconnect <connection>`, and an `optional` one is skipped, even in the
50
+ playground. Authorize those ahead of time with `mcp oauth`.
64
51
 
65
52
  ## Keep privileged tools behind a wrapper
66
53
 
67
- Put a connection under `bot/host-connections/` when the model should
68
- not receive the MCP server's tools directly. A server tool can expose
69
- one constrained operation while `ctx.host.mcp` keeps the broader server
70
- on the host.
54
+ The model never sees a connection under `bot/host-connections/`. A
55
+ server tool reaches it through `ctx.host.mcp` and exposes one narrow
56
+ operation.
71
57
 
72
58
  ```ts
73
59
  // bot/host-connections/inventory.ts
@@ -105,48 +91,28 @@ export default defineTool({
105
91
  });
106
92
  ```
107
93
 
108
- The model sees `get_stock`, not the unrestricted inventory server.
109
- Use this shape when code should own an allowlist or another side-effect
110
- gate.
111
-
112
94
  ## Use an OAuth server from a hosted agent
113
95
 
114
- Tokens from `mcp oauth` stay in the CLI config directory of the machine
115
- that authorized them, so a hosted deployment doesn't receive them. For a
116
- Cursor-managed agent, add the server under MCP in the Cursor dashboard,
96
+ Tokens from `mcp oauth` stay on the machine that authorized them. For a
97
+ Cursor-hosted agent, add the server under MCP in the Cursor dashboard,
117
98
  reach it through a
118
99
  [`cursorAccount: true` connection](../reference/connections.md#cursor-account-mcp-connection),
119
100
  and connect it from [Deployed Agents](https://cursor.com/dashboard/deployed-agents).
120
-
121
- Anyone able to use that agent can reach the MCP capabilities you
122
- expose, so narrow the connection's `servers` list and keep privileged
123
- operations behind a host-side wrapper.
101
+ Anyone who can use the agent can use that connection, so narrow its
102
+ `servers` list.
124
103
 
125
104
  ## Choose where credentials live
126
105
 
127
- Use the credential shape that matches who should own access:
128
-
129
- - Choose `cursorAccount: true` for connectors already authorized under
130
- MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.
131
-
132
- - Choose `url` with `oauth: true` when the machine running `agent-sdk serve`
133
- should hold OAuth credentials.
134
-
135
- - Choose `url` with static `headers` when the server uses an API key or
136
- bearer token instead of OAuth.
106
+ | Connection | Credentials live in | Use it when |
107
+ | --- | --- | --- |
108
+ | `cursorAccount: true` | Cursor's backend | You connected the server in the Cursor dashboard |
109
+ | `url` with `oauth: true` | The serve host | The serve host should own access |
110
+ | `url` with `headers` | Your secrets | The server takes an API key or bearer token |
137
111
 
138
- Host OAuth and per-session `auth` are different identity models and
139
- cannot be combined on one connection. Use per-session auth when each
140
- caller needs a different downstream identity.
112
+ Host OAuth can't share a connection with per-session `auth`, which
113
+ gives each caller its own downstream identity.
141
114
 
142
115
  ## Related
143
116
 
144
- - [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md): the
145
- companion setup procedure for coding agents
146
- - [MCP connections](../reference/connections.md): transports, account
147
- connectors, per-session auth, and tool filtering
148
- - [CLI reference](../reference/cli.md#mcp-oauth): OAuth command flags
149
- and browser callback behavior
150
- - [Deployment](../deployment.md): hosted egress and secrets
151
- - [Troubleshooting](../troubleshooting.md): authorization symptoms and
152
- remedies
117
+ - Follow the `bdk-mcp-auth` skill, then run `agent-sdk mcp oauth <connection>`.
118
+ - [MCP connections](../reference/connections.md)