@grok/agent-sdk 0.2.29 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (396) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/docs/404.html +2 -2
  3. package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
  4. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  5. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  6. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  7. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  8. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  9. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  10. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
  11. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  12. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
  13. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  14. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  15. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  16. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  17. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  18. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  24. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  25. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  26. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  27. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  28. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  29. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  30. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  33. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  34. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  35. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  36. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  37. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
  38. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  39. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  40. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  41. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  42. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
  43. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
  44. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
  45. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  46. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  47. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  48. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  49. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  50. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  51. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  52. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  53. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
  54. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  55. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  56. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  57. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  58. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  59. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  60. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  61. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  62. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  63. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  64. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  65. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  66. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  67. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  68. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  69. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  70. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  72. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  74. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  75. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  76. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  77. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  78. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  80. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  81. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  82. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  83. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  84. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  85. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  86. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  87. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  88. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  89. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  90. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  91. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  92. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  93. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  94. package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
  95. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  96. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  97. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  98. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  99. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  100. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  101. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  102. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  103. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  104. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  105. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  106. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  107. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  108. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  109. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  110. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  111. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  112. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  113. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  114. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  115. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  116. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  117. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  118. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  119. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  120. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  121. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  122. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  123. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  124. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  125. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  126. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  127. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  128. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  129. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  130. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  131. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  132. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  133. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  134. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  135. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  136. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  137. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  138. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  139. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  140. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  141. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  142. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  143. package/dist/docs/building-with-agents.html +41 -44
  144. package/dist/docs/building-with-agents.md +11 -104
  145. package/dist/docs/changelog.html +37 -37
  146. package/dist/docs/changelog.md +5 -155
  147. package/dist/docs/deployment.html +54 -54
  148. package/dist/docs/deployment.md +83 -262
  149. package/dist/docs/evals.html +52 -71
  150. package/dist/docs/evals.md +33 -129
  151. package/dist/docs/guides/agent-to-agent.html +43 -43
  152. package/dist/docs/guides/agent-to-agent.md +27 -64
  153. package/dist/docs/guides/bitbucket.html +62 -62
  154. package/dist/docs/guides/bitbucket.md +73 -134
  155. package/dist/docs/guides/cloud-agents.html +37 -37
  156. package/dist/docs/guides/cloud-agents.md +23 -53
  157. package/dist/docs/guides/convert-automation.html +39 -56
  158. package/dist/docs/guides/convert-automation.md +31 -115
  159. package/dist/docs/guides/github.html +46 -54
  160. package/dist/docs/guides/github.md +49 -131
  161. package/dist/docs/guides/gitlab.html +98 -108
  162. package/dist/docs/guides/gitlab.md +104 -184
  163. package/dist/docs/guides/improve.html +38 -43
  164. package/dist/docs/guides/improve.md +24 -90
  165. package/dist/docs/guides/jev.html +55 -95
  166. package/dist/docs/guides/jev.md +53 -160
  167. package/dist/docs/guides/mcp-oauth.html +38 -40
  168. package/dist/docs/guides/mcp-oauth.md +33 -67
  169. package/dist/docs/guides/migrate.html +38 -43
  170. package/dist/docs/guides/migrate.md +56 -130
  171. package/dist/docs/guides/opentelemetry.html +41 -43
  172. package/dist/docs/guides/opentelemetry.md +32 -27
  173. package/dist/docs/guides/pagerduty.html +50 -49
  174. package/dist/docs/guides/pagerduty.md +65 -199
  175. package/dist/docs/guides/slack.html +51 -57
  176. package/dist/docs/guides/slack.md +76 -204
  177. package/dist/docs/guides/webhooks.html +42 -42
  178. package/dist/docs/guides/webhooks.md +64 -146
  179. package/dist/docs/hashmap.json +1 -1
  180. package/dist/docs/hillclimbing.html +40 -42
  181. package/dist/docs/hillclimbing.md +40 -102
  182. package/dist/docs/index.html +55 -61
  183. package/dist/docs/index.md +49 -83
  184. package/dist/docs/llms-full.txt +2262 -5721
  185. package/dist/docs/llms.txt +9 -14
  186. package/dist/docs/quickstart.html +95 -152
  187. package/dist/docs/quickstart.md +91 -180
  188. package/dist/docs/reference/access.html +36 -36
  189. package/dist/docs/reference/access.md +7 -12
  190. package/dist/docs/reference/agent-config.html +43 -56
  191. package/dist/docs/reference/agent-config.md +91 -174
  192. package/dist/docs/reference/artifacts.html +38 -39
  193. package/dist/docs/reference/artifacts.md +38 -62
  194. package/dist/docs/reference/channels.html +38 -39
  195. package/dist/docs/reference/channels.md +102 -151
  196. package/dist/docs/reference/cli.html +68 -84
  197. package/dist/docs/reference/cli.md +232 -697
  198. package/dist/docs/reference/connections.html +45 -57
  199. package/dist/docs/reference/connections.md +83 -164
  200. package/dist/docs/reference/evals.html +47 -54
  201. package/dist/docs/reference/evals.md +75 -141
  202. package/dist/docs/reference/extensions.html +41 -43
  203. package/dist/docs/reference/extensions.md +37 -70
  204. package/dist/docs/reference/hooks.html +40 -52
  205. package/dist/docs/reference/hooks.md +62 -133
  206. package/dist/docs/reference/http-api.html +38 -42
  207. package/dist/docs/reference/http-api.md +66 -118
  208. package/dist/docs/reference/instructions.html +39 -39
  209. package/dist/docs/reference/instructions.md +19 -29
  210. package/dist/docs/reference/limits.html +38 -38
  211. package/dist/docs/reference/limits.md +9 -21
  212. package/dist/docs/reference/memory.html +37 -38
  213. package/dist/docs/reference/memory.md +38 -75
  214. package/dist/docs/reference/playground.html +36 -36
  215. package/dist/docs/reference/playground.md +14 -22
  216. package/dist/docs/reference/project-layout.html +49 -48
  217. package/dist/docs/reference/project-layout.md +38 -84
  218. package/dist/docs/reference/schedules.html +46 -48
  219. package/dist/docs/reference/schedules.md +59 -90
  220. package/dist/docs/reference/sessions.html +37 -37
  221. package/dist/docs/reference/sessions.md +66 -113
  222. package/dist/docs/reference/skills.html +39 -39
  223. package/dist/docs/reference/skills.md +11 -31
  224. package/dist/docs/reference/subagents.html +37 -37
  225. package/dist/docs/reference/subagents.md +17 -31
  226. package/dist/docs/reference/tools.html +47 -64
  227. package/dist/docs/reference/tools.md +48 -130
  228. package/dist/docs/templates/agentic-owners.html +38 -38
  229. package/dist/docs/templates/agentic-owners.md +50 -74
  230. package/dist/docs/templates/reviews.html +69 -0
  231. package/dist/docs/templates/reviews.md +71 -0
  232. package/dist/docs/troubleshooting.html +38 -36
  233. package/dist/docs/troubleshooting.md +48 -101
  234. package/dist/internal/cli-deploy.js +1 -1
  235. package/dist/internal/cli-docs.js +1 -1
  236. package/dist/internal/cli-images.js +1 -1
  237. package/dist/internal/cli-skills.js +1 -1
  238. package/dist/internal/cursor/credentials.js +1 -1
  239. package/dist/internal/deploy-manifest.d.ts +1 -0
  240. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  241. package/dist/internal/deploy-manifest.js +0 -1
  242. package/dist/internal/discovery/agent-config.d.ts +2 -6
  243. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  244. package/dist/internal/discovery/agent-config.js +8 -25
  245. package/dist/internal/discovery/agent.d.ts.map +1 -1
  246. package/dist/internal/discovery/agent.js +2 -3
  247. package/dist/internal/discovery/project.d.ts.map +1 -1
  248. package/dist/internal/discovery/project.js +15 -0
  249. package/dist/internal/init-project.d.ts.map +1 -1
  250. package/dist/internal/init-project.js +7 -5
  251. package/dist/internal/reminder-runner.js +1 -1
  252. package/dist/internal/session-engine.js +1 -1
  253. package/dist/internal/shallow-clone.js +1 -1
  254. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  255. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  256. package/dist/playground/index.html +2 -2
  257. package/dist/types.d.ts +4 -17
  258. package/dist/types.d.ts.map +1 -1
  259. package/docs/README.md +49 -83
  260. package/docs/building-with-agents.md +11 -104
  261. package/docs/changelog.md +6 -156
  262. package/docs/deployment.md +83 -262
  263. package/docs/evals.md +34 -130
  264. package/docs/guides/agent-to-agent.md +27 -64
  265. package/docs/guides/bitbucket.md +73 -134
  266. package/docs/guides/cloud-agents.md +23 -53
  267. package/docs/guides/convert-automation.md +31 -115
  268. package/docs/guides/github.md +49 -131
  269. package/docs/guides/gitlab.md +104 -184
  270. package/docs/guides/improve.md +24 -90
  271. package/docs/guides/jev.md +53 -160
  272. package/docs/guides/mcp-oauth.md +33 -67
  273. package/docs/guides/migrate.md +56 -130
  274. package/docs/guides/opentelemetry.md +37 -27
  275. package/docs/guides/pagerduty.md +68 -200
  276. package/docs/guides/slack.md +76 -204
  277. package/docs/guides/webhooks.md +64 -146
  278. package/docs/hillclimbing.md +41 -103
  279. package/docs/quickstart.md +91 -180
  280. package/docs/reference/access.md +7 -12
  281. package/docs/reference/agent-config.md +91 -174
  282. package/docs/reference/artifacts.md +38 -62
  283. package/docs/reference/channels.md +102 -151
  284. package/docs/reference/cli.md +232 -697
  285. package/docs/reference/connections.md +83 -164
  286. package/docs/reference/evals.md +75 -141
  287. package/docs/reference/extensions.md +37 -70
  288. package/docs/reference/hooks.md +61 -132
  289. package/docs/reference/http-api.md +66 -118
  290. package/docs/reference/instructions.md +20 -30
  291. package/docs/reference/limits.md +10 -22
  292. package/docs/reference/memory.md +38 -75
  293. package/docs/reference/playground.md +14 -22
  294. package/docs/reference/project-layout.md +38 -84
  295. package/docs/reference/schedules.md +59 -90
  296. package/docs/reference/sessions.md +66 -113
  297. package/docs/reference/skills.md +12 -32
  298. package/docs/reference/subagents.md +17 -31
  299. package/docs/reference/tools.md +48 -130
  300. package/docs/templates/agentic-owners.md +50 -74
  301. package/docs/templates/reviews.md +76 -0
  302. package/docs/troubleshooting.md +48 -101
  303. package/package.json +2 -2
  304. package/skills/deploy/SKILL.md +1 -1
  305. package/skills/migrate-v2/SKILL.md +0 -1
  306. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  307. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  308. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  309. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  310. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  311. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  312. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  313. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  314. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  315. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  316. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  317. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  318. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  319. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  320. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  321. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  322. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  323. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  324. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  325. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  326. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  327. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  328. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  329. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  330. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  331. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  332. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  333. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  334. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  335. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  336. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  337. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  338. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  339. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  340. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  341. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  342. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  343. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  344. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  345. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  346. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  347. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  348. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  349. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  350. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  351. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  352. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  353. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  354. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  355. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  356. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  357. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  358. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  359. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  360. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  361. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  362. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  363. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  364. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  365. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  366. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  367. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  368. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  369. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  370. package/dist/docs/guides/hooks.html +0 -113
  371. package/dist/docs/guides/hooks.md +0 -116
  372. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  373. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  374. package/dist/docs/package/skills/github/SKILL.md +0 -133
  375. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  376. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  377. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  378. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  379. package/dist/docs/reference/prompt.html +0 -68
  380. package/dist/docs/reference/prompt.md +0 -47
  381. package/dist/docs/templates/security-reviewer.html +0 -62
  382. package/dist/docs/templates/security-reviewer.md +0 -81
  383. package/dist/docs/templates/thermo-quality-review.html +0 -62
  384. package/dist/docs/templates/thermo-quality-review.md +0 -75
  385. package/dist/docs/templates/thermo-review.html +0 -62
  386. package/dist/docs/templates/thermo-review.md +0 -75
  387. package/dist/docs/templates/triage.html +0 -68
  388. package/dist/docs/templates/triage.md +0 -101
  389. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  390. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  391. package/docs/guides/hooks.md +0 -121
  392. package/docs/reference/prompt.md +0 -52
  393. package/docs/templates/security-reviewer.md +0 -86
  394. package/docs/templates/thermo-quality-review.md +0 -80
  395. package/docs/templates/thermo-review.md +0 -80
  396. package/docs/templates/triage.md +0 -106
@@ -5,20 +5,23 @@ description: "Cron-driven runs defined at deploy time, and per-session durable w
5
5
 
6
6
  # Schedules and reminders
7
7
 
8
- An agent can act without an inbound message in two ways. A schedule is
9
- deploy-time cron: "every weekday at 09:00, summarize open incidents." A
10
- reminder is a runtime wake bound to one conversation: "re-check this
11
- PR's CI in two hours." Schedules live in the filesystem; reminders are
12
- created by running code.
8
+ A schedule or a reminder lets an agent act without an inbound message.
13
9
 
14
- ## Schedules
10
+ ## Schedules vs reminders
11
+
12
+ | | Schedule | Reminder |
13
+ | --- | --- | --- |
14
+ | Defined | At deploy time, in `bot/schedules/*` | At runtime, with `createReminder` or `host.reminders` |
15
+ | Scope | The whole agent | One conversation |
16
+ | Session | Starts a new task session, or hands off through `receive` | Wakes an existing conversation |
17
+ | Cadence | 5-field cron, in UTC, to the minute | `every`, `cron`, `delay`, or `at` |
18
+ | Dev mode | Manual dispatch only | Manual dispatch only, with timers off |
15
19
 
16
- Cron expressions are standard 5-field, evaluated in UTC with minute
17
- granularity.
20
+ ## Schedules
18
21
 
19
22
  ### Markdown schedules
20
23
 
21
- A markdown file with `cron:` frontmatter is a fire-and-forget task:
24
+ A Markdown file with `cron:` frontmatter is a fire-and-forget task:
22
25
 
23
26
  ```md
24
27
  ---
@@ -28,14 +31,14 @@ cron: "0 9 * * 1-5"
28
31
  Pull open incidents and post a summary to the metrics endpoint.
29
32
  ```
30
33
 
31
- Each firing starts a task-mode session: the body is the prompt, the
32
- session runs to `session.completed` or `session.failed`, and it isn't
33
- followable.
34
+ Each fire starts a task-mode session with the body as its prompt, and
35
+ the session runs to `session.completed` or `session.failed` without
36
+ follow-ups.
34
37
 
35
38
  ### Schedule handlers
36
39
 
37
- Use `defineSchedule` with a `run` handler to call tools or hand work into
38
- a channel so its delivery events fire:
40
+ A `run` handler can call tools or hand work to a channel, whose delivery
41
+ events then fire:
39
42
 
40
43
  ```ts
41
44
  import { defineSchedule } from "@grok/agent-sdk/schedules";
@@ -46,8 +49,7 @@ export default defineSchedule({
46
49
  async run({ receive, waitUntil, appAuth, host }) {
47
50
  waitUntil(
48
51
  receive(webhook, {
49
- message:
50
- "Check for new critical alerts. Report only when there are any.",
52
+ message: "Report any new critical alerts.",
51
53
  auth: appAuth,
52
54
  })
53
55
  );
@@ -55,57 +57,50 @@ export default defineSchedule({
55
57
  });
56
58
  ```
57
59
 
58
- `defineSchedule` requires exactly one of `markdown` or `run`. The `run`
59
- handler receives `receive` (hand off into a channel), `callTool`
60
- (deterministic server-tool calls), `waitUntil`, `appAuth` (a
61
- schedule-scoped principal for work the agent does on its own behalf),
62
- and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
63
- `host.reminders`).
60
+ `defineSchedule` takes exactly one of `markdown` or `run`. `appAuth` is a
61
+ schedule-scoped principal for work the agent does on its own behalf. The
62
+ handler also receives `callTool`, for server-tool calls without a model
63
+ turn, and `host`, which holds `host.mcp`, `host.github`, `host.slack`,
64
+ and `host.reminders`.
64
65
 
65
66
  ### Dispatch a schedule
66
67
 
67
- | Mode | What fires |
68
- | --- | --- |
69
- | Cursor-managed hosting | Cron cadence, from the schedules in the deployed release. See [Schedules on Cursor hosting](#schedules-on-cursor-hosting) |
70
- | Production `agent-sdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
71
- | `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
68
+ Schedules fire on their cron cadence on Cursor hosting and under
69
+ production `agent-sdk serve`. Run them in exactly one `serve` process
70
+ per project, or pass `--no-schedules` to turn them off. `serve --dev`
71
+ fires nothing on its own, so dispatch by hand:
72
72
 
73
73
  ```bash
74
74
  curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
75
- # {"scheduleId":"heartbeat","sessionIds":["ses_…"]}
76
75
  ```
77
76
 
78
- The playground can dispatch schedules in dev mode too, and
79
- `handle.dispatchSchedule("heartbeat")` does it programmatically.
77
+ The playground and `handle.dispatchSchedule("heartbeat")` dispatch the
78
+ same way.
80
79
 
81
80
  ### Schedules on Cursor hosting
82
81
 
83
- Each deploy registers the schedules in its release and replaces the
84
- previous set, so a schedule you delete from `bot/schedules/` stops after
85
- the next deploy. Hosted schedules need `@grok/agent-sdk` 0.2.14 or newer in
86
- the project. A deployment built with an earlier version has no hosted
87
- schedules until you upgrade the package and deploy again.
82
+ Each deploy replaces the hosted schedules with the ones in
83
+ `bot/schedules/`, so a schedule you delete stops after your next deploy.
88
84
 
89
- Every fire starts a new runtime. A Markdown schedule starts a task
90
- session there, and a `run` handler must finish in 26 minutes, including
91
- the work it passes to `receive` and `waitUntil`. Nothing in module memory
92
- carries over to the next fire, so keep state in `ctx.host.kv` or
93
- `ctx.host.files`. Each scheduled time starts at most one run, and a
94
- stopped deployment skips its fires.
85
+ A `run` handler must finish in 26 minutes, including the work it passes
86
+ to `receive` and `waitUntil`. Module memory doesn't carry over to the
87
+ next fire, so keep state in `ctx.host.kv` or `ctx.host.files`. Each scheduled time
88
+ starts at most one run, and a stopped deployment skips its fires.
95
89
 
96
- A schedule's name is its path under `bot/schedules/` without the file
90
+ A schedule's name is its path under `bot/schedules/` without the
97
91
  extension. On Cursor hosting, a name has 1 to 100 letters, digits, `.`,
98
- `_`, `-`, or `/`, and starts with a letter or digit. A release holds at
99
- most 64 schedules, and `deploy` rejects a release that breaks either
100
- rule.
92
+ `_`, `-`, or `/`, and starts with a letter or digit. A deploy can hold
93
+ at most 64 schedules, and `deploy` rejects one that breaks either rule.
101
94
 
102
95
  ## Reminders
103
96
 
104
- A reminder is created at runtime and bound to a channel continuation. A
105
- prompt reminder wakes that conversation when it fires; a handler reminder
106
- runs host code, which can call `followup` to wake it. Recurring reminders
107
- behave like `setInterval`, and one-shots behave like `setTimeout`. Prompt
108
- and named-handler reminders stay armed across restarts.
97
+ A reminder belongs to one channel continuation, and it stays armed
98
+ across restarts. A recurring reminder works like `setInterval`, and a
99
+ one-shot reminder works like `setTimeout`.
100
+
101
+ Reminders take a prompt or a named handler. A prompt reminder sends
102
+ `prompt` into the conversation when it fires, and `until` tells the
103
+ model when to cancel it:
109
104
 
110
105
  ```ts
111
106
  await handle.createReminder({
@@ -118,8 +113,8 @@ await handle.createReminder({
118
113
  });
119
114
  ```
120
115
 
121
- When host code must decide what happens on each tick, author a named
122
- handler and pass its default export with serializable `args`:
116
+ When host code must decide what happens on each tick, write a named
117
+ handler. It starts a model turn only if it calls `followup`:
123
118
 
124
119
  ```ts
125
120
  // bot/reminders/ci_recheck.ts
@@ -128,13 +123,15 @@ import { defineReminder } from "@grok/agent-sdk/reminders";
128
123
  export default defineReminder({
129
124
  async run({ args, followup }) {
130
125
  await followup({
131
- message: `Re-check CI for ${String(args.prUrl)}. Report only if the status changed.`,
126
+ message: `Re-check CI for ${String(args.prUrl)}.`,
132
127
  });
133
128
  return { action: "delivered" };
134
129
  },
135
130
  });
136
131
  ```
137
132
 
133
+ Pass its default export as `handler`, with serializable `args`:
134
+
138
135
  ```ts
139
136
  import ciRecheck from "./bot/reminders/ci_recheck.js";
140
137
 
@@ -148,48 +145,20 @@ await handle.createReminder({
148
145
  });
149
146
  ```
150
147
 
151
- Architecture v2, the default, rejects an anonymous `run` handler and a
152
- function `until`, locally and on Cursor hosting. Use a prompt or a named
153
- handler.
154
-
155
- | Form | What it does | After a restart |
156
- | --- | --- | --- |
157
- | Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
158
- | Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
159
- | Anonymous `run` | Architecture v1 only. Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
160
-
161
- The same API is `host.reminders` on channel handlers, tools, and
162
- schedule runs. `builtinTools: { reminders: true }` adds
163
- `reminders_create`, `reminders_list`, and `reminders_cancel` on the
164
- current conversation; see
165
- [Agent config: built-in tools](./agent-config.md#built-in-tools).
148
+ Channel handlers, tools, and schedule runs get the same API as
149
+ `host.reminders`. `builtinTools: { reminders: true }` gives the model
150
+ `reminders_create`, `reminders_list`, and `reminders_cancel` for the
151
+ current conversation. See
152
+ [built-in tools](./agent-config.md#built-in-tools).
166
153
 
167
- `--dev` does not auto-fire reminders. Dispatch one by hand:
154
+ `--dev` doesn't fire reminders on its own. Dispatch one by hand, or call
155
+ `handle.dispatchReminder(id)` from code:
168
156
 
169
157
  ```bash
170
158
  curl http://127.0.0.1:3000/<slug>/v1/dev/reminders # list
171
159
  curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id> # fire one
172
160
  ```
173
161
 
174
- `handle.dispatchReminder(id)` is the programmatic equivalent.
175
-
176
- Cancel reminders when their subject dies, for example on
162
+ Cancel a reminder when its subject ends, for example on
177
163
  `pull_request.closed`. Keep wake prompts generic so the agent re-reads
178
- live state instead of replaying a stale payload.
179
-
180
- ## Schedules vs reminders
181
-
182
- | | Schedule | Reminder |
183
- | -------- | ---------------------------------------------------------- | ----------------------------------------------- |
184
- | Defined | at deploy time, `bot/schedules/*` | at runtime, `createReminder` / `host.reminders` |
185
- | Scope | global to the agent | one channel continuation (one conversation) |
186
- | Session | starts a new task session (or hands off through `receive`) | wakes an existing conversation |
187
- | Cadence | cron (UTC) | `every`, `cron`, `delay`, or `at` |
188
- | Dev mode | manual dispatch only | manual dispatch only (timers off) |
189
-
190
- ## Related
191
-
192
- - [Channels](./channels.md): `receive` and the delivery events
193
- - [GitHub guide](../guides/github.md): reminders in a real webhook loop
194
- - [HTTP API](./http-api.md#dev-mode-routes): the dev
195
- dispatch routes
164
+ live state.
@@ -6,79 +6,66 @@ description: "Understand how conversations continue, how events stream, and wher
6
6
  # Sessions, events, and streaming
7
7
 
8
8
  A session keeps one conversation, its workspace, and an append-only
9
- record of every message and tool call. Continue it with a continuation
10
- token, inspect it with a session ID, and follow progress on the NDJSON
11
- stream. Chat sessions wait for follow-ups; task sessions run once and
12
- stop.
9
+ record of every message and tool call.
13
10
 
14
11
  ## Session contents
15
12
 
16
- Each session combines:
17
-
18
- - A channel and authenticated caller
19
- - A conversation the caller can continue
20
- - A workspace for local turns
21
- - An NDJSON event stream
22
- - State that lets the conversation resume after a restart
23
-
24
- Sessions belong to the principal that created them. Follow-up, stream,
25
- and list routes return `403` when another caller tries to access one.
13
+ Each session also has a channel, an authenticated caller, an NDJSON
14
+ event stream, and state that survives a restart. Sessions belong to the
15
+ principal that created them. Another caller gets `403` from that
16
+ session's routes.
26
17
 
27
18
  ## Session identifiers
28
19
 
29
- Sessions have two identifiers because conversation routing and
30
- inspection are different jobs.
31
-
32
20
  | Identifier | Use it for |
33
21
  | --- | --- |
34
22
  | `continuationToken` | Continue a conversation through its channel |
35
23
  | `sessionId` | Stream events, inspect state, or run a session-bound tool call |
36
24
 
37
- Channels decide what a continuation token looks like. Slack uses its
38
- thread identity. A PR channel can use a key such as `pr:owner/repo#1`.
39
- The built-in HTTP API returns an opaque token and rotates it after each
40
- accepted follow-up. Reusing a stale HTTP token returns `409`.
41
-
42
- Use the continuation token to keep talking. Use the session ID to
43
- observe or manage the stored session.
25
+ Each channel picks its token format, such as a Slack thread or
26
+ `pr:owner/repo#1`. The built-in HTTP API returns an opaque token and
27
+ rotates it after each accepted follow-up, so a stale HTTP token returns
28
+ `409`.
44
29
 
45
30
  ## Session modes
46
31
 
47
- | Mode | Created by | What happens after a turn |
48
- | --- | --- | --- |
49
- | `chat` | HTTP sessions, channel `send`, Slack, or MCP `ask` | Waits in `session.waiting` and accepts follow-ups |
50
- | `task` | Markdown schedules and fire-and-forget dispatch | Ends in `session.completed` or `session.failed` |
51
-
52
- Task sessions don't accept follow-ups. Trying one returns `409`.
32
+ HTTP sessions, channel `send`, Slack, and MCP `ask` create `chat`
33
+ sessions, which wait in `session.waiting` for follow-ups. Markdown
34
+ schedules and fire-and-forget dispatch create `task` sessions, which end
35
+ in `session.completed` or `session.failed`. A follow-up to a task
36
+ session returns `409`.
53
37
 
54
38
  ## Follow-ups
55
39
 
56
- A follow-up to an idle chat session starts another turn. Admission when
57
- the session is already busy depends on the channel:
40
+ A follow-up starts a turn right away on an idle session. On a busy one, the channel decides what happens.
58
41
 
59
42
  | Path | Busy-session policy |
60
43
  | --- | --- |
61
- | HTTP playground / `POST /v1/session/:id` / MCP `ask` | **Preempt** (default): interrupt the in-flight turn, wait for it to settle, then run the new message |
62
- | Slack mentions / DMs / alert-watch | **Coalesce**: leave the active turn running and queue the follow-up. The running turn may receive it at a tool boundary; any asks that remain become one follow-up turn when it finishes |
44
+ | HTTP playground, `POST /v1/session/:id`, MCP `ask` | Preempt (the default). Interrupts the running turn, then runs the new message |
45
+ | Slack mentions, DMs, alert-watch | Coalesce. The running turn may pick up the follow-up at a tool boundary, and the rest become one turn when it finishes |
46
+
47
+ Pass `admission: "coalesce"` on `send()` to use the Slack policy from
48
+ other callers.
63
49
 
64
- Pass `admission: "coalesce"` on `send()` to opt into the Slack policy from
65
- other callers. Omit it (or pass `"preempt"`) to keep interrupt semantics.
50
+ `POST /v1/session/:id/stop` interrupts a turn without sending a message.
51
+ The stream records `turn.failed` with `status: "cancelled"`, and the
52
+ session can take another follow-up. A Slack message that is only `stop`
53
+ or `@agent stop` does the same for its thread and clears pending
54
+ coalesced follow-ups.
66
55
 
67
56
  ### Track which follow-up reached the agent
68
57
 
69
- Every `send()` returns a `deliveryId`. Pass your own as the `deliveryId`
70
- option, such as the webhook delivery ID you already hold, or omit it to
71
- get a fresh `dlv_…` ID. A coalesced follow-up reaches the agent in one of
72
- two ways, and the ID is on the event for that path:
58
+ Every `send()` returns a `deliveryId`. Pass your own, such as a webhook
59
+ delivery ID, or omit it to get a fresh `dlv_…` ID. A coalesced follow-up
60
+ reaches the agent in one of two ways.
73
61
 
74
62
  | Path | Event | Field |
75
63
  | --- | --- | --- |
76
64
  | Steered into the running turn | `nudge.delivered` | `data.deliveryId` |
77
65
  | Fell back to the next turn | That turn's `message.received` | `data.deliveryIds` |
78
66
 
79
- `message.received` lists every send its prompt carries, in arrival order.
80
- Follow-ups queued behind a busy turn drain into one turn, so the list can
81
- hold several IDs. A direct send that starts a turn gets a one-item list.
67
+ `message.received` lists every send its prompt carries in arrival order,
68
+ so one turn can carry several IDs.
82
69
 
83
70
  ```ts
84
71
  // In a route or channel hook: name the steer after the webhook delivery.
@@ -105,98 +92,64 @@ const events: ChannelEventHandlers = {
105
92
  };
106
93
  ```
107
94
 
108
- A local Slack session can also pick up follow-ups at a tool boundary from
109
- its own thread store. That `nudge.delivered` has no `deliveryId`, which
110
- tells it apart from a steered send.
111
-
112
- `POST /v1/session/:id/stop` interrupts a turn without sending a new
113
- message. The stream records `turn.failed` with `status: "cancelled"`;
114
- the session stays a chat session and can take another follow-up. A
115
- whole-message Slack `stop` / `@agent stop` does the same for that thread
116
- and clears pending coalesced follow-ups.
117
-
118
- See [Tools](./tools.md#call-a-tool-without-a-model-turn) for direct-call
119
- behavior while a session is busy.
95
+ In a local Slack session, a `nudge.delivered` event with no `deliveryId`
96
+ came from a new Slack message, not from a `send()` call.
120
97
 
121
98
  ## Stream events
122
99
 
123
- Each NDJSON line uses this envelope:
124
- `{ type, index, sessionId, turnId?, at, data }`. The `index` increases
125
- within one session. The `at` field is an ISO-8601 timestamp.
100
+ Each NDJSON line is a `{ type, index, sessionId, turnId?, at, data }`
101
+ envelope. The `index` increases within one session, and `at` is an
102
+ ISO-8601 timestamp.
126
103
 
127
104
  | Phase | Events | What they tell you |
128
105
  | --- | --- | --- |
129
- | Session | `session.started`, `session.waiting`, `session.completed`, `session.failed` | Session creation, readiness, and task completion |
130
- | Input | `message.received`, `nudge.delivered` | A user message was accepted as a turn's prompt, or reached a running turn mid-turn. Both name the [sends they carry](#track-which-follow-up-reached-the-agent) |
131
- | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](./agent-config.md#concurrency), then turn status, final result, and token usage |
106
+ | Session | `session.started`, `session.waiting`, `session.completed`, `session.failed` | Creation, readiness, and task completion |
107
+ | Input | `message.received`, `nudge.delivered` | A prompt was accepted or reached a running turn. Both carry [delivery IDs](#track-which-follow-up-reached-the-agent) |
108
+ | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queueing under [`maxRunningTurns`](./agent-config.md#concurrency), then status, result, and token usage |
132
109
  | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
133
110
  | Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
134
- | Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
135
- | Tools | `actions.requested`, `actions.completed`, `action.result`, `action.tool_retry` | Tool names, validated arguments, outputs, and errors. `action.tool_retry` means a read is running again after a transient failure |
111
+ | Reply | `message.appended`, `message.completed` | Text deltas and finished assistant messages |
112
+ | Tools | `actions.requested`, `actions.completed`, `action.result`, `action.tool_retry` | Tool names, arguments, outputs, and errors. `action.tool_retry` marks a read retried after a transient failure |
136
113
  | Subagents | `subagent.called`, `subagent.completed` | Delegated work |
137
- | Artifacts | `artifact.tagged` | A durable [artifact](./artifacts.md) was tagged for this session, by host code or `tag_artifact` |
138
-
139
- Pair `actions.requested` with `actions.completed` for each model-step
140
- batch. `action.result` is the live per-call envelope. Read
141
- `turn.completed.data.usage` for input, output, and
142
- cache token counts.
114
+ | Artifacts | `artifact.tagged` | An [artifact](./artifacts.md) was tagged |
143
115
 
144
- ## Stream or replay events
145
-
146
- One endpoint handles both live streaming and replay:
147
-
148
- ```bash
149
- curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
150
- ```
151
-
152
- Pass `startIndex` to continue after the last event you received,
153
- including after a server restart. Omit it or pass `0` to replay the
154
- full session before following new events.
155
- `GET /v1/session/:id/events` returns a one-time dump without staying
156
- connected.
116
+ `actions.requested` and `actions.completed` bracket each model step's
117
+ tool batch, and `action.result` carries each call live. Read
118
+ `turn.completed.data.usage` for token counts.
119
+ [HTTP API](./http-api.md#stream-or-replay-session-events) shows how to
120
+ follow the stream.
157
121
 
158
122
  ## Local session workspace
159
123
 
160
- Agent SDK creates a workspace before the first local turn:
161
-
162
- | Source path | Lands as |
163
- | ---------------------------------- | ----------------------------------------------------------------------- |
164
- | `skills/*` | `.cursor/skills/<name>/SKILL.md` |
165
- | agent tools (`execution: "agent"`) | scripts in the session workspace, with a catalog in `AGENTS.md` |
166
- | `sandbox/workspace/**` | copied in as seed files |
167
- | per-send `workspaceFiles` | written before the turn |
124
+ Agent SDK creates a workspace before the first local turn.
168
125
 
169
- Instructions reach the model as its system prompt; they aren't written
170
- into the workspace. See [Instructions](./instructions.md#delivery).
126
+ | Source path | Lands as |
127
+ | --- | --- |
128
+ | `skills/*` | `.cursor/skills/<name>/SKILL.md` |
129
+ | agent tools (`execution: "agent"`) | Scripts listed in the system prompt |
130
+ | `sandbox/workspace/**` | Seed files |
131
+ | per-send `workspaceFiles` | Files written before the turn |
171
132
 
172
- Local turns use this workspace as their working directory. Parent
173
- directories can contribute `AGENTS.md` and `.cursor` settings. Set
174
- `local.cwd` when you need a clean parent directory. A channel can also
175
- provide a different working directory for one session, such as a PR
176
- worktree.
133
+ On a local turn, Agent SDK sends the instructions as the system prompt, and on a turn in the cloud it includes them in the first user message. Nothing is written into the session workspace as `AGENTS.md`. See
134
+ [Instructions](./instructions.md).
177
135
 
178
- See [Agent config: local cwd](./agent-config.md#local-cwd) for the
179
- inheritance rules.
136
+ A channel can give one session a different directory, such as a PR
137
+ worktree. [Agent config](./agent-config.md#local-cwd) covers what parent
138
+ directories add.
180
139
 
181
140
  ## Session storage
182
141
 
183
- Local session state lives under `--state-root`. A slugged mount stores
184
- it in a subdirectory named for the slug.
185
-
186
- Deleting a session directory removes the session from the server: it
187
- disappears from listings and can no longer be streamed or continued.
142
+ Local session state lives under `--state-root`, in a subdirectory named
143
+ for the slug on a slugged mount. Deleting a session directory removes
144
+ the session from the server.
188
145
 
189
146
  ## Inspect a saved event stream
190
147
 
191
- Use `session get --file` with a saved trace:
192
-
193
- ```text
194
- agent-sdk session get --file <state-root>/traces/<sessionId>.ndjson
195
- ```
196
-
197
- The command prints tool calls, the reply, and token usage in the same
198
- JSON shape as `run`. Open the session's **Trace** view in the playground
199
- for a visual timeline.
148
+ `agent-sdk session get --file <state-root>/traces/<sessionId>.ndjson`
149
+ prints a saved trace's tool calls, reply, and token usage in the same
150
+ JSON shape as `run`. For a session on a running server,
151
+ `agent-sdk session get <sessionId> --view events` prints the raw event
152
+ list. The playground's **Trace** view shows a timeline.
200
153
 
201
154
  ## Related
202
155
 
@@ -5,21 +5,16 @@ description: "On-demand procedures the model loads only when relevant, in three
5
5
 
6
6
  # Skills
7
7
 
8
- A skill is an on-demand procedure following the `SKILL.md` convention:
9
- the harness advertises each skill by its description, and the model
10
- loads the full content only when the task calls for it. Skills are how
11
- you give an agent a multi-step workflow without carrying it in the
12
- always-on [instructions](./instructions.md).
8
+ A skill is an on-demand procedure in the `SKILL.md` convention. Agent SDK advertises each skill by its description, and the model loads a skill only when the task calls for it. Skills give an agent a multi-step workflow without carrying it in the always-on
9
+ [instructions](./instructions.md).
13
10
 
14
11
  ## Authoring forms
15
12
 
16
- Skills support three authoring forms.
17
-
18
13
  | Form | Reach for it when |
19
14
  | --- | --- |
20
- | `bot/skills/<name>.md` | Static Markdown. Optional `description` frontmatter; the first body line is the fallback. |
21
- | `bot/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files (`references/…`). Requires `description` frontmatter. |
22
- | `bot/skills/<name>.ts` | Generated content, with `defineSkill` from `@grok/agent-sdk/skills`. |
15
+ | `bot/skills/<name>.md` | Static Markdown. `description` frontmatter is optional and falls back to the first body line |
16
+ | `bot/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files. Requires `description` frontmatter |
17
+ | `bot/skills/<name>.ts` | Generated content, with `defineSkill` from `@grok/agent-sdk/skills` |
23
18
 
24
19
  Use flat Markdown for static content:
25
20
 
@@ -50,28 +45,13 @@ export default defineSkill({
50
45
 
51
46
  ## Skill delivery
52
47
 
53
- Skills land in the session workspace at
54
- `.cursor/skills/<name>/SKILL.md`, and the harness advertises and loads
55
- them natively.
48
+ Local sessions get each skill at `.cursor/skills/<name>/SKILL.md` in the session workspace, and the agent lists and loads them from there.
56
49
 
57
50
  ## Skills, instructions, and tools
58
51
 
59
- Instructions are always in context: identity, tool-choice rules, the
60
- output contract. Keep them short. Skills load when relevant: procedures,
61
- checklists, house style. Reach for a skill when the model needs to
62
- follow something but only sometimes needs it loaded. Tools are typed,
63
- executable behavior: anything that must be correct every time belongs in
64
- tool code, not in prose the model might paraphrase.
65
-
66
- A good skill description is a routing rule, not a title. Say when to
67
- use it, like "Use when a pull request needs a structured approval
68
- checklist," because the description is all the model sees before
69
- deciding to load it.
70
-
71
- ## Related
72
-
73
- - [Instructions](./instructions.md): what stays always-on
74
- - [Tools](./tools.md): when prose needs to become code
75
- - [Extensions](./extensions.md): skills installed as a package under a
76
- namespace
77
- - [Project layout](./project-layout.md): where skills sit in the tree
52
+ Instructions stay in context on every turn. Skills hold procedures,
53
+ checklists, and house style that the model needs only sometimes. Put
54
+ anything that must be correct every time in a typed
55
+ [tool](./tools.md), where the model can't paraphrase it.
56
+
57
+ A description is a routing hint, so say when to use the skill, as the checklist example does. The model sees only the description before it decides to load the skill.
@@ -5,13 +5,15 @@ description: "Specialist child agents the model delegates to mid-turn, each its
5
5
 
6
6
  # Subagents
7
7
 
8
- A subagent is a specialist child agent the model can delegate to
9
- mid-turn. Each one lives under `bot/subagents/<id>/` with a required
10
- `agent.ts`. Add `instructions.md` or inline `instructions` in `agent.ts`
11
- for a custom prompt. The parent model delegates through the `task` tool,
12
- and the stream records `subagent.called` and `subagent.completed`.
13
- `subagent.completed` has `isError: true` when the subagent failed or was
14
- cancelled.
8
+ A subagent is a specialist child agent the model can delegate to mid-turn. Each one lives under `bot/subagents/<id>/` with a required `agent.ts`.
9
+
10
+ Add `instructions.md`, or inline `instructions` in `agent.ts`, for a custom prompt. Omit `model` to inherit the parent's model.
11
+
12
+ The parent model reads `description` to decide whether to delegate, so write it the way you write a [skill description](./skills.md#skills-instructions-and-tools).
13
+
14
+ The parent delegates through the `task` tool. A parent that limits its [built-in tools](./agent-config.md#harness-tools) must list `"task"`.
15
+
16
+ The stream records `subagent.called` and `subagent.completed`. `subagent.completed` has `isError: true` when the subagent failed or was cancelled.
15
17
 
16
18
  ```text
17
19
  bot/subagents/researcher/
@@ -32,22 +34,15 @@ export default defineAgent({
32
34
 
33
35
  ## Subagent rules
34
36
 
35
- `description` is required. The parent model uses it to decide whether
36
- to delegate, so write it as a routing rule ("Background research: …"),
37
- following the same discipline as a [skill](./skills.md) description.
38
- `model` is optional; omit it to inherit the parent's model, or set it
39
- to run the specialist on a different model.
37
+ Subagents inherit the parent's execution surface. Discovery warns about
38
+ and ignores these directories inside a subagent: `tools/`, `skills/`,
39
+ `extensions/`, `mcp-connections/`, `host-connections/`, `channels/`,
40
+ `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and nested
41
+ `subagents/`.
40
42
 
41
- Subagents inherit the parent's execution surface. Every per-subagent
42
- capability directory is reported as a warning and ignored: `tools/`,
43
- `skills/`, `extensions/`, `mcp-connections/`, `host-connections/`,
44
- `channels/`, `schedules/`, `reminders/`, `hooks/`, `sandbox/`, and
45
- nested `subagents/`.
46
-
47
- Delegation needs both halves: the description makes it possible, and the
48
- parent's [instructions](./instructions.md) make it happen. "When a
49
- request needs background research, delegate to the `researcher`
50
- subagent." The parent routes; the specialist executes.
43
+ The parent's [instructions](./instructions.md) should say when to
44
+ delegate, such as "When a request needs background research, delegate
45
+ to the `researcher` subagent."
51
46
 
52
47
  ## Subagents and peers
53
48
 
@@ -55,12 +50,3 @@ Subagents split one job into roles inside a single agent. When the
55
50
  specialist is independently useful, with its own tools, sessions, and
56
51
  playground, make it a full agent. See
57
52
  [Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
58
-
59
- ## Related
60
-
61
- - [Skills](./skills.md): when a procedure is enough and a child agent
62
- is overkill
63
- - [Peer agents](../guides/agent-to-agent.md): independently useful
64
- specialists
65
- - [Agent config](./agent-config.md#harness-tools): `"task"` on the
66
- parent's tool allowlist