@grok/agent-sdk 0.2.29 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (451) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  3. package/dist/channels/slack/slack-channel.js +27 -14
  4. package/dist/docs/404.html +2 -2
  5. package/dist/docs/assets/{app.DMrZKFjI.js → app.BSH__xV4.js} +4 -4
  6. package/dist/docs/assets/building-with-agents.md.Bo3ct-rf.js +6 -0
  7. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.Bo3ct-rf.lean.js} +1 -1
  8. package/dist/docs/assets/changelog.md.b6H_ea44.js +1 -0
  9. package/dist/docs/assets/changelog.md.b6H_ea44.lean.js +1 -0
  10. package/dist/docs/assets/chunks/@localSearchIndexroot.CiRGcfZg.js +1 -0
  11. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.Cadl7A0k.js} +1 -1
  12. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.K7t9nNY6.js} +1 -1
  13. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.SlHEknkX.js} +1 -1
  14. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.DJLRMLkz.js} +1 -1
  15. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.Bs6XxFpe.js} +1 -1
  16. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.CyLg6Ovc.js} +1 -1
  17. package/dist/docs/assets/chunks/channel.CVTdqYx0.js +1 -0
  18. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.DTQ4TinT.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.Es84IgcH.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.Clm3cGPQ.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DE4CRkS5.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.Bf8HCvqp.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.eub-7nSx.js} +1 -1
  24. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.WyP9VAS_.js} +1 -1
  25. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.LO9ohhDE.js} +1 -1
  26. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CsJJyx6-.js +1 -0
  27. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CsJJyx6-.js +1 -0
  28. package/dist/docs/assets/chunks/clone.Dk8KvtOB.js +1 -0
  29. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.D5za6aH0.js} +1 -1
  30. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.Dq1daUru.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.j1YL5BKS.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.Bi1aLdhC.js} +1 -1
  33. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.BOzMEkAr.js} +1 -1
  34. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.Dx2FVhCr.js} +1 -1
  35. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.DI4TNkye.js} +1 -1
  36. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.C58Z9uPK.js} +1 -1
  37. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.DXSpW809.js} +1 -1
  38. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B955oaFl.js} +1 -1
  39. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.BQXhKtxS.js} +1 -1
  40. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.Dozj_-Gm.js} +1 -1
  41. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D2140OzH.js} +1 -1
  42. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.DrqrMhCk.js} +1 -1
  43. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Dv-LTrlw.js} +1 -1
  44. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.CGtHp49X.js} +1 -1
  45. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.CHZLYB52.js} +1 -1
  46. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.D4Vt3eIy.js} +1 -1
  47. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BBfpYTea.js} +1 -1
  48. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.BVYvElmY.js} +1 -1
  49. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.C6Gc2mdY.js} +1 -1
  50. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.DWa8b4cn.js} +1 -1
  51. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.Bi-g4ajv.js} +1 -1
  52. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.DlU3vVN9.js} +1 -1
  53. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.CeqJRqnU.js} +1 -1
  54. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.DE0BnUZh.js +1 -0
  55. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DGq7D4tt.js} +2 -2
  56. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.Cqf2kjq9.js} +1 -1
  57. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.BeOpE_lM.js} +1 -1
  58. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.FMQXA-6q.js} +1 -1
  59. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.BXS65dAC.js} +1 -1
  60. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.haEiSxqc.js} +1 -1
  61. package/dist/docs/assets/deployment.md.DJtuDVLh.js +31 -0
  62. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.DJtuDVLh.lean.js} +1 -1
  63. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  64. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  65. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.DcB3nhOz.js} +8 -8
  66. package/dist/docs/assets/guides_agent-to-agent.md.DcB3nhOz.lean.js +1 -0
  67. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  68. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  69. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  70. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  71. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  72. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.CcuZ7keS.js} +11 -19
  74. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.CcuZ7keS.lean.js} +1 -1
  75. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  76. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  77. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  78. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  80. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  81. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.GVPMKcYl.js} +3 -5
  82. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.GVPMKcYl.lean.js} +1 -1
  83. package/dist/docs/assets/guides_migrate.md.B8CZxnnX.js +3 -0
  84. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.B8CZxnnX.lean.js} +1 -1
  85. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  86. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  87. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  88. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  89. package/dist/docs/assets/guides_slack.md.D7Rwyva4.js +82 -0
  90. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.D7Rwyva4.lean.js} +1 -1
  91. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  92. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  93. package/dist/docs/assets/hillclimbing.md.M51bF-oT.js +5 -0
  94. package/dist/docs/assets/hillclimbing.md.M51bF-oT.lean.js +1 -0
  95. package/dist/docs/assets/index.md.DnJPj_B6.js +14 -0
  96. package/dist/docs/assets/index.md.DnJPj_B6.lean.js +1 -0
  97. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  98. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  99. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  100. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  101. package/dist/docs/assets/reference_agent-config.md.BSNp2uJ7.js +27 -0
  102. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.BSNp2uJ7.lean.js} +1 -1
  103. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  104. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  105. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  106. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  107. package/dist/docs/assets/reference_cli.md.DHm6DmYk.js +83 -0
  108. package/dist/docs/assets/reference_cli.md.DHm6DmYk.lean.js +1 -0
  109. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  110. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  111. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  112. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  113. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  114. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  115. package/dist/docs/assets/reference_hooks.md.vbIM394-.js +39 -0
  116. package/dist/docs/assets/reference_hooks.md.vbIM394-.lean.js +1 -0
  117. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  118. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  119. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  120. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  121. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  122. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  123. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  124. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  125. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  126. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  127. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  128. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  129. package/dist/docs/assets/reference_schedules.md.Dd8_d0WG.js +45 -0
  130. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.Dd8_d0WG.lean.js} +1 -1
  131. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  132. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  133. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  134. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  135. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  136. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  137. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  138. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  139. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  140. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  141. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  142. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  143. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  144. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  145. package/dist/docs/building-with-agents.html +41 -44
  146. package/dist/docs/building-with-agents.md +11 -104
  147. package/dist/docs/changelog.html +37 -37
  148. package/dist/docs/changelog.md +14 -145
  149. package/dist/docs/deployment.html +54 -54
  150. package/dist/docs/deployment.md +97 -270
  151. package/dist/docs/evals.html +52 -71
  152. package/dist/docs/evals.md +33 -129
  153. package/dist/docs/guides/agent-to-agent.html +43 -43
  154. package/dist/docs/guides/agent-to-agent.md +29 -64
  155. package/dist/docs/guides/bitbucket.html +62 -62
  156. package/dist/docs/guides/bitbucket.md +73 -134
  157. package/dist/docs/guides/cloud-agents.html +37 -37
  158. package/dist/docs/guides/cloud-agents.md +23 -53
  159. package/dist/docs/guides/convert-automation.html +39 -56
  160. package/dist/docs/guides/convert-automation.md +31 -115
  161. package/dist/docs/guides/github.html +46 -54
  162. package/dist/docs/guides/github.md +49 -131
  163. package/dist/docs/guides/gitlab.html +98 -108
  164. package/dist/docs/guides/gitlab.md +104 -184
  165. package/dist/docs/guides/improve.html +38 -43
  166. package/dist/docs/guides/improve.md +24 -90
  167. package/dist/docs/guides/jev.html +55 -95
  168. package/dist/docs/guides/jev.md +53 -160
  169. package/dist/docs/guides/mcp-oauth.html +38 -40
  170. package/dist/docs/guides/mcp-oauth.md +33 -67
  171. package/dist/docs/guides/migrate.html +38 -43
  172. package/dist/docs/guides/migrate.md +56 -130
  173. package/dist/docs/guides/opentelemetry.html +41 -43
  174. package/dist/docs/guides/opentelemetry.md +32 -27
  175. package/dist/docs/guides/pagerduty.html +50 -49
  176. package/dist/docs/guides/pagerduty.md +65 -199
  177. package/dist/docs/guides/slack.html +51 -57
  178. package/dist/docs/guides/slack.md +76 -204
  179. package/dist/docs/guides/webhooks.html +42 -42
  180. package/dist/docs/guides/webhooks.md +64 -146
  181. package/dist/docs/hashmap.json +1 -1
  182. package/dist/docs/hillclimbing.html +40 -42
  183. package/dist/docs/hillclimbing.md +40 -102
  184. package/dist/docs/index.html +49 -61
  185. package/dist/docs/index.md +42 -82
  186. package/dist/docs/llms-full.txt +2272 -5711
  187. package/dist/docs/llms.txt +9 -14
  188. package/dist/docs/quickstart.html +95 -152
  189. package/dist/docs/quickstart.md +91 -180
  190. package/dist/docs/reference/access.html +36 -36
  191. package/dist/docs/reference/access.md +7 -12
  192. package/dist/docs/reference/agent-config.html +45 -58
  193. package/dist/docs/reference/agent-config.md +92 -176
  194. package/dist/docs/reference/artifacts.html +38 -39
  195. package/dist/docs/reference/artifacts.md +38 -62
  196. package/dist/docs/reference/channels.html +38 -39
  197. package/dist/docs/reference/channels.md +102 -151
  198. package/dist/docs/reference/cli.html +68 -84
  199. package/dist/docs/reference/cli.md +232 -697
  200. package/dist/docs/reference/connections.html +45 -57
  201. package/dist/docs/reference/connections.md +83 -164
  202. package/dist/docs/reference/evals.html +47 -54
  203. package/dist/docs/reference/evals.md +75 -141
  204. package/dist/docs/reference/extensions.html +41 -43
  205. package/dist/docs/reference/extensions.md +37 -70
  206. package/dist/docs/reference/hooks.html +40 -52
  207. package/dist/docs/reference/hooks.md +62 -133
  208. package/dist/docs/reference/http-api.html +38 -42
  209. package/dist/docs/reference/http-api.md +66 -118
  210. package/dist/docs/reference/instructions.html +39 -39
  211. package/dist/docs/reference/instructions.md +19 -29
  212. package/dist/docs/reference/limits.html +38 -38
  213. package/dist/docs/reference/limits.md +9 -21
  214. package/dist/docs/reference/memory.html +37 -38
  215. package/dist/docs/reference/memory.md +38 -75
  216. package/dist/docs/reference/playground.html +36 -36
  217. package/dist/docs/reference/playground.md +14 -22
  218. package/dist/docs/reference/project-layout.html +49 -48
  219. package/dist/docs/reference/project-layout.md +38 -84
  220. package/dist/docs/reference/schedules.html +44 -46
  221. package/dist/docs/reference/schedules.md +59 -90
  222. package/dist/docs/reference/sessions.html +37 -37
  223. package/dist/docs/reference/sessions.md +66 -113
  224. package/dist/docs/reference/skills.html +39 -39
  225. package/dist/docs/reference/skills.md +11 -31
  226. package/dist/docs/reference/subagents.html +37 -37
  227. package/dist/docs/reference/subagents.md +17 -31
  228. package/dist/docs/reference/tools.html +47 -64
  229. package/dist/docs/reference/tools.md +48 -130
  230. package/dist/docs/templates/agentic-owners.html +38 -38
  231. package/dist/docs/templates/agentic-owners.md +50 -74
  232. package/dist/docs/templates/reviews.html +69 -0
  233. package/dist/docs/templates/reviews.md +71 -0
  234. package/dist/docs/troubleshooting.html +38 -36
  235. package/dist/docs/troubleshooting.md +48 -101
  236. package/dist/filesystem.d.ts +7 -320
  237. package/dist/filesystem.d.ts.map +1 -1
  238. package/dist/filesystem.js +10 -691
  239. package/dist/index.d.ts +1 -1
  240. package/dist/index.d.ts.map +1 -1
  241. package/dist/index.js +1 -1
  242. package/dist/internal/authored-alias-hooks.d.ts +6 -0
  243. package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
  244. package/dist/internal/authored-alias-hooks.js +12 -0
  245. package/dist/internal/authored-loaders.js +10 -1
  246. package/dist/internal/cli/commands/scaffold.js +1 -1
  247. package/dist/internal/cli-deploy.js +1 -1
  248. package/dist/internal/cli-docs.js +1 -1
  249. package/dist/internal/cli-images.js +1 -1
  250. package/dist/internal/cli-skills.js +1 -1
  251. package/dist/internal/continuation-session-ids.d.ts +15 -0
  252. package/dist/internal/continuation-session-ids.d.ts.map +1 -0
  253. package/dist/internal/continuation-session-ids.js +43 -0
  254. package/dist/internal/cursor/credentials.js +1 -1
  255. package/dist/internal/deploy-manifest.d.ts +1 -0
  256. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  257. package/dist/internal/deploy-manifest.js +0 -1
  258. package/dist/internal/discovery/agent-config.d.ts +2 -6
  259. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  260. package/dist/internal/discovery/agent-config.js +8 -25
  261. package/dist/internal/discovery/agent.d.ts.map +1 -1
  262. package/dist/internal/discovery/agent.js +2 -3
  263. package/dist/internal/discovery/project.d.ts.map +1 -1
  264. package/dist/internal/discovery/project.js +15 -0
  265. package/dist/internal/filesystem/walk.d.ts +1 -5
  266. package/dist/internal/filesystem/walk.d.ts.map +1 -1
  267. package/dist/internal/filesystem/walk.js +1 -9
  268. package/dist/internal/hosted-catch-protocol.d.ts +3 -3
  269. package/dist/internal/hosted-catch-protocol.js +3 -3
  270. package/dist/internal/hosted-fetch.d.ts +7 -0
  271. package/dist/internal/hosted-fetch.d.ts.map +1 -0
  272. package/dist/internal/hosted-fetch.js +26 -0
  273. package/dist/internal/init-project.d.ts.map +1 -1
  274. package/dist/internal/init-project.js +7 -5
  275. package/dist/internal/install-cursor-skills.d.ts +5 -6
  276. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  277. package/dist/internal/install-cursor-skills.js +19 -4
  278. package/dist/internal/mcp-endpoint.js +4 -4
  279. package/dist/internal/model-config.d.ts.map +1 -1
  280. package/dist/internal/model-config.js +11 -4
  281. package/dist/internal/platform-timers.d.ts +3 -7
  282. package/dist/internal/platform-timers.d.ts.map +1 -1
  283. package/dist/internal/platform-timers.js +10 -51
  284. package/dist/internal/reminder-runner.js +1 -1
  285. package/dist/internal/server.d.ts.map +1 -1
  286. package/dist/internal/server.js +6 -1
  287. package/dist/internal/session-engine.d.ts +3 -0
  288. package/dist/internal/session-engine.d.ts.map +1 -1
  289. package/dist/internal/session-engine.js +13 -4
  290. package/dist/internal/shallow-clone.js +1 -1
  291. package/dist/playground/assets/index-Bno25Cg0.css +1 -0
  292. package/dist/playground/assets/index-SGKsaznh.js +62 -0
  293. package/dist/playground/index.html +2 -2
  294. package/dist/types.d.ts +6 -17
  295. package/dist/types.d.ts.map +1 -1
  296. package/dist/types.js +2 -2
  297. package/docs/README.md +42 -82
  298. package/docs/building-with-agents.md +11 -104
  299. package/docs/changelog.md +15 -146
  300. package/docs/deployment.md +97 -270
  301. package/docs/evals.md +34 -130
  302. package/docs/guides/agent-to-agent.md +29 -64
  303. package/docs/guides/bitbucket.md +73 -134
  304. package/docs/guides/cloud-agents.md +23 -53
  305. package/docs/guides/convert-automation.md +31 -115
  306. package/docs/guides/github.md +49 -131
  307. package/docs/guides/gitlab.md +104 -184
  308. package/docs/guides/improve.md +24 -90
  309. package/docs/guides/jev.md +53 -160
  310. package/docs/guides/mcp-oauth.md +33 -67
  311. package/docs/guides/migrate.md +56 -130
  312. package/docs/guides/opentelemetry.md +37 -27
  313. package/docs/guides/pagerduty.md +68 -200
  314. package/docs/guides/slack.md +76 -204
  315. package/docs/guides/webhooks.md +64 -146
  316. package/docs/hillclimbing.md +41 -103
  317. package/docs/quickstart.md +91 -180
  318. package/docs/reference/access.md +7 -12
  319. package/docs/reference/agent-config.md +92 -176
  320. package/docs/reference/artifacts.md +38 -62
  321. package/docs/reference/channels.md +102 -151
  322. package/docs/reference/cli.md +232 -697
  323. package/docs/reference/connections.md +83 -164
  324. package/docs/reference/evals.md +75 -141
  325. package/docs/reference/extensions.md +37 -70
  326. package/docs/reference/hooks.md +61 -132
  327. package/docs/reference/http-api.md +66 -118
  328. package/docs/reference/instructions.md +20 -30
  329. package/docs/reference/limits.md +10 -22
  330. package/docs/reference/memory.md +38 -75
  331. package/docs/reference/playground.md +14 -22
  332. package/docs/reference/project-layout.md +38 -84
  333. package/docs/reference/schedules.md +59 -90
  334. package/docs/reference/sessions.md +66 -113
  335. package/docs/reference/skills.md +12 -32
  336. package/docs/reference/subagents.md +17 -31
  337. package/docs/reference/tools.md +48 -130
  338. package/docs/templates/agentic-owners.md +50 -74
  339. package/docs/templates/reviews.md +76 -0
  340. package/docs/troubleshooting.md +48 -101
  341. package/package.json +4 -4
  342. package/skills/cli/SKILL.md +1 -1
  343. package/skills/create-agent/SKILL.md +61 -7
  344. package/skills/debug/SKILL.md +1 -1
  345. package/skills/deploy/SKILL.md +3 -3
  346. package/skills/evals/SKILL.md +1 -1
  347. package/skills/framework-map/SKILL.md +2 -2
  348. package/skills/github/SKILL.md +1 -1
  349. package/skills/hillclimb/SKILL.md +1 -1
  350. package/skills/mcp-auth/SKILL.md +1 -1
  351. package/skills/migrate-v2/SKILL.md +2 -3
  352. package/skills/otel/SKILL.md +1 -1
  353. package/skills/setup-slack/SKILL.md +2 -2
  354. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  355. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  356. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  357. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  358. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  359. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  360. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  361. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  362. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  363. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  364. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  365. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  366. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  367. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  368. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  369. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  370. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  371. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  372. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  373. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  374. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  375. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  376. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  377. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  378. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  379. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  380. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  381. package/dist/docs/assets/index.md.CAruw_rp.lean.js +0 -1
  382. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  383. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  384. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  385. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  386. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  387. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  388. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  389. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  390. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  391. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  392. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  393. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  394. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  395. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  396. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  397. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  398. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  399. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  400. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  401. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  402. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  403. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  404. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  405. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  406. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  407. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  408. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  409. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  410. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  411. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  412. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  413. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  414. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  415. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  416. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  417. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  418. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  419. package/dist/docs/guides/hooks.html +0 -113
  420. package/dist/docs/guides/hooks.md +0 -116
  421. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  422. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  423. package/dist/docs/package/skills/github/SKILL.md +0 -133
  424. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  425. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  426. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  427. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  428. package/dist/docs/reference/prompt.html +0 -68
  429. package/dist/docs/reference/prompt.md +0 -47
  430. package/dist/docs/templates/security-reviewer.html +0 -62
  431. package/dist/docs/templates/security-reviewer.md +0 -81
  432. package/dist/docs/templates/thermo-quality-review.html +0 -62
  433. package/dist/docs/templates/thermo-quality-review.md +0 -75
  434. package/dist/docs/templates/thermo-review.html +0 -62
  435. package/dist/docs/templates/thermo-review.md +0 -75
  436. package/dist/docs/templates/triage.html +0 -68
  437. package/dist/docs/templates/triage.md +0 -101
  438. package/dist/internal/filesystem/errors.d.ts +0 -64
  439. package/dist/internal/filesystem/errors.d.ts.map +0 -1
  440. package/dist/internal/filesystem/errors.js +0 -180
  441. package/dist/internal/filesystem/merge.d.ts +0 -34
  442. package/dist/internal/filesystem/merge.d.ts.map +0 -1
  443. package/dist/internal/filesystem/merge.js +0 -154
  444. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  445. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  446. package/docs/guides/hooks.md +0 -121
  447. package/docs/reference/prompt.md +0 -52
  448. package/docs/templates/security-reviewer.md +0 -86
  449. package/docs/templates/thermo-quality-review.md +0 -80
  450. package/docs/templates/thermo-review.md +0 -80
  451. package/docs/templates/triage.md +0 -106
@@ -5,46 +5,30 @@ description: "Define typed actions the model can call, control their dry-run eff
5
5
 
6
6
  # Tools
7
7
 
8
- A tool is a typed action the model can call: hit an API, run a query,
9
- write a file. Each file in `bot/tools/` defines one tool, and the
10
- filename becomes the tool name the model sees. Tools come in two
11
- execution flavors: server tools run on the serving host, and
12
- agent tools run as scripts where the agent runs. Every server tool can
13
- also be called directly, with no model turn.
8
+ A tool is a typed action the model can call, such as hitting an API, running a query, or writing a file. Each file in `bot/tools/` defines one tool, and the filename is the name the model sees. Server tools run on the serving host, and agent tools run as scripts next to the agent.
14
9
 
15
10
  ## Define a server tool
16
11
 
17
12
  By default, `execute` runs in-process on the serving host with full
18
- access to `process.env` and your `bot/lib/` code.
13
+ access to `process.env` and your `bot/lib/` code. `execution: "server"`
14
+ is the default.
19
15
 
20
- ```ts
21
- // bot/tools/inspect_pr.ts
22
- import { defineTool } from "@grok/agent-sdk/tools";
23
- import { z } from "zod";
24
-
25
- export default defineTool({
26
- description: "Inspect a pull request before approval.",
27
- // execution: "server" is the default
28
- inputSchema: z.object({ prUrl: z.string().url() }),
29
- async execute({ prUrl }, ctx) {
30
- return { prUrl, checks: ["unit", "lint"], ready: true };
31
- },
32
- });
33
- ```
16
+ A tool needs a filename slug (the model-facing name), a `description`
17
+ written for the model, an optional `inputSchema`, and the code that
18
+ runs it. With a Zod schema, Agent SDK validates the input and infers its type. With plain JSON Schema, `execute` gets raw JSON.
34
19
 
35
- A tool definition needs a filename slug (the model-facing name), a
36
- `description` written for the model, an optional `inputSchema`, and the
37
- code that runs it. With a Zod `inputSchema`, the input is validated before
38
- `execute` runs and the input type is inferred. A plain JSON Schema
39
- object is forwarded as-is and the input arrives as raw JSON.
20
+ `prompt` from `@grok/agent-sdk` or `@grok/agent-sdk/prompt` dedents a
21
+ template literal so a multi-line description, reminder, or error can
22
+ sit indented in TypeScript. Blank lines and relative indentation stay.
23
+ `prompt.lines` returns the same text as `string[]`, one entry per line.
40
24
 
41
- A server tool can call `decide` from
42
- [`@grok/agent-sdk/extensions/jev`](../guides/jev.md) for a risk tier or a
43
- finding gate without a second model turn.
25
+ ```ts
26
+ context: prompt.lines`
27
+ Merged PR detected: ${pr.url} by ${author}.
44
28
 
45
- For multi-line descriptions, reminder prompts, and error messages, use
46
- [`prompt`](./prompt.md) so the string can sit indented with the surrounding
47
- TypeScript:
29
+ Call plan_deploy, then follow its nextStep.
30
+ `
31
+ ```
48
32
 
49
33
  ```ts
50
34
  import { prompt } from "@grok/agent-sdk";
@@ -71,7 +55,7 @@ export default defineTool({
71
55
  | --- | --- |
72
56
  | `ctx.toolCallId` | The call id, matching the `actions.requested` / `action.result` stream events |
73
57
  | `ctx.session` | Read-only session info: id, channel, mode, auth |
74
- | `ctx.approvedBy` | For a `needsApproval` tool, the auth of whoever approved this call, in the same shape as `ctx.session.auth`. On Slack, `attributes.user_id` is the person who clicked Approve, who can differ from the person who started the thread. Unset when the call needed no approval |
58
+ | `ctx.approvedBy` | Auth of whoever approved a `needsApproval` call, same shape as `ctx.session.auth`. On Slack, `attributes.user_id` is the person who clicked Approve. Unset when the call needed no approval |
75
59
  | `ctx.workspaceDir` | The session's workspace directory |
76
60
  | `ctx.stateRoot` | The agent's durable state root, shared across every session |
77
61
  | `ctx.host` | Shared host services (see below) |
@@ -79,24 +63,12 @@ export default defineTool({
79
63
  | `ctx.getSession(channelId, sessionId)` | Look up a session on a channel |
80
64
  | `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
81
65
 
82
- `ctx.host` carries the shared host services: `host.mcp` (authored MCP
83
- connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
84
- `host.github` and `host.slack` (shared platform clients), `host.kv` and
85
- `host.files` (durable storage), and `host.reminders` (per-session wakes,
86
- when attached). Custom metrics use the
87
- [OpenTelemetry](../guides/opentelemetry.md) API.
66
+ `ctx.host` has `mcp`, `github`, `slack`, `kv`, `files`, and `reminders`.
67
+ Custom metrics use the [OpenTelemetry](../guides/opentelemetry.md) API.
88
68
 
89
69
  ### Return values
90
70
 
91
- `execute` may return a string (passed to the model verbatim), a
92
- JSON-shaped value (serialized), or the envelope
93
- `{ content: [...], isError? }` for rich results. Returns must be
94
- JSON-shaped: use object literals or `type` aliases. An `interface` type
95
- fails assignability (no index signature), and tsx won't catch it. Your
96
- typecheck will.
97
-
98
- Throwing inside `execute` reports an error result to the model
99
- (`isError: true`). The turn and the server keep running.
71
+ `execute` may return a string, a JSON-shaped value, or `{ content: [...], isError? }`. Use object literals or `type` aliases, since an `interface` return fails typecheck with no index signature. If `execute` throws, the model gets the error and the turn keeps going.
100
72
 
101
73
  ### Declare structured output
102
74
 
@@ -119,21 +91,17 @@ export default defineTool({
119
91
  });
120
92
  ```
121
93
 
122
- Agent SDK advertises the schema. It does not validate tool results against
123
- it. Plain object returns fill MCP `structuredContent` automatically. An
124
- envelope return must set `structuredContent` next to `content` and `isError`.
125
-
126
- Use the exported `ToolInput<TSchema>` type when another function needs the
127
- input type inferred from a tool schema.
94
+ Agent SDK advertises the schema and does not validate results against it.
95
+ A plain object fills MCP `structuredContent`. An envelope must set
96
+ `structuredContent` next to `content` and `isError`.
128
97
 
129
98
  ### Control dry-run effects
130
99
 
131
100
  Set `effect` to `"read"`, `"write"`, `"idempotent"`, or a predicate over
132
- validated input. A dry-run session executes reads and answers writes and
133
- idempotent calls without running their tool bodies. An authored tool
134
- without `effect` is treated as a write. `"idempotent"` may change
135
- something outside the session, and repeating the same arguments has no
136
- additional effect. It is not a read.
101
+ the validated input. A dry-run session runs reads and stubs writes and
102
+ idempotent calls. A tool with no `effect` is a write. `"idempotent"` can
103
+ change something outside the session, and repeating the same arguments
104
+ has no further effect.
137
105
 
138
106
  ```ts
139
107
  export default defineTool({
@@ -147,35 +115,23 @@ export default defineTool({
147
115
  });
148
116
  ```
149
117
 
150
- `dryRunResult` keeps the result shape stable. Without it, a stubbed write
151
- returns `"Operation acknowledged."`. Traces mark the result as stubbed.
118
+ Set `dryRunResult` so a stubbed write returns the real shape. Without it, the write returns "Operation acknowledged." Traces mark the result as stubbed.
152
119
 
153
120
  ### Retry a transient read or idempotent call
154
121
 
155
- When a read or an idempotent call fails because the service or the network
156
- was briefly unavailable, Agent SDK runs that same call again before the model
157
- sees the error. A write, and a tool that does not declare an effect, runs
158
- once. An advertised MCP tool is retried when its annotations classify as
159
- a read, or as idempotent. `idempotentHint: true` with `destructiveHint`
160
- explicitly true or explicitly false is idempotent. The two hints are
161
- orthogonal: a destructive call can still be safe to repeat. A bare
162
- `idempotentHint`, a destructive hint without `idempotentHint`, and
163
- `destructiveHint: false` without `idempotentHint` are not eligible.
164
- `idempotent` is not a read and is not a non-destructive claim. Declaring
165
- `effect: "read"` or `effect: "idempotent"` opts the call into the default
166
- policy of 3 attempts.
167
-
168
- If the call still fails, the tool error is the last attempt's message,
169
- unchanged.
122
+ If a read or an idempotent call fails with a transient error, Agent SDK
123
+ tries it up to 3 times before the model sees the error. It runs writes,
124
+ and tools that don't declare an effect, only once. Agent SDK retries an
125
+ MCP tool when the tool's annotations mark it read-only, or when the tool
126
+ sets `idempotentHint: true` together with an explicit `destructiveHint`.
127
+ If the call still fails, the tool error is the last attempt's message.
170
128
 
171
129
  ### Bound time arguments under `asOf`
172
130
 
173
- Declare `timeArgs` with the input properties that carry time bounds. In a
174
- session created with `asOf`, every named argument must be an absolute
175
- ISO-8601 instant with a timezone, no later than the session's frozen
176
- instant. A call that omits one, or supplies a relative or later value, is
177
- refused with an error telling the model to retry with absolute bounds.
178
- Sessions without `asOf` ignore the declaration.
131
+ `timeArgs` names the input fields that carry time bounds. In a session
132
+ created with `asOf`, each named argument must be an absolute ISO-8601
133
+ instant with a timezone, no later than that frozen instant. A missing,
134
+ relative, or later value is refused. Sessions without `asOf` ignore it.
179
135
 
180
136
  ```ts
181
137
  export default defineTool({
@@ -189,35 +145,28 @@ export default defineTool({
189
145
  });
190
146
  ```
191
147
 
192
- Every name in `timeArgs` must exist in the input schema; a session with
193
- `asOf` refuses to start otherwise, because a misspelled name would silently
194
- check nothing.
148
+ Every name in `timeArgs` must exist in the input schema. A session with
149
+ `asOf` refuses to start otherwise, because a misspelled name would check
150
+ nothing.
195
151
 
196
152
  ## Define an agent tool
197
153
 
198
- Set `execution: "agent"` and the tool materializes as a shell script
199
- that runs in the Cursor agent workspace. The script receives JSON
200
- arguments on stdin and prints its
201
- result on stdout. Use this flavor when the tool must run next to the
202
- checkout the agent works in.
154
+ Set `execution: "agent"` when the tool must run next to the checkout.
155
+ The script receives JSON on stdin and prints its result on stdout.
203
156
 
204
157
  ```ts
205
- import { defineTool } from "@grok/agent-sdk/tools";
206
- import { z } from "zod";
207
-
208
158
  export default defineTool({
209
159
  description: "Echo a message from the agent workspace.",
210
160
  execution: "agent",
211
161
  inputSchema: z.object({ message: z.string() }),
212
162
  script: `#!/usr/bin/env bash
213
163
  set -euo pipefail
214
- message=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])')
215
- printf '%s\\n' "$message"
164
+ python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])'
216
165
  `,
217
166
  });
218
167
  ```
219
168
 
220
- Scripts land in the session workspace with a catalog in `AGENTS.md`.
169
+ Agent SDK copies the scripts into the workspace and lists them in the system prompt.
221
170
 
222
171
  ## Tools from an MCP connection, advertised by name
223
172
 
@@ -230,9 +179,7 @@ contract.
230
179
 
231
180
  ## Call a tool without a model turn
232
181
 
233
- Server tools can be called deterministically. You pick the tool and the
234
- input. Validation and execution match a model-initiated call, and no
235
- Cursor API key is needed.
182
+ You can call any server tool yourself, with your own input and no model turn. Validation and execution match a model-initiated call, and no Cursor API key is needed.
236
183
 
237
184
  Over HTTP, with the same auth chain as the session API:
238
185
 
@@ -244,15 +191,11 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
244
191
  # "isError":false,"result":{…},"durationMs":12}
245
192
  ```
246
193
 
247
- From the CLI, which starts an ephemeral server unless `--url` targets
248
- a running one:
194
+ From the CLI. Without `--url`, this starts an ephemeral server:
249
195
 
250
196
  ```text
251
197
  agent-sdk tool call inspect_pr --dir . \
252
198
  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
253
- agent-sdk tool call inspect_pr \
254
- --url http://127.0.0.1:3000/<slug> \
255
- --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
256
199
  ```
257
200
 
258
201
  Programmatically, `callTool(toolName, input, options?)` is available on
@@ -264,9 +207,6 @@ model turns:
264
207
  const outcome = await handle.callTool("inspect_pr", {
265
208
  prUrl: "https://github.com/acme/checkout/pull/42",
266
209
  });
267
- if (outcome.isError) {
268
- return outcome;
269
- }
270
210
  // { toolName, callId, isError, result, durationMs }
271
211
  ```
272
212
 
@@ -296,26 +236,4 @@ exclusive.
296
236
  | `500 workspace_unavailable` | Write-effect call when the session workspace cannot be created |
297
237
  | `isError: true` | The tool body threw; same envelope the model would see |
298
238
 
299
- ## Design habits
300
-
301
- Keep one decision per tool. Small tools with crisp descriptions beat
302
- multi-purpose tools with mode flags. The model chooses better and evals
303
- gate cleaner.
304
-
305
- Put deterministic policy in tool code, not model judgment. A PR-approval
306
- tool should re-read the live PR inside the tool before acting, so a
307
- spoofed payload can't steer it.
308
-
309
- Test tools with `tool call` before blaming prompts. If the tool's output is
310
- wrong, no instruction change fixes it.
311
-
312
- Declare each tool's `effect` so dry-run sessions can execute reads and
313
- stub writes.
314
-
315
- ## Related
316
-
317
- - [MCP connections](./connections.md): tools that come from MCP servers
318
- instead
319
- - [Extensions](./extensions.md): tools installed as a package under a
320
- namespace
321
- - [Evals](../evals.md): gating tool decisions with `calledTool`
239
+ See also [MCP connections](./connections.md), [Extensions](./extensions.md), and [Evals](../evals.md).
@@ -5,26 +5,19 @@ description: "Scaffold the agent, commit .agentic-owners policies, and let it ri
5
5
 
6
6
  # Review pull requests with owners policies
7
7
 
8
- This agent reviews every pull request in your repository. It risk-tiers
9
- the diff, requests the owning team or user as reviewers, and approves
10
- what your policy allows. Ownership rules live in
11
- `.agentic-owners/policy.yml` files committed at any depth of the repo.
12
- The closest policy to a changed file wins, and policies are always read
13
- from the PR's base ref, so a PR cannot exempt itself.
8
+ This agent risk-tiers every pull request in your repository, requests
9
+ the owners as reviewers, and approves what your policy allows. Rules
10
+ live in `.agentic-owners/policy.yml` files at any depth. The closest policy to a changed file wins. The agent reads
11
+ policies from the PR's base ref, so a PR can't exempt itself.
14
12
 
15
- ## Scaffold
13
+ ## Scaffold and run
16
14
 
17
15
  ```bash
18
16
  agent-sdk init ./owners-agent --template agentic-owners
19
17
  ```
20
18
 
21
- `init` writes the project, installs dependencies, and puts `agent-sdk`
22
- on PATH.
23
-
24
- ## Log in and run
25
-
26
19
  Set your repositories in `bot/lib/config.ts` (`repos: ["acme/api"]`),
27
- then:
20
+ then run:
28
21
 
29
22
  ```bash
30
23
  cd owners-agent
@@ -32,11 +25,10 @@ agent-sdk login
32
25
  agent-sdk dev
33
26
  ```
34
27
 
35
- PR events stream through your Cursor account. No webhook or GitHub App
36
- setup. The agent reviews a PR when it is opened, reopened, pushed to,
37
- marked ready for review, or retargeted to another base. Draft PRs wait
38
- until they are ready. Open a PR, or replay a real one (this also works
39
- with `repos` empty):
28
+ PR events stream through your Cursor account, so you don't need a
29
+ webhook or GitHub App. The agent reviews a PR when it's opened,
30
+ reopened, pushed to, marked ready for review, or retargeted, and skips
31
+ drafts. Open a PR or replay a real one:
40
32
 
41
33
  ```bash
42
34
  agent-sdk github replay https://github.com/acme/api/pull/123 --dir .
@@ -46,9 +38,9 @@ Deploy with `agent-sdk deploy`.
46
38
 
47
39
  ## Policies
48
40
 
49
- With no policy files, every PR gets a default risk review: very-low and
50
- low risk approve, medium and above hold with a comment. Route reviews by
51
- committing policies:
41
+ With no policy files, the agent approves very-low and low risk PRs and
42
+ holds medium and above with a comment. Commit policies to route
43
+ reviews:
52
44
 
53
45
  ```yaml
54
46
  # .agentic-owners/policy.yml at any depth; the closest policy wins.
@@ -64,68 +56,52 @@ policies:
64
56
  mode: hard # the agent never approves; a person must
65
57
  ```
66
58
 
67
- `paths` are globs relative to the directory that holds the
68
- `.agentic-owners/` folder, so a root policy sees repo-relative paths and
69
- `src/.agentic-owners/policy.yml` matches `api/**` against
70
- `src/api/**`. Leading `../` segments reach a sibling tree. A path cannot
71
- escape the repo.
59
+ `paths` are relative to the policy's parent directory, so
60
+ `src/.agentic-owners/policy.yml` matches `api/**` against `src/api/**`.
61
+ A leading `../` reaches a sibling tree inside the repo.
72
62
 
73
63
  | Key | Meaning |
74
64
  | --- | --- |
75
- | `paths` | Globs relative to the policy's directory. Required. |
76
- | `team` / `teams` | Owner teams. A bare slug resolves in the repo's org. An `org/team` handle names a team directly. |
77
- | `user` / `users` | Owner GitHub logins, without `@`. |
78
- | `prompt` | Markdown filename in the same directory, added to the rubric for matching PRs. |
79
- | `mode` | `advisory` (default): low risk approves. `hard`: a person must approve. `notify`: the rule never blocks and its owners are not requested. |
80
- | `human_review_required` | `true` is the older spelling of `mode: hard`. |
81
- | `self_review` | A listed `user:` owner's own PRs clear this rule. |
82
- | `always_approve` | Satisfied at every risk tier. Cannot combine with owners, `prompt`, `mode`, `self_review`, or `human_review_required`. |
83
-
84
- A rule without owners must set `always_approve: true`.
85
- `global_exclusions` in the root policy opts paths out entirely. The
86
- agent rejects `delegated_automations`: nothing in this template consumes
87
- automation approvals.
65
+ | `paths` | Required globs |
66
+ | `team`, `teams` | Owner teams, as a slug in the repo's org or an `org/team` handle |
67
+ | `user`, `users` | Owner GitHub logins, without `@` |
68
+ | `prompt` | Extra rubric file beside the policy |
69
+ | `mode` | `advisory`, the default, approves low risk. `hard` requires a person to approve. `notify` never blocks and doesn't request its owners |
70
+ | `human_review_required` | `true` is the older spelling of `mode: hard` |
71
+ | `self_review` | A listed `user:` owner's own PRs clear this rule |
72
+ | `always_approve` | Satisfied at every risk tier. Allows no other key except `paths` |
73
+
74
+ - A rule without owners must set `always_approve: true`.
75
+ - `global_exclusions` in the root policy opts paths out entirely.
76
+ - The template rejects `delegated_automations`.
88
77
 
89
78
  ## What one review does
90
79
 
91
- One model turn per PR head assesses the host-fetched diff against the
92
- base rubric plus any matched rule prompts, then records a risk tier of
93
- `very_low`, `low`, `medium`, `medium_high`, or `high` with
94
- `record_review`. The host recomputes the policy from trusted state and
95
- applies the deterministic decision:
96
-
97
- - **Approve** when every matched rule is `always_approve` or `notify`,
98
- or when the tier is very low or low and every matched `hard` rule is
99
- cleared by an owner-author with `self_review`. At medium and above,
100
- the agent approves only when the author's `self_review` covers every
101
- rule that can require review.
102
- - **Request reviewers** otherwise: the policy owners (max 2, never the
103
- author), plus one status comment the agent keeps updated in place.
104
-
105
- An approval binds to the head SHA, and a later hold dismisses the
106
- agent's earlier approvals. The agent also holds when the PR edits
107
- `.agentic-owners/` or `CODEOWNERS`, when the diff is empty or truncated,
108
- or when GitHub capped the changed-file list. `self_review` never clears
109
- a governance edit.
110
-
111
- The model never writes to GitHub. A broken policy file fails closed with
112
- a comment listing the validation issues. Team membership is not
113
- resolved, because repo-scoped credentials cannot read org teams, so
114
- `self_review` applies to `user:` owners only.
80
+ - One model turn per PR head grades the diff against the base rubric
81
+ and matched rule prompts, then calls `record_review` with `very_low`,
82
+ `low`, `medium`, `medium_high`, or `high`. The model never writes to
83
+ GitHub.
84
+ - The host recomputes the policy from trusted state. It approves when
85
+ every matched rule is `always_approve` or `notify`. Otherwise it
86
+ approves only when the author's `self_review` clears every matched
87
+ `hard` rule at very low or low risk, or every rule that can require
88
+ review at medium and above.
89
+ - When the agent holds, it requests up to two owners, never the author,
90
+ and updates one status comment in place.
91
+ - An approval binds to the head SHA. A later hold dismisses the agent's
92
+ earlier approvals.
93
+ - The agent holds when the PR edits `.agentic-owners/` or `CODEOWNERS`,
94
+ or when the diff is empty or GitHub truncated the diff or file list.
95
+ `self_review` never clears a governance edit.
96
+ - A broken policy file fails closed and comments with the validation
97
+ issues.
115
98
 
116
99
  ## Rubric
117
100
 
118
- Edit `bot/lib/owners/prompts/base-review.md` for the risk tiers and
119
- their boundaries. Per-area guidance belongs in policy `prompt:` files
120
- next to the policy that names them. The next review reads both.
101
+ Edit `bot/lib/owners/prompts/base-review.md` to change the risk tiers.
102
+ Put per-area guidance in policy `prompt:` files.
121
103
 
122
104
  ## Evals
123
105
 
124
- Use the three smoke reviews as a local exercise:
125
-
126
- ```bash
127
- agent-sdk eval
128
- ```
129
-
130
- The cases are a docs-only change, an auth deletion, and a prompt
131
- injection. Eval sessions skip GitHub writes.
106
+ `agent-sdk eval` runs three smoke reviews without writing to GitHub.
107
+ They cover a docs-only change, an auth deletion, and a prompt injection.
@@ -0,0 +1,76 @@
1
+ ---
2
+ title: "Review and triage templates"
3
+ description: "Scaffold a pull request reviewer or an issue triager, try it locally, and deploy it."
4
+ ---
5
+
6
+ # Review and triage templates
7
+
8
+ Each template is one model turn. A review template reads the diff and posts one comment, and the triage template comments on a ticket you already filed.
9
+
10
+ | Template | `--template` id | What it posts | Channel |
11
+ | --- | --- | --- | --- |
12
+ | Security reviewer | `security-reviewer` | One comment on exploitable bugs, such as injection, authz bypass, secret leaks, SSRF, and RCE | GitHub |
13
+ | Thermo review | `thermo-review` | One comment on bugs, breaking side effects, and unintended feature exposure | GitHub |
14
+ | Thermo quality review | `thermo-quality-review` | One comment on structure, such as missing abstractions, deep nesting, and files past 1,000 lines | GitHub |
15
+ | Triage | `triage-linear`, `triage-jira`, or `triage` | A `Triage:` comment, a bug priority, and a duplicate link when titles match | Linear or Jira |
16
+
17
+ `triage` is short for `triage-linear`. No review template comments on style, and the quality template doesn't argue about behavior.
18
+
19
+ The [Agentic Approver](./agentic-owners.md) template is separate. It applies an owners policy instead of posting one findings comment.
20
+
21
+ ## Scaffold
22
+
23
+ ```text
24
+ agent-sdk init ./security-reviewer --template security-reviewer \
25
+ --var repos=acme/api
26
+ ```
27
+
28
+ Swap the folder and the `--template` id for the row you want. `--var repos` is only for `security-reviewer`. Name repositories already connected in Cursor, separated by commas, and they must share one owner. `init` writes that list to `bot/lib/repos.ts`.
29
+
30
+ ## Try it locally
31
+
32
+ Connect GitHub in Cursor for the repositories you watch (Settings or [cursor.com/dashboard](https://cursor.com/dashboard)), then sign the host in with `agent-sdk login`. The [GitHub guide](../guides/github.md) covers `cursorAccount`.
33
+
34
+ ```text
35
+ agent-sdk dev --cursor-events --repo acme/api
36
+ agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
37
+ ```
38
+
39
+ You need pull access to replay. The channel skips drafts, writes the diff to `pr/diff.patch`, and starts a turn. The model calls `post_findings` once, and that call writes the GitHub comment. Chat replies stay in the playground.
40
+
41
+ ```text
42
+ agent-sdk eval
43
+ ```
44
+
45
+ Eval sessions skip the GitHub write. Edit `bot/instructions.md` for what counts as a finding, and edit `evals/review.eval.ts` for the smoke cases.
46
+
47
+ ## Deploy
48
+
49
+ From the agent's git checkout:
50
+
51
+ ```text
52
+ agent-sdk login
53
+ agent-sdk deploy --cursor-events-repo acme/api
54
+ ```
55
+
56
+ Repeat `--cursor-events-repo` for each repository, and every repository must share one owner. The deployment watches those repositories through your team's Cursor GitHub connection, and you can change the list later without a redeploy:
57
+
58
+ ```text
59
+ agent-sdk deployment update my-agent --event-repo acme/api --event-repo acme/web
60
+ ```
61
+
62
+ ## Triage a tracker
63
+
64
+ The template runs after someone files a ticket, so keep filing them as you do now. Connect Linear or Jira under MCP in the Cursor dashboard, then run `agent-sdk dev` and open `/queue/issue` in the playground.
65
+
66
+ ```bash
67
+ curl -X POST http://127.0.0.1:3000/triage-agent/v1/channels/queue/issue \
68
+ -H 'content-type: application/json' \
69
+ -d '{
70
+ "identifier": "ENG-142",
71
+ "title": "CSV export returns 500",
72
+ "description": "Export has returned 500 since this morning."
73
+ }'
74
+ ```
75
+
76
+ For create webhooks, set `LINEAR_WEBHOOK_SECRET` or `JIRA_WEBHOOK_SECRET` and point the provider at `/v1/channels/webhook` on the deployed alias. `record_triage` comments on the issue that started the session. Edit `bot/skills/triage-rubric.md` for kinds and what `urgent` means on your team. Eval sessions skip tracker writes.