@grok/agent-sdk 0.2.28 → 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 (528) hide show
  1. package/AGENTS.md +29 -29
  2. package/dist/bin/agent-serve.d.ts +2 -2
  3. package/dist/bin/agent-serve.js +3 -3
  4. package/dist/channels/pagerduty/api.js +1 -1
  5. package/dist/channels/pagerduty/pagerduty-channel.d.ts +1 -1
  6. package/dist/channels/pagerduty/pagerduty-channel.d.ts.map +1 -1
  7. package/dist/channels/pagerduty/pagerduty-channel.js +1 -1
  8. package/dist/channels/pagerduty/replay.d.ts +1 -1
  9. package/dist/channels/pagerduty/replay.js +4 -4
  10. package/dist/channels/slack/cli-project.js +1 -1
  11. package/dist/docs/404.html +2 -2
  12. package/dist/docs/assets/{app.DF9vlcdn.js → app.BzTUBOAD.js} +4 -4
  13. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  14. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  15. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  16. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  17. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  18. package/dist/docs/assets/chunks/{VPLocalSearchBox.D8OuwKO0.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  19. package/dist/docs/assets/chunks/{arc.DCq_TCYV.js → arc.DH8GOhiv.js} +1 -1
  20. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.PWRNTPbk.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  21. package/dist/docs/assets/chunks/{baseUniq.BeRPvRUL.js → baseUniq.BXHpx1lE.js} +1 -1
  22. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.BuRmZVSo.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  23. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.7DKSMwuv.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  24. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  25. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.7VrO9-9i.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  26. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.CHystNE2.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  27. package/dist/docs/assets/chunks/{chunk-55IACEB6.Nuh9TbTq.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  28. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CA0EKugm.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  29. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.F9_mp7U8.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  30. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CEU4QfE1.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  31. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.B8h_x9_i.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  32. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.Btfb-rKg.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  33. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  34. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  35. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  36. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.DKvc96Wa.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  37. package/dist/docs/assets/chunks/{dagre-KV5264BT.CMo0cy1b.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  38. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.DDgMOQhB.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  39. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.BdJnoIsU.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  40. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.oSvhAZaL.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  41. package/dist/docs/assets/chunks/{diagram-TYMM5635.C9zZLIE-.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  42. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.BNhVyccy.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  43. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BEFLLBiU.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  44. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.BdUzXBgY.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  45. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.Rd3LlOIJ.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  46. package/dist/docs/assets/chunks/{graph.DnJC1GpG.js → graph.DgJ4L-8V.js} +1 -1
  47. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.xv0xntDJ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  48. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.BaGIlviU.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  49. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.Cof_h0fp.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  50. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.C5GozFuU.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  51. package/dist/docs/assets/chunks/{layout.zc9UShLc.js → layout.DXXqX4MQ.js} +1 -1
  52. package/dist/docs/assets/chunks/{linear.BoqrFVcJ.js → linear.5c61gNw4.js} +1 -1
  53. package/dist/docs/assets/chunks/{min.DwIfr8hG.js → min.B1-NAjHX.js} +1 -1
  54. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.Dkq2yTtp.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  55. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.B4CpTmHK.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  56. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.BqXnFC9C.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  57. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.DhIN2z-E.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  58. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BhxUAmg2.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  59. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.BqgU7HU-.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  60. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.B1BCO18N.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  61. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  62. package/dist/docs/assets/chunks/{theme.oV7rddEz.js → theme.DMj_7q3B.js} +2 -2
  63. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.oRI8UwMC.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  64. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.DmuWrIxN.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  65. package/dist/docs/assets/chunks/{wardley-RL74JXVD.CEBjM5ov.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  66. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.m5zsCOF9.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  67. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.cPN-587n.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  68. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  69. package/dist/docs/assets/{deployment.md.DDmjAVbg.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  70. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  71. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  72. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  73. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  74. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  75. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  76. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  77. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  78. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  79. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  80. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  81. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  82. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  83. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  84. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  85. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  86. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.js → guides_jev.md.DGCzkMUN.js} +20 -60
  87. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  88. package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  89. package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  90. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  91. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  92. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  93. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  94. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  95. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  96. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  97. package/dist/docs/assets/{guides_slack.md.BqiGSYGX.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  98. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  99. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  100. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  101. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  102. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  103. package/dist/docs/assets/index.md.DRfaoRCZ.lean.js +1 -0
  104. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  105. package/dist/docs/assets/{quickstart.md.DaLk4ZIF.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  106. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  107. package/dist/docs/assets/{reference_access.md.CExlH_mR.lean.js → reference_access.md.C5lblfUC.lean.js} +1 -1
  108. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  109. package/dist/docs/assets/{reference_agent-config.md.11E_xe--.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  110. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  111. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  112. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  113. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  114. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  115. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  116. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  117. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  118. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  119. package/dist/docs/assets/{reference_evals.md.DYKjGFi-.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  120. package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  121. package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  122. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  123. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  124. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  125. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  126. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  127. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  128. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  129. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  130. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  131. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  132. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  133. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  134. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  135. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  136. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  137. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  138. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  139. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  140. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  141. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  142. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  143. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  144. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  145. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  146. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  147. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  148. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  149. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  150. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  151. package/dist/docs/assets/{troubleshooting.md.AGJ3jDzj.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  152. package/dist/docs/building-with-agents.html +41 -44
  153. package/dist/docs/building-with-agents.md +11 -104
  154. package/dist/docs/changelog.html +37 -37
  155. package/dist/docs/changelog.md +5 -145
  156. package/dist/docs/deployment.html +54 -54
  157. package/dist/docs/deployment.md +86 -265
  158. package/dist/docs/evals.html +52 -71
  159. package/dist/docs/evals.md +33 -127
  160. package/dist/docs/guides/agent-to-agent.html +43 -43
  161. package/dist/docs/guides/agent-to-agent.md +27 -64
  162. package/dist/docs/guides/bitbucket.html +62 -62
  163. package/dist/docs/guides/bitbucket.md +73 -134
  164. package/dist/docs/guides/cloud-agents.html +37 -37
  165. package/dist/docs/guides/cloud-agents.md +23 -53
  166. package/dist/docs/guides/convert-automation.html +39 -56
  167. package/dist/docs/guides/convert-automation.md +31 -115
  168. package/dist/docs/guides/github.html +46 -54
  169. package/dist/docs/guides/github.md +49 -131
  170. package/dist/docs/guides/gitlab.html +98 -108
  171. package/dist/docs/guides/gitlab.md +104 -184
  172. package/dist/docs/guides/improve.html +38 -43
  173. package/dist/docs/guides/improve.md +24 -90
  174. package/dist/docs/guides/jev.html +55 -95
  175. package/dist/docs/guides/jev.md +57 -159
  176. package/dist/docs/guides/mcp-oauth.html +38 -40
  177. package/dist/docs/guides/mcp-oauth.md +34 -69
  178. package/dist/docs/guides/migrate.html +38 -43
  179. package/dist/docs/guides/migrate.md +56 -130
  180. package/dist/docs/guides/opentelemetry.html +41 -43
  181. package/dist/docs/guides/opentelemetry.md +32 -27
  182. package/dist/docs/guides/pagerduty.html +50 -49
  183. package/dist/docs/guides/pagerduty.md +65 -199
  184. package/dist/docs/guides/slack.html +51 -57
  185. package/dist/docs/guides/slack.md +76 -205
  186. package/dist/docs/guides/webhooks.html +42 -42
  187. package/dist/docs/guides/webhooks.md +64 -146
  188. package/dist/docs/hashmap.json +1 -1
  189. package/dist/docs/hillclimbing.html +40 -42
  190. package/dist/docs/hillclimbing.md +40 -102
  191. package/dist/docs/index.html +55 -62
  192. package/dist/docs/index.md +49 -82
  193. package/dist/docs/llms-full.txt +2292 -5830
  194. package/dist/docs/llms.txt +9 -15
  195. package/dist/docs/quickstart.html +96 -153
  196. package/dist/docs/quickstart.md +93 -178
  197. package/dist/docs/reference/access.html +36 -36
  198. package/dist/docs/reference/access.md +7 -12
  199. package/dist/docs/reference/agent-config.html +43 -56
  200. package/dist/docs/reference/agent-config.md +93 -176
  201. package/dist/docs/reference/artifacts.html +38 -39
  202. package/dist/docs/reference/artifacts.md +38 -62
  203. package/dist/docs/reference/channels.html +38 -39
  204. package/dist/docs/reference/channels.md +102 -151
  205. package/dist/docs/reference/cli.html +68 -84
  206. package/dist/docs/reference/cli.md +233 -698
  207. package/dist/docs/reference/connections.html +45 -57
  208. package/dist/docs/reference/connections.md +83 -164
  209. package/dist/docs/reference/evals.html +66 -53
  210. package/dist/docs/reference/evals.md +97 -128
  211. package/dist/docs/reference/extensions.html +41 -43
  212. package/dist/docs/reference/extensions.md +37 -70
  213. package/dist/docs/reference/hooks.html +40 -52
  214. package/dist/docs/reference/hooks.md +62 -133
  215. package/dist/docs/reference/http-api.html +38 -42
  216. package/dist/docs/reference/http-api.md +66 -118
  217. package/dist/docs/reference/instructions.html +39 -39
  218. package/dist/docs/reference/instructions.md +19 -29
  219. package/dist/docs/reference/limits.html +38 -38
  220. package/dist/docs/reference/limits.md +9 -21
  221. package/dist/docs/reference/memory.html +37 -38
  222. package/dist/docs/reference/memory.md +38 -75
  223. package/dist/docs/reference/playground.html +36 -36
  224. package/dist/docs/reference/playground.md +14 -22
  225. package/dist/docs/reference/project-layout.html +49 -48
  226. package/dist/docs/reference/project-layout.md +38 -84
  227. package/dist/docs/reference/schedules.html +46 -48
  228. package/dist/docs/reference/schedules.md +59 -90
  229. package/dist/docs/reference/sessions.html +37 -37
  230. package/dist/docs/reference/sessions.md +66 -113
  231. package/dist/docs/reference/skills.html +39 -39
  232. package/dist/docs/reference/skills.md +11 -31
  233. package/dist/docs/reference/subagents.html +37 -37
  234. package/dist/docs/reference/subagents.md +17 -31
  235. package/dist/docs/reference/tools.html +47 -64
  236. package/dist/docs/reference/tools.md +48 -130
  237. package/dist/docs/templates/agentic-owners.html +38 -38
  238. package/dist/docs/templates/agentic-owners.md +50 -74
  239. package/dist/docs/templates/reviews.html +69 -0
  240. package/dist/docs/templates/reviews.md +71 -0
  241. package/dist/docs/troubleshooting.html +38 -36
  242. package/dist/docs/troubleshooting.md +48 -101
  243. package/dist/evals.d.ts +2 -2
  244. package/dist/extensions/jev/extension.d.ts +12 -2
  245. package/dist/extensions/jev/extension.d.ts.map +1 -1
  246. package/dist/extensions/jev/extension.js +4 -0
  247. package/dist/extensions/jev/lib/evaluate.d.ts +31 -4
  248. package/dist/extensions/jev/lib/evaluate.d.ts.map +1 -1
  249. package/dist/extensions/jev/lib/evaluate.js +18 -4
  250. package/dist/internal/cli/command.d.ts +1 -1
  251. package/dist/internal/cli/command.js +1 -1
  252. package/dist/internal/cli/commands/channels.js +6 -6
  253. package/dist/internal/cli/commands/develop.d.ts.map +1 -1
  254. package/dist/internal/cli/commands/develop.js +23 -14
  255. package/dist/internal/cli/commands/hosted.js +4 -4
  256. package/dist/internal/cli/commands/index.d.ts +1 -1
  257. package/dist/internal/cli/commands/index.d.ts.map +1 -1
  258. package/dist/internal/cli/commands/index.js +1 -1
  259. package/dist/internal/cli/commands/mcp.js +1 -1
  260. package/dist/internal/cli/commands/project.js +4 -4
  261. package/dist/internal/cli/commands/scaffold.d.ts.map +1 -1
  262. package/dist/internal/cli/commands/scaffold.js +9 -6
  263. package/dist/internal/cli/commands/serve.d.ts +1 -1
  264. package/dist/internal/cli/commands/serve.js +5 -5
  265. package/dist/internal/cli/commands/session.d.ts.map +1 -1
  266. package/dist/internal/cli/commands/session.js +12 -7
  267. package/dist/internal/cli/dispatch.d.ts +3 -3
  268. package/dist/internal/cli/dispatch.js +3 -3
  269. package/dist/internal/cli/errors.d.ts +1 -1
  270. package/dist/internal/cli/errors.d.ts.map +1 -1
  271. package/dist/internal/cli/errors.js +1 -1
  272. package/dist/internal/cli/flags.d.ts +2 -2
  273. package/dist/internal/cli/flags.d.ts.map +1 -1
  274. package/dist/internal/cli/flags.js +2 -2
  275. package/dist/internal/cli/help-command.d.ts +1 -1
  276. package/dist/internal/cli/help-command.js +2 -2
  277. package/dist/internal/cli/help.d.ts +7 -7
  278. package/dist/internal/cli/help.d.ts.map +1 -1
  279. package/dist/internal/cli/help.js +8 -8
  280. package/dist/internal/cli-ax.d.ts.map +1 -1
  281. package/dist/internal/cli-ax.js +3 -0
  282. package/dist/internal/cli-convert-automation.d.ts +1 -1
  283. package/dist/internal/cli-convert-automation.js +1 -1
  284. package/dist/internal/cli-deploy.js +1 -1
  285. package/dist/internal/cli-docs.js +1 -1
  286. package/dist/internal/cli-images.js +1 -1
  287. package/dist/internal/cli-migrate.d.ts +1 -1
  288. package/dist/internal/cli-migrate.js +1 -1
  289. package/dist/internal/cli-pagerduty.d.ts +1 -1
  290. package/dist/internal/cli-pagerduty.js +1 -1
  291. package/dist/internal/cli-skills.js +1 -1
  292. package/dist/internal/convert-automation/types.d.ts +1 -1
  293. package/dist/internal/convert-automation/types.js +1 -1
  294. package/dist/internal/cursor/credentials.js +1 -1
  295. package/dist/internal/deploy-client.d.ts +2 -2
  296. package/dist/internal/deploy-client.d.ts.map +1 -1
  297. package/dist/internal/deploy-manifest.d.ts +1 -0
  298. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  299. package/dist/internal/deploy-manifest.js +0 -1
  300. package/dist/internal/discovery/agent-config.d.ts +2 -6
  301. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  302. package/dist/internal/discovery/agent-config.js +8 -25
  303. package/dist/internal/discovery/agent.d.ts.map +1 -1
  304. package/dist/internal/discovery/agent.js +2 -3
  305. package/dist/internal/discovery/project.d.ts.map +1 -1
  306. package/dist/internal/discovery/project.js +15 -0
  307. package/dist/internal/init-project.d.ts +7 -3
  308. package/dist/internal/init-project.d.ts.map +1 -1
  309. package/dist/internal/init-project.js +60 -12
  310. package/dist/internal/init-scaffold.d.ts +2 -1
  311. package/dist/internal/init-scaffold.d.ts.map +1 -1
  312. package/dist/internal/init-scaffold.js +20 -7
  313. package/dist/internal/peer-connections.js +1 -1
  314. package/dist/internal/reminder-runner.js +1 -1
  315. package/dist/internal/server.d.ts +1 -1
  316. package/dist/internal/session-cost.d.ts +4 -4
  317. package/dist/internal/session-cost.d.ts.map +1 -1
  318. package/dist/internal/session-cost.js +4 -4
  319. package/dist/internal/session-engine.d.ts +1 -1
  320. package/dist/internal/session-engine.js +2 -2
  321. package/dist/internal/shallow-clone.js +1 -1
  322. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  323. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  324. package/dist/playground/index.html +2 -2
  325. package/dist/types.d.ts +9 -22
  326. package/dist/types.d.ts.map +1 -1
  327. package/docs/README.md +49 -82
  328. package/docs/building-with-agents.md +11 -104
  329. package/docs/changelog.md +6 -146
  330. package/docs/deployment.md +86 -265
  331. package/docs/evals.md +34 -128
  332. package/docs/guides/agent-to-agent.md +27 -64
  333. package/docs/guides/bitbucket.md +73 -134
  334. package/docs/guides/cloud-agents.md +23 -53
  335. package/docs/guides/convert-automation.md +31 -115
  336. package/docs/guides/github.md +49 -131
  337. package/docs/guides/gitlab.md +104 -184
  338. package/docs/guides/improve.md +24 -90
  339. package/docs/guides/jev.md +57 -159
  340. package/docs/guides/mcp-oauth.md +34 -69
  341. package/docs/guides/migrate.md +56 -130
  342. package/docs/guides/opentelemetry.md +37 -27
  343. package/docs/guides/pagerduty.md +68 -200
  344. package/docs/guides/slack.md +76 -205
  345. package/docs/guides/webhooks.md +64 -146
  346. package/docs/hillclimbing.md +41 -103
  347. package/docs/quickstart.md +93 -178
  348. package/docs/reference/access.md +7 -12
  349. package/docs/reference/agent-config.md +93 -176
  350. package/docs/reference/artifacts.md +38 -62
  351. package/docs/reference/channels.md +102 -151
  352. package/docs/reference/cli.md +233 -698
  353. package/docs/reference/connections.md +83 -164
  354. package/docs/reference/evals.md +97 -128
  355. package/docs/reference/extensions.md +37 -70
  356. package/docs/reference/hooks.md +61 -132
  357. package/docs/reference/http-api.md +66 -118
  358. package/docs/reference/instructions.md +20 -30
  359. package/docs/reference/limits.md +10 -22
  360. package/docs/reference/memory.md +38 -75
  361. package/docs/reference/playground.md +14 -22
  362. package/docs/reference/project-layout.md +38 -84
  363. package/docs/reference/schedules.md +59 -90
  364. package/docs/reference/sessions.md +66 -113
  365. package/docs/reference/skills.md +12 -32
  366. package/docs/reference/subagents.md +17 -31
  367. package/docs/reference/tools.md +48 -130
  368. package/docs/templates/agentic-owners.md +50 -74
  369. package/docs/templates/reviews.md +76 -0
  370. package/docs/troubleshooting.md +48 -101
  371. package/package.json +3 -9
  372. package/skills/cli/SKILL.md +15 -15
  373. package/skills/create-agent/SKILL.md +20 -19
  374. package/skills/debug/SKILL.md +4 -4
  375. package/skills/deploy/SKILL.md +2 -2
  376. package/skills/evals/SKILL.md +8 -8
  377. package/skills/framework-map/SKILL.md +3 -3
  378. package/skills/github/SKILL.md +7 -7
  379. package/skills/hillclimb/SKILL.md +4 -4
  380. package/skills/mcp-auth/SKILL.md +3 -3
  381. package/skills/migrate-v2/SKILL.md +40 -41
  382. package/skills/otel/SKILL.md +2 -2
  383. package/skills/setup-slack/SKILL.md +8 -8
  384. package/templates/agentic-owners/README.md +5 -5
  385. package/templates/agentic-owners/bot/tools/record_review.ts +1 -1
  386. package/templates/agentic-owners/package.json +1 -1
  387. package/templates/agents-md/README.md +4 -4
  388. package/templates/agents-md/package.json +1 -1
  389. package/templates/code-wiki/README.md +3 -3
  390. package/templates/code-wiki/package.json +1 -1
  391. package/templates/demo/README.md +3 -3
  392. package/templates/demo/package.json +1 -1
  393. package/templates/pr-autofixer/package.json +1 -1
  394. package/templates/security-help/README.md +5 -5
  395. package/templates/security-help/package.json +1 -1
  396. package/templates/security-reviewer/README.md +3 -3
  397. package/templates/security-reviewer/package.json +1 -1
  398. package/templates/thermo-quality-review/README.md +4 -4
  399. package/templates/thermo-quality-review/package.json +1 -1
  400. package/templates/thermo-review/README.md +4 -4
  401. package/templates/thermo-review/package.json +1 -1
  402. package/templates/triage/README.md +3 -3
  403. package/templates/triage/overlays/jira/README.md +3 -3
  404. package/templates/triage/overlays/linear/README.md +3 -3
  405. package/templates/triage/package.json +1 -1
  406. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  407. package/dist/docs/assets/changelog.md.fZ-NNFeJ.js +0 -1
  408. package/dist/docs/assets/changelog.md.fZ-NNFeJ.lean.js +0 -1
  409. package/dist/docs/assets/chunks/@localSearchIndexroot.mfzjiOsL.js +0 -1
  410. package/dist/docs/assets/chunks/channel.goFR5lbe.js +0 -1
  411. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.B2yLtFja.js +0 -1
  412. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.B2yLtFja.js +0 -1
  413. package/dist/docs/assets/chunks/clone.CztV97Wu.js +0 -1
  414. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CZlVHdDZ.js +0 -1
  415. package/dist/docs/assets/deployment.md.DDmjAVbg.js +0 -31
  416. package/dist/docs/assets/evals.md.OjKb7tNA.js +0 -68
  417. package/dist/docs/assets/evals.md.OjKb7tNA.lean.js +0 -1
  418. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  419. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  420. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  421. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.js +0 -15
  422. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.lean.js +0 -1
  423. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  424. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  425. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  426. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  427. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  428. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  429. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  430. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  431. package/dist/docs/assets/guides_slack.md.BqiGSYGX.js +0 -88
  432. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  433. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  434. package/dist/docs/assets/index.md.CVRjO09Y.js +0 -27
  435. package/dist/docs/assets/index.md.CVRjO09Y.lean.js +0 -1
  436. package/dist/docs/assets/quickstart.md.DaLk4ZIF.js +0 -170
  437. package/dist/docs/assets/reference_access.md.CExlH_mR.js +0 -1
  438. package/dist/docs/assets/reference_agent-config.md.11E_xe--.js +0 -40
  439. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  440. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  441. package/dist/docs/assets/reference_cli.md.DQ3dCgmk.js +0 -99
  442. package/dist/docs/assets/reference_cli.md.DQ3dCgmk.lean.js +0 -1
  443. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  444. package/dist/docs/assets/reference_evals.md.DYKjGFi-.js +0 -56
  445. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  446. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  447. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  448. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  449. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  450. package/dist/docs/assets/reference_limits.md.Da1HegjB.js +0 -8
  451. package/dist/docs/assets/reference_limits.md.Da1HegjB.lean.js +0 -1
  452. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  453. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  454. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  455. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  456. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  457. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  458. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  459. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  460. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  461. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  462. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  463. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  464. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  465. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  466. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  467. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  468. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  469. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  470. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  471. package/dist/docs/assets/troubleshooting.md.AGJ3jDzj.js +0 -1
  472. package/dist/docs/guides/grokbot-agents.html +0 -74
  473. package/dist/docs/guides/grokbot-agents.md +0 -129
  474. package/dist/docs/guides/hooks.html +0 -113
  475. package/dist/docs/guides/hooks.md +0 -116
  476. package/dist/docs/reference/prompt.html +0 -68
  477. package/dist/docs/reference/prompt.md +0 -47
  478. package/dist/docs/templates/security-reviewer.html +0 -62
  479. package/dist/docs/templates/security-reviewer.md +0 -81
  480. package/dist/docs/templates/thermo-quality-review.html +0 -62
  481. package/dist/docs/templates/thermo-quality-review.md +0 -75
  482. package/dist/docs/templates/thermo-review.html +0 -62
  483. package/dist/docs/templates/thermo-review.md +0 -75
  484. package/dist/docs/templates/triage.html +0 -68
  485. package/dist/docs/templates/triage.md +0 -101
  486. package/dist/extensions/cursor-grokbot-agents/extension.d.ts +0 -71
  487. package/dist/extensions/cursor-grokbot-agents/extension.d.ts.map +0 -1
  488. package/dist/extensions/cursor-grokbot-agents/extension.js +0 -64
  489. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts +0 -11
  490. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts.map +0 -1
  491. package/dist/extensions/cursor-grokbot-agents/lib/agents.js +0 -31
  492. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts +0 -56
  493. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts.map +0 -1
  494. package/dist/extensions/cursor-grokbot-agents/lib/backend.js +0 -139
  495. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts +0 -28
  496. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts.map +0 -1
  497. package/dist/extensions/cursor-grokbot-agents/lib/contacts.js +0 -46
  498. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts +0 -53
  499. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts.map +0 -1
  500. package/dist/extensions/cursor-grokbot-agents/lib/conversation.js +0 -186
  501. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts +0 -4
  502. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts.map +0 -1
  503. package/dist/extensions/cursor-grokbot-agents/lib/inputs.js +0 -15
  504. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts +0 -12
  505. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts.map +0 -1
  506. package/dist/extensions/cursor-grokbot-agents/lib/lock.js +0 -24
  507. package/dist/extensions/cursor-grokbot-agents/skills/consult.md +0 -40
  508. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts +0 -4
  509. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts.map +0 -1
  510. package/dist/extensions/cursor-grokbot-agents/tools/ask.js +0 -26
  511. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts +0 -4
  512. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts.map +0 -1
  513. package/dist/extensions/cursor-grokbot-agents/tools/check.js +0 -21
  514. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts +0 -4
  515. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts.map +0 -1
  516. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.js +0 -13
  517. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts +0 -4
  518. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts.map +0 -1
  519. package/dist/extensions/cursor-grokbot-agents/tools/list.js +0 -22
  520. package/dist/playground/assets/index-BMpVzZzC.css +0 -1
  521. package/dist/playground/assets/index-_3zz3yh8.js +0 -62
  522. package/docs/guides/grokbot-agents.md +0 -134
  523. package/docs/guides/hooks.md +0 -121
  524. package/docs/reference/prompt.md +0 -52
  525. package/docs/templates/security-reviewer.md +0 -86
  526. package/docs/templates/thermo-quality-review.md +0 -80
  527. package/docs/templates/thermo-review.md +0 -80
  528. package/docs/templates/triage.md +0 -106
@@ -1,30 +1,19 @@
1
1
  ---
2
2
  title: "Hooks"
3
- description: "Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."
3
+ description: "Run code after session events for audit logs, metrics, and transcript mirrors."
4
4
  ---
5
5
 
6
6
  # Hooks
7
7
 
8
- A hook subscribes to selected session events and can run a side effect
9
- after each matching event is recorded: an audit line, a metric, a
10
- transcript copy, or derived state. Hooks run in the serving process for
11
- every session of the agent. They cannot change the turn, the prompt, or
12
- the reply; a handler that throws is logged and skipped.
8
+ A hook subscribes to selected session events and can run a side effect after each matching event is recorded. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply. A handler that throws is logged and skipped.
13
9
 
14
- Treat the event as read-only. Later subscribers see the same object.
15
- That makes hooks safe to add to a production agent, and the wrong
16
- surface for anything that must run before the model or must fail a
17
- turn; see [Hook boundaries](#hook-boundaries).
10
+ Treat the event as read-only. Later subscribers see the same object. A hook is the wrong surface for anything that must run before the model or must fail a turn. See [Hook boundaries](#hook-boundaries).
18
11
 
19
- `defineHook` is unrelated to
20
- [Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the
21
- `.cursor/hooks.json` scripts that can observe, block, or modify the
22
- agent loop. Those still run inside a local session workspace.
12
+ `defineHook` is unrelated to [Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the `.cursor/hooks.json` scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.
23
13
 
24
14
  ## Author a hook
25
15
 
26
- Author `bot/hooks/<name>.ts` with `defineHook` from
27
- `@grok/agent-sdk/hooks`. This one meters tokens:
16
+ Author `bot/hooks/<name>.ts` with `defineHook` from `@grok/agent-sdk/hooks`. This hook meters tokens and pages on failure:
28
17
 
29
18
  ```ts
30
19
  // bot/hooks/usage.ts
@@ -33,7 +22,6 @@ import { defineHook } from "@grok/agent-sdk/hooks";
33
22
 
34
23
  const meter = metrics.getMeter("acme");
35
24
  const inputTokens = meter.createCounter("acme.tokens.input");
36
- const outputTokens = meter.createCounter("acme.tokens.output");
37
25
  const turnFailed = meter.createCounter("acme.turn.failed");
38
26
 
39
27
  export default defineHook({
@@ -42,90 +30,8 @@ export default defineHook({
42
30
  if (ctx.session.purpose === "eval" || event.data.usage === undefined) {
43
31
  return;
44
32
  }
45
- const usage = event.data.usage;
46
- inputTokens.add(usage.inputTokens);
47
- outputTokens.add(usage.outputTokens);
33
+ inputTokens.add(event.data.usage.inputTokens);
48
34
  },
49
- async "turn.failed"(_event, ctx) {
50
- turnFailed.add(1, { channel: ctx.channel.id });
51
- },
52
- },
53
- });
54
- ```
55
-
56
- Any module under `bot/hooks/`, subfolders included, is a hook named by
57
- its path without the extension: `bot/hooks/audit/usage.ts` is
58
- `audit/usage`. `*.test.ts` and `*.spec.ts` files are skipped. The
59
- default export must be `defineHook(...)`, names can't contain `__`, and
60
- an empty `events` map skips the hook with a warning; `agent-sdk validate`
61
- reports all three. An extension mounts its hooks as `<ns>__<name>`, and
62
- `disableHook()` removes one
63
- ([Adjust a mounted extension](./extensions.md#adjust-a-mounted-extension)).
64
-
65
- `agent-sdk init` scaffolds `bot/hooks/memory.ts`, which exports
66
- `memoryHook()` from `@grok/agent-sdk/memory` and journals every turn for
67
- later sessions to read. Delete the file to opt out. See
68
- [Memory](./memory.md).
69
-
70
- ## Events and payloads
71
-
72
- Keys are event types from the
73
- [event vocabulary](./sessions.md#stream-events), or `"*"`
74
- for every event. A typed key narrows `event.data`; a `"*"` handler
75
- receives the union, so switch on `event.type`. Every event carries the
76
- stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
77
- `turnId` set on turn-scoped events. Skip `*.appended` deltas when you
78
- want the final text; `message.completed` already has it.
79
-
80
- | Event | `event.data` |
81
- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82
- | `message.received` | `{ text }` |
83
- | `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
84
- | `turn.failed` | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present |
85
- | `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. One envelope per model step once that step has listed its tools. A single tool is a batch of one. `parentCallId` marks subagent work |
86
- | `actions.completed` | `{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }`. Pair with `actions.requested`; emitted when every call in that batch has a result |
87
- | `action.result` | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. Live per-call envelope for chips and spans. `stubbed` means a dry-run session answered a write without running it |
88
- | `action.tool_retry` | `{ callId, toolName, attempt, reason, connection? }`. A read is running again after a transient failure. `attempt` is the try about to run. `reason` is a class such as `transport` or `http_503` |
89
-
90
- The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
91
- exported from `@grok/agent-sdk`.
92
-
93
- ## Handler context
94
-
95
- | Member | What it is |
96
- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
97
- | `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set |
98
- | `ctx.agent` | `{ name }` of the agent the event belongs to |
99
- | `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
100
- | `ctx.host.kv` | Durable JSON, shared by every session of the agent. Prefix keys with `ctx.session.id` for per-session state |
101
- | `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
102
- | `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
103
- | `ctx.host.reminders` | Per-session [reminders](./schedules.md#reminders), the same API tools get |
104
- | `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` fills in `sessionId` and `turnId` |
105
- | `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files` |
106
-
107
- ## Hook dispatch
108
-
109
- A hook runs after the event is recorded. It never delays the model and
110
- never sees an event that wasn't recorded.
111
-
112
- | Rule | What happens |
113
- | --- | --- |
114
- | Same session | Events dispatch one at a time |
115
- | Eval sessions | The same stream fires; skip metering or paging when `ctx.session.purpose === "eval"` |
116
- | Host restart | Recorded events are not replayed into hooks, so a mirror needs no dedupe |
117
- | Slow handler | Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow |
118
-
119
- Read hosted secrets inside the handler, not at module scope. Give
120
- outbound calls a timeout; a stalled request holds later handlers on that
121
- session. Skip cancelled turns when paging; they record interrupted work.
122
-
123
- ```ts
124
- // bot/hooks/page-on-failure.ts
125
- import { defineHook } from "@grok/agent-sdk/hooks";
126
-
127
- export default defineHook({
128
- events: {
129
35
  async "turn.failed"(event, ctx) {
130
36
  const pagerUrl = process.env.PAGER_WEBHOOK_URL;
131
37
  if (
@@ -135,13 +41,13 @@ export default defineHook({
135
41
  ) {
136
42
  return;
137
43
  }
44
+ turnFailed.add(1, { channel: ctx.channel.id });
138
45
  await fetch(pagerUrl, {
139
46
  method: "POST",
140
47
  headers: { "content-type": "application/json" },
141
48
  body: JSON.stringify({
142
49
  agent: ctx.agent.name,
143
50
  session: ctx.session.id,
144
- channel: ctx.channel.id,
145
51
  message: event.data.message,
146
52
  }),
147
53
  signal: AbortSignal.timeout(5_000),
@@ -151,37 +57,68 @@ export default defineHook({
151
57
  });
152
58
  ```
153
59
 
154
- ## Hooks vs channels vs evals
60
+ Any module under `bot/hooks/` is a hook named by its path without the extension. `*.test.ts` and `*.spec.ts` are skipped. The default export must be `defineHook(...)`, names can't contain `__`, and an empty `events` map is skipped with a warning. `agent-sdk validate` reports all three. An extension mounts its hooks as `<ns>__<name>`, and `disableHook()` removes one. See [Adjust a mounted extension](./extensions.md#adjust-a-mounted-extension).
155
61
 
156
- All three consume the same stream, for different jobs:
62
+ `agent-sdk init` scaffolds `bot/hooks/memory.ts`. Delete it to opt out of the journal. See [Memory](./memory.md).
63
+
64
+ Read hosted secrets inside the handler, not at module scope. See [Add egress and secrets](../deployment.md#add-egress-and-secrets). Give outbound calls a timeout, because a stalled request blocks later handlers on that session.
65
+
66
+ ## Events and payloads
157
67
 
158
- | | Hooks | Channel `events` | Evals |
159
- | ------------------ | ----------------------------------------------- | ----------------------------------------------------------------- | --------------------------------- |
160
- | Scope | every session of the agent | sessions the channel owns | one test turn |
161
- | Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory |
162
- | Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers |
163
- | Can affect the run | no | yes, it owns the surface | n/a |
164
- | Authored at | `bot/hooks/*.ts` | channel config | `evals/**/*.eval.ts` |
68
+ Keys are event types from the [event vocabulary](./sessions.md#stream-events), or `"*"` for every event. A typed key narrows `event.data`, a `"*"` handler receives the union so you switch on `event.type`, and every event carries `{ type, index, sessionId, turnId?, at, data }`. Skip `*.appended` deltas when you want the final text.
69
+
70
+ | Event | `event.data` |
71
+ | --- | --- |
72
+ | `message.received` | `{ text }` |
73
+ | `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
74
+ | `turn.failed` | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present |
75
+ | `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. One envelope per model step. `parentCallId` marks subagent work |
76
+ | `actions.completed` | `{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }`. Emitted when every call in that batch has a result |
77
+ | `action.result` | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. Live per-call envelope. `stubbed` means a dry-run session answered a write without running it |
78
+ | `action.tool_retry` | `{ callId, toolName, attempt, reason, connection? }`. A read is running again after a transient failure. `attempt` is the try about to run |
79
+
80
+ The types are `SessionEvent`, `SessionEventType`, and `HookContext`, exported from `@grok/agent-sdk`.
81
+
82
+ ## Handler context
83
+
84
+ | Member | What it is |
85
+ | --- | --- |
86
+ | `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set |
87
+ | `ctx.agent` | `{ name }` of the agent the event belongs to |
88
+ | `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
89
+ | `ctx.host.kv` | Durable JSON, shared by every session of the agent. Prefix keys with `ctx.session.id` for per-session state |
90
+ | `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
91
+ | `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
92
+ | `ctx.host.reminders` | Per-session [reminders](./schedules.md#reminders) |
93
+ | `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade. `tag` fills in `sessionId` and `turnId` |
94
+ | `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced. Keep derived state in `kv` or `files` |
95
+
96
+ ## Hook dispatch
97
+
98
+ A hook runs after the event is recorded. It never delays the model.
99
+
100
+ | Rule | What happens |
101
+ | --- | --- |
102
+ | Same session | Events dispatch one at a time |
103
+ | Eval sessions | The same stream fires. Skip metering or paging when `ctx.session.purpose === "eval"` |
104
+ | Host restart | Recorded events are not replayed into hooks, so a mirror needs no dedupe |
105
+ | Slow handler | Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow |
165
106
 
166
107
  ## Hook boundaries
167
108
 
168
- | You want to | Use instead |
169
- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
170
- | Add context before the model runs | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
171
- | Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
172
- | Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`; see [GitHub agents](../guides/github.md) |
173
- | Gate a change on behavior | [Evals](../evals.md) |
109
+ | You want to | Use instead |
110
+ | --- | --- |
111
+ | Add context before the model runs | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
112
+ | Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
113
+ | Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`. See [GitHub agents](../guides/github.md) |
114
+ | Gate a change on behavior | [Evals](../evals.md) |
115
+ | Observe every session for audit, metrics, or a transcript mirror | A hook |
174
116
 
175
- To act on a turn's decision, such as a label or a ticket, have the model
176
- record it with an authored [tool](./tools.md). A `turn.completed` hook then
177
- reads the recorded decision and acts on it through `ctx.host`.
117
+ To act on a turn's decision, such as a label or a ticket, have the model record it with an authored [tool](./tools.md). A `turn.completed` hook then reads the recorded decision and acts on it through `ctx.host`.
178
118
 
179
119
  ## Test a hook
180
120
 
181
- A hook definition is a plain object, so a unit test calls
182
- `hook.events["turn.completed"]` directly with an event and a stub
183
- `HookContext`. Discovery skips `*.test.ts`, so the test can live next to
184
- the hook.
121
+ A hook definition is a plain object, so a unit test calls `hook.events["turn.completed"]` directly with an event and a stub `HookContext`. Discovery skips `*.test.ts`, so the test can live next to the hook.
185
122
 
186
123
  | Command | What it reports |
187
124
  | --- | --- |
@@ -191,12 +128,4 @@ the hook.
191
128
 
192
129
  On hosting, read the same log with [`agent-sdk logs`](./cli.md#logs).
193
130
 
194
- ## Related
195
-
196
- - [Hooks guide](../guides/hooks.md): meter usage and page on failure
197
- - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
198
- - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
199
- from the same event stream
200
- - [Deployment](../deployment.md#observability): runtime logs and export
201
- paths
202
- - [Channels](./channels.md#events): the delivery-side counterpart
131
+ See also [Sessions](./sessions.md#stream-events), [OpenTelemetry](../guides/opentelemetry.md), and [Channels](./channels.md#events).
@@ -5,31 +5,28 @@ description: "Public session, discovery, and channel routes callers use."
5
5
 
6
6
  # HTTP API
7
7
 
8
- Agent SDK hosts expose one public HTTP surface. In the default
9
- multi-agent layout, each agent uses `/<slug>/v1/*`; `--mode single` serves the
10
- same routes at `/v1/*`. Routes use the agent's HTTP auth chain, and
11
- session-owned resources return `403` to another principal.
12
-
13
- Unless a section says otherwise, the default auth policy is
14
- `localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
15
- `--allow-anonymous` replaces it with anonymous access. Built-in JSON
16
- routes use `{ ok: false, error: "<code>", message? }` for errors, and MCP
17
- uses JSON-RPC. Custom channel routes answer hosted callers with an empty
18
- `202`; see [Call custom channel routes](#call-custom-channel-routes).
8
+ In the default multi-agent layout each agent serves its routes at
9
+ `/<slug>/v1/*`, and `--mode single` serves them at `/v1/*`.
10
+
11
+ Routes use the agent's HTTP auth chain, which defaults to
12
+ `localDevStrict()`. `--bearer-token` and `--allow-anonymous` replace it
13
+ with bearer or anonymous access. Built-in JSON
14
+ routes return errors as `{ ok: false, error: "<code>", message? }`, and
15
+ MCP uses JSON-RPC.
19
16
 
20
17
  ## Host routes
21
18
 
22
- These routes live at the host root in multi-agent mode. The index routes
23
- exist only when the playground is enabled.
19
+ These routes need no auth.
24
20
 
25
21
  | Route | Contract |
26
22
  | --- | --- |
27
- | `GET /` | HTML index of mounted agents; no auth |
28
- | `GET /v1/agents` | JSON index of mounted agents; no auth |
29
- | `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
23
+ | `GET /` | HTML index of mounted agents |
24
+ | `GET /v1/agents` | JSON index of mounted agents, multi-agent layout only |
25
+ | `GET /<slug>/playground`, `GET /<slug>/playground/assets/:file` | The agent's playground page and assets |
26
+ | `GET /docs`, `GET /docs/*` | Documentation site |
30
27
 
31
- `--no-playground` removes the two index routes. `--no-docs` removes the
32
- documentation site.
28
+ `--no-playground` removes the index and playground routes, and
29
+ `--no-docs` removes the docs.
33
30
 
34
31
  ## Start a session
35
32
 
@@ -43,17 +40,14 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
43
40
  # "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
44
41
  ```
45
42
 
46
- Once accepted, the response returns `sessionId` for inspection and
47
- `continuationToken` for follow-ups; follow the stream for progress.
48
-
49
43
  | Body field | Contract |
50
44
  | --- | --- |
51
45
  | `message` | Required user message |
52
46
  | `title` | Display title |
53
47
  | `dryRun` | Run read tools and stub write tools |
54
- | `asOf` | ISO-8601 instant with a timezone; sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments. Invalid values return `400` |
48
+ | `asOf` | ISO-8601 instant with a timezone. Sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments |
55
49
  | `workspaceFiles` | Relative files added to the session workspace |
56
- | `purpose` | Use `"eval"` to mark regression traffic |
50
+ | `purpose` | `"eval"` marks regression traffic |
57
51
 
58
52
  ## Send a follow-up
59
53
 
@@ -65,13 +59,7 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
65
59
  -d '{"continuationToken":"http:…","message":"Make it shorter."}'
66
60
  ```
67
61
 
68
- The route accepts any chat session, including one created by a custom
69
- channel. Each accepted follow-up rotates the continuation token and
70
- returns the replacement. A message sent to a busy session interrupts
71
- the active turn before starting.
72
-
73
- The route returns `409` for a stale token or task session, and `403`
74
- when the caller doesn't own the session.
62
+ The route accepts any chat session, including one a custom channel created. Each accepted follow-up returns a new continuation token. A message to a busy session interrupts the active turn. A stale token or a task session returns `409`.
75
63
 
76
64
  ## Stream or replay session events
77
65
 
@@ -81,146 +69,106 @@ when the caller doesn't own the session.
81
69
  curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
82
70
  ```
83
71
 
84
- The route replays one event per line from `startIndex`, then follows new
85
- events. The default `0` replays the full stream. To reconnect without
86
- duplicates, pass the last index you received plus one.
72
+ It replays from `startIndex`, which defaults to `0`, then follows new
73
+ events. To reconnect without duplicates, pass the last index you
74
+ received plus one.
87
75
 
88
- `GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
89
- Pass `?format=json` for `{ sessionId, events, playgroundUrl }`. See
90
- [Stream events](./sessions.md#stream-events) for the event vocabulary.
76
+ `GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump, or
77
+ `{ sessionId, events, playgroundUrl }` with `?format=json`.
78
+ [Stream events](./sessions.md#stream-events) lists the event types.
91
79
 
92
80
  ## Manage sessions
93
81
 
94
82
  | Route | Contract |
95
83
  | --- | --- |
96
84
  | `POST /v1/session/:sessionId/stop` | Interrupt the active turn without sending another message |
97
- | `GET /v1/sessions` | List sessions owned by the caller |
98
- | `GET /v1/session/:sessionId/cost` | Return per-turn token usage and estimated cost |
85
+ | `GET /v1/sessions` | List sessions the caller owns |
86
+ | `GET /v1/session/:sessionId/cost` | Per-turn token usage and estimated cost |
99
87
 
100
- On loopback under `serve --dev`, the session list includes every
101
- principal so webhook and schedule sessions appear in the playground.
102
- The cost route returns `404` for an unknown session.
88
+ Under `serve --dev` on loopback, the list includes every principal's
89
+ sessions.
103
90
 
104
91
  ## Call a tool without a model turn
105
92
 
106
- `POST /v1/tools/:toolName` runs a server tool with no model turn.
107
-
108
- ```bash
109
- curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
110
- -H 'content-type: application/json' \
111
- -d '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'
112
- # {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",
113
- # "isError":false,"result":{…},"durationMs":12}
114
- ```
115
-
116
- | Body field | Contract |
93
+ | Route | Contract |
117
94
  | --- | --- |
118
- | `input` | Tool input; defaults to `{}` |
119
- | `sessionId` | Bind the call to an existing session |
120
- | `continuationToken` | Bind the call by its wire continuation token; mutually exclusive with `sessionId` |
95
+ | `POST /v1/tools/:toolName` | Run a server tool on `{ input, sessionId?, continuationToken? }` |
121
96
 
122
- Omit both identifiers for an unbound call. Agent-execution tools return
123
- `400`, and an unknown name returns `404` with the available names. See
124
- [Tools](./tools.md#call-a-tool-without-a-model-turn) for session
125
- binding, busy-session rules, and error codes.
97
+ [Tools](./tools.md#call-a-tool-without-a-model-turn) covers session
98
+ binding, busy sessions, and error codes.
126
99
 
127
100
  ## Discovery routes
128
101
 
129
- These read-only routes describe the running agent.
130
-
131
102
  | Route | Contract |
132
103
  | --- | --- |
133
- | `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
134
- | `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind session-specific listings with `session` or `continuationToken` |
135
- | `GET /v1/tools/:name` | Return one tool's description, execution mode, effect rules, schemas, and source |
136
- | `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
104
+ | `GET /v1/info` | Everything discovery found, such as the model, tools, channels, and diagnostics |
105
+ | `GET /v1/tools` | Server and advertised MCP tools as `{ name, title?, source? }`, optionally for one `session` or `continuationToken` |
106
+ | `GET /v1/tools/:name` | One tool's schemas, effect rules, execution mode, and source. An unknown name returns `404` with the available names |
107
+ | `GET /v1/logs?after=N` | Recent server logs and the next polling cursor |
137
108
 
138
- An unknown tool name returns `404` with available names. If an MCP
139
- connection can't list its tools, the catalog skips that connection and
140
- includes it in `connectionErrors`.
109
+ `connectionErrors` names any connection that couldn't list its tools.
141
110
 
142
111
  ## List and download artifacts
143
112
 
144
- | Route | Contract |
145
- | --- | --- |
146
- | `GET /v1/artifacts` | Return `{ artifacts }`, newest-updated first; filter with `kind`, `sessionId`, and a positive `limit` |
147
- | `GET /v1/artifacts/:id/content` | Download an artifact's file or blob as an attachment; return `404` when no content exists |
148
-
149
- The list follows the same ownership rules as `GET /v1/sessions`. See
150
- [Artifacts](./artifacts.md) for tagging and record fields.
113
+ `GET /v1/artifacts` returns the caller's `{ artifacts }`, newest-updated
114
+ first, filtered by `kind`, `sessionId`, and a positive `limit`.
115
+ `GET /v1/artifacts/:id/content` downloads an artifact's file or blob.
116
+ [Artifacts](./artifacts.md) covers tagging and record fields.
151
117
 
152
118
  ## Call custom channel routes
153
119
 
154
120
  Authored routes mount under `/v1/channels/<id>` with their declared
155
- methods and paths, and each channel's auth chain applies. A hosted
156
- caller receives `202 Accepted` with an empty body, never the handler's
157
- response. See [Route responses](./channels.md#route-responses).
121
+ methods and paths, behind each channel's auth chain.
122
+ [Route responses](./channels.md#route-responses) covers what a hosted
123
+ caller gets back.
158
124
 
159
125
  ## MCP endpoint
160
126
 
161
- Both MCP routes use stateless streamable HTTP. Send protocol requests
162
- with `POST`; `GET` and `DELETE` return `405`.
163
-
164
- | Route | Tools and auth |
165
- | --- | --- |
166
- | `/v1/mcp` | `ask`, `check`, and `call_tool` when server tools exist; uses the session API auth chain |
167
- | `/v1/mcp/tools` | Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain |
127
+ Both MCP routes use stateless streamable HTTP, so they take `POST` and
128
+ return `405` for `GET` and `DELETE`.
168
129
 
169
- See [MCP connections](./connections.md#peer-mcp-connection) to connect
170
- one agent to another.
130
+ `/v1/mcp` serves `ask`, `check`, and `call_tool` when server tools
131
+ exist, behind the session API auth chain. `/v1/mcp/tools` serves only
132
+ deterministic server tools, behind the CLI-level loopback, bearer, or
133
+ anonymous auth chain. [MCP connections](./connections.md#peer-mcp-connection)
134
+ connects one agent to another.
171
135
 
172
136
  ## Playground eval routes
173
137
 
174
- The playground Evals tab and remote eval commands use these routes:
175
-
176
138
  | Route | Contract |
177
139
  | --- | --- |
178
140
  | `GET /v1/dev/evals` | List discovered cases and eval config |
179
141
  | `GET /v1/dev/evals/runs` | List recent run snapshots, newest first |
180
- | `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`; return `202`, `404` for no match, or `409` while another run is active |
181
- | `GET /v1/dev/evals/runs/:runId` | Return progress and the final snapshot |
182
- | `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run; return `404` when unknown or `409` when no longer running |
142
+ | `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`. Returns `202`, `404` for no match, or `409` while a run is active |
143
+ | `GET /v1/dev/evals/runs/:runId` | Progress and the final snapshot |
144
+ | `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run. Returns `409` when it already ended |
183
145
 
184
- Poll the run route until its status is `completed`, `failed`, or
185
- `cancelled`. Entries within `filterIds` and `tags` use OR semantics;
186
- when both fields are present, a case must match each group.
146
+ Poll a run until it is `completed`, `failed`, or `cancelled`. A case must match one entry from each of `filterIds` and
147
+ `tags` that you pass.
187
148
 
188
149
  ## Dev-mode routes
189
150
 
190
- These routes exist only under `serve --dev`.
191
-
192
- | Route | Contract |
193
- | --- | --- |
194
- | `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once. Returns `{scheduleId, sessionIds}` |
195
- | `GET /v1/dev/reminders` | List reminders |
196
- | `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand |
197
-
198
- Schedules and reminders never fire automatically in dev mode. These
199
- routes run them manually.
200
-
201
- ## Playground assets
202
-
203
- `GET /playground` and `GET /playground/assets/:file` serve the
204
- playground. `--no-playground` removes both routes.
151
+ These routes exist only under `serve --dev`, where schedules and
152
+ reminders never fire on their own. `POST /v1/dev/schedules/:scheduleId`
153
+ dispatches a schedule once and returns `{scheduleId, sessionIds}`.
154
+ `GET /v1/dev/reminders` lists reminders, and
155
+ `POST /v1/dev/reminders/:reminderId` fires one.
205
156
 
206
157
  ## Status codes
207
158
 
208
- Built-in routes use these common status codes.
209
-
210
159
  | Code | Meaning |
211
160
  | --- | --- |
212
- | `400` | Invalid body, query, tool input, or request shape |
161
+ | `202` | Accepted for asynchronous work |
162
+ | `400` | Invalid body, query, or tool input |
213
163
  | `401` | No auth policy admitted the request |
214
- | `403` | The caller is authenticated but doesn't own the resource |
215
- | `404` | A named resource doesn't exist, or an eval selection matches no cases |
164
+ | `403` | The caller doesn't own the resource |
165
+ | `404` | A named resource doesn't exist, or no eval case matches |
216
166
  | `405` | The route doesn't accept this method |
217
- | `409` | The resource state rejects the request, such as a stale token or busy write |
218
- | `202` | The request was accepted for asynchronous work |
167
+ | `409` | The resource's state rejects the request, such as a stale token or busy write |
219
168
  | `500` | A write-effect tool can't create its session workspace (`workspace_unavailable`) |
220
169
 
221
170
  ## Related
222
171
 
223
172
  - [Sessions](./sessions.md)
224
173
  - [Channels](./channels.md)
225
- - [Tools](./tools.md)
226
174
  - [Deployment](../deployment.md)
@@ -1,21 +1,21 @@
1
1
  ---
2
2
  title: "Instructions"
3
- description: "The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."
3
+ description: "The always-on system prompt: authoring forms, how a local turn and a turn in the cloud receive it, and what makes instructions hold up."
4
4
  ---
5
5
 
6
6
  # Instructions
7
7
 
8
- Agent instructions form the always-on system prompt and reach the model
9
- on every turn. A root agent requires them; a subagent may inline
10
- `instructions` in `agent.ts` instead.
8
+ Instructions are the always-on prompt for every turn. A root agent
9
+ requires them, and a subagent may inline `instructions` in `agent.ts`
10
+ instead.
11
11
 
12
12
  ## Authoring forms
13
13
 
14
14
  | Form | Use it when |
15
15
  | --- | --- |
16
- | `bot/instructions.md` | Plain Markdown for most agents |
17
- | `bot/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string |
18
- | `bot/instructions/` directory | A long prompt split across files, composed in filename order |
16
+ | `bot/instructions.md` | Most agents |
17
+ | `bot/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a string |
18
+ | `bot/instructions/` | A long prompt split across files, joined in filename order |
19
19
 
20
20
  ```ts
21
21
  // bot/instructions.ts
@@ -26,25 +26,23 @@ export default defineInstructions({
26
26
  });
27
27
  ```
28
28
 
29
- The `markdown` string is fixed when this file loads. Read a secret in
30
- a handler, a tool, or a callback. See
31
- [Add egress and secrets](../deployment.md#add-egress-and-secrets).
29
+ The `markdown` string is fixed when the file loads. See
30
+ [Add egress and secrets](../deployment.md#add-egress-and-secrets) for
31
+ reading secrets inside a handler.
32
32
 
33
33
  ## Delivery
34
34
 
35
- Instructions land in the session workspace as `AGENTS.md`, and the
36
- harness loads them natively. Parent directories can still contribute
37
- ambient `AGENTS.md` and `.cursor` settings;
38
- [Agent config: local cwd](./agent-config.md#local-cwd) covers how to
39
- control that.
35
+ A local turn sends the instructions, with a short identity section, as the system prompt, and a turn in the cloud includes the same text in the first user message. Nothing is written to the workspace as `AGENTS.md`, but a parent directory's `AGENTS.md` can still reach a local session. See
36
+ [Local cwd](./agent-config.md#local-cwd).
40
37
 
41
38
  ## Contents
42
39
 
43
- Keep them a few lines: identity, when to use which tool, and the output
44
- shape. The [quickstart PR approver](../quickstart.md) is the pattern:
40
+ Keep instructions to a few lines that cover identity, when to use each
41
+ tool, and the output shape. A short version of the
42
+ [quickstart](../quickstart.md) reviewer:
45
43
 
46
44
  ```md
47
- # PR approver
45
+ # PR reviewer
48
46
 
49
47
  You review GitHub pull requests. Be specific and brief.
50
48
 
@@ -55,15 +53,7 @@ You review GitHub pull requests. Be specific and brief.
55
53
  End with one sentence: the verdict and why.
56
54
  ```
57
55
 
58
- Name the tools and the decision rule ("use X before answering about
59
- Y"), not general encouragement. State the output contract, including
60
- length, format, and fences, so your [evals](../evals.md) can gate it.
61
- Put multi-step workflows the model only sometimes needs in
62
- `bot/skills/`; they load on demand and keep the always-on prompt small.
63
-
64
- ## Related
65
-
66
- - [Skills](./skills.md): procedures the model loads only when relevant
67
- - [Agent config](./agent-config.md): the file next to this one
68
- - [Hillclimbing](../hillclimbing.md): iterating on instructions with
69
- evidence
56
+ Name the tools and the decision rule, such as "use X before answering
57
+ about Y". State the output contract, including length and format, so
58
+ your [evals](../evals.md) can gate it. Move occasional multi-step
59
+ workflows into [skills](./skills.md), which load on demand.