@grok/agent-sdk 0.3.0 → 0.5.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 (289) hide show
  1. package/dist/channels/match-ready/index.d.ts +4 -0
  2. package/dist/channels/match-ready/index.d.ts.map +1 -0
  3. package/dist/channels/match-ready/index.js +2 -0
  4. package/dist/channels/match-ready/match-ready-channel.d.ts +5 -0
  5. package/dist/channels/match-ready/match-ready-channel.d.ts.map +1 -0
  6. package/dist/channels/match-ready/match-ready-channel.js +42 -0
  7. package/dist/channels/match-ready/types.d.ts +25 -0
  8. package/dist/channels/match-ready/types.d.ts.map +1 -0
  9. package/dist/channels/match-ready/types.js +1 -0
  10. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  11. package/dist/channels/slack/slack-channel.js +27 -14
  12. package/dist/docs/404.html +2 -2
  13. package/dist/docs/assets/{app.BzTUBOAD.js → app.CYdjweqP.js} +4 -4
  14. package/dist/docs/assets/{building-with-agents.md.BqJ7AAjG.js → building-with-agents.md.Bo3ct-rf.js} +1 -1
  15. package/dist/docs/assets/changelog.md.BMrJ5WxW.js +1 -0
  16. package/dist/docs/assets/changelog.md.BMrJ5WxW.lean.js +1 -0
  17. package/dist/docs/assets/chunks/@localSearchIndexroot.dUaE1f8e.js +1 -0
  18. package/dist/docs/assets/chunks/{VPLocalSearchBox.DsnRlUT5.js → VPLocalSearchBox.CRATKS9J.js} +1 -1
  19. package/dist/docs/assets/chunks/{arc.DH8GOhiv.js → arc.BxM78ISR.js} +1 -1
  20. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.9m9ObyuE.js → architectureDiagram-Q4EWVU46.Bi6MuKaU.js} +1 -1
  21. package/dist/docs/assets/chunks/{baseUniq.BXHpx1lE.js → baseUniq.L47qqpDG.js} +1 -1
  22. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.xY3EX59q.js → blockDiagram-DXYQGD6D.kHFF2FK5.js} +1 -1
  23. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.DnqgMVgc.js → c4Diagram-AHTNJAMY.BTW85ll3.js} +1 -1
  24. package/dist/docs/assets/chunks/channel.ljJtQtBi.js +1 -0
  25. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.BjFxK2A3.js → chunk-4BX2VUAB.Bbh3_48g.js} +1 -1
  26. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.BujS_Spt.js → chunk-4TB4RGXK.WeAmK3fK.js} +1 -1
  27. package/dist/docs/assets/chunks/{chunk-55IACEB6.YbTjhdaM.js → chunk-55IACEB6.DTdUiVHf.js} +1 -1
  28. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.DnQ8t4GC.js → chunk-EDXVE4YY.n5XzANDz.js} +1 -1
  29. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.B67AwAmj.js → chunk-FMBD7UC4.D51eewCb.js} +1 -1
  30. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.DrZIAFOm.js → chunk-OYMX7WX6.BrY0U7ZV.js} +1 -1
  31. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.BLmmydkn.js → chunk-QZHKN3VN.B0OA4aFV.js} +1 -1
  32. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.DaoOfw0O.js → chunk-YZCP3GAM.Djt3Mjft.js} +1 -1
  33. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.BZ3Uc-XU.js +1 -0
  34. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.BZ3Uc-XU.js +1 -0
  35. package/dist/docs/assets/chunks/clone.BDtbEo69.js +1 -0
  36. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.DMQuNhM5.js → cose-bilkent-S5V4N54A.DiMcA6Q8.js} +1 -1
  37. package/dist/docs/assets/chunks/{dagre-KV5264BT.CZoGVuUf.js → dagre-KV5264BT.BGqI4vrS.js} +1 -1
  38. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.CLt9uOyL.js → diagram-5BDNPKRD.bDqFuMoH.js} +1 -1
  39. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.DpczEm1G.js → diagram-G4DWMVQ6.Y0sxaXRU.js} +1 -1
  40. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.D4r13DvJ.js → diagram-MMDJMWI5.Bg43b0yi.js} +1 -1
  41. package/dist/docs/assets/chunks/{diagram-TYMM5635.CYU9eGFu.js → diagram-TYMM5635.DCfVasEC.js} +1 -1
  42. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.QA9naWEw.js → erDiagram-SMLLAGMA.C72GaD16.js} +1 -1
  43. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BbNoVZYd.js → flowDiagram-DWJPFMVM.DxRQj7pP.js} +1 -1
  44. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.IHjDoG7r.js → ganttDiagram-T4ZO3ILL.DiLZy5Q4.js} +1 -1
  45. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.B21VMdf5.js → gitGraphDiagram-UUTBAWPF.DL8XkRvh.js} +1 -1
  46. package/dist/docs/assets/chunks/{graph.DgJ4L-8V.js → graph.3Xub80xJ.js} +1 -1
  47. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.CQjrcthc.js → infoDiagram-42DDH7IO.O3lGaspu.js} +1 -1
  48. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.D4tPGtVo.js → ishikawaDiagram-UXIWVN3A.w-pCiQzn.js} +1 -1
  49. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.BD3WaNbQ.js → journeyDiagram-VCZTEJTY.Cg_oBs9j.js} +1 -1
  50. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.Ca0o4Tqz.js → kanban-definition-6JOO6SKY.BpfMGPwn.js} +1 -1
  51. package/dist/docs/assets/chunks/{layout.DXXqX4MQ.js → layout.CtwXs__p.js} +1 -1
  52. package/dist/docs/assets/chunks/{linear.5c61gNw4.js → linear.NmCskOrP.js} +1 -1
  53. package/dist/docs/assets/chunks/{min.B1-NAjHX.js → min.DpQtsLKs.js} +1 -1
  54. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.BELznv3-.js → mindmap-definition-QFDTVHPH.B-P-aKVp.js} +1 -1
  55. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.qPzO1mq5.js → pieDiagram-DEJITSTG.BfjjqK7j.js} +1 -1
  56. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.CxIvzbjX.js → quadrantDiagram-34T5L4WZ.BTzHo53F.js} +1 -1
  57. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.CqA0iJx8.js → requirementDiagram-MS252O5E.DIT2FIKr.js} +1 -1
  58. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.XRTutBnb.js → sankeyDiagram-XADWPNL6.NK1wCsgt.js} +1 -1
  59. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.E--7bRLQ.js → sequenceDiagram-FGHM5R23.D9oElkvo.js} +1 -1
  60. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.C4vGu8zq.js → stateDiagram-FHFEXIEX.IPksnixH.js} +1 -1
  61. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CbhzVsQE.js +1 -0
  62. package/dist/docs/assets/chunks/{theme.DMj_7q3B.js → theme.CgKu7tr3.js} +2 -2
  63. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C7LgNVAL.js → timeline-definition-GMOUNBTQ.CuAtJapY.js} +1 -1
  64. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.HUwoZcy_.js → vennDiagram-DHZGUBPP.B87nNW9E.js} +1 -1
  65. package/dist/docs/assets/chunks/wardley-RL74JXVD.BFIVMaoi.js +162 -0
  66. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.B2pSo5rB.js → wardleyDiagram-NUSXRM2D.BELjSq8w.js} +1 -1
  67. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.NQhMiOOL.js → xychartDiagram-5P7HB3ND.5zN5ZGsz.js} +1 -1
  68. package/dist/docs/assets/{deployment.md.BtqJrHhp.js → deployment.md.DJtuDVLh.js} +3 -3
  69. package/dist/docs/assets/{deployment.md.BtqJrHhp.lean.js → deployment.md.DJtuDVLh.lean.js} +1 -1
  70. package/dist/docs/assets/{guides_agent-to-agent.md.BcmSqL2z.js → guides_agent-to-agent.md.DcB3nhOz.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.6jiEH7dg.js → guides_github.md.CcuZ7keS.js} +1 -1
  72. package/dist/docs/assets/{guides_mcp-oauth.md.C-Sx_IPa.js → guides_mcp-oauth.md.GVPMKcYl.js} +1 -1
  73. package/dist/docs/assets/{guides_migrate.md.BbhHYeCr.js → guides_migrate.md.B8CZxnnX.js} +1 -1
  74. package/dist/docs/assets/{guides_slack.md.BgIGG9ur.js → guides_slack.md.D7Rwyva4.js} +1 -1
  75. package/dist/docs/assets/{hillclimbing.md.3TkdF79A.js → hillclimbing.md.M51bF-oT.js} +1 -1
  76. package/dist/docs/assets/index.md.DnJPj_B6.js +14 -0
  77. package/dist/docs/assets/index.md.DnJPj_B6.lean.js +1 -0
  78. package/dist/docs/assets/{reference_agent-config.md.C0Tp_Fk9.js → reference_agent-config.md.Bbqf0lgS.js} +13 -5
  79. package/dist/docs/assets/{reference_agent-config.md.C0Tp_Fk9.lean.js → reference_agent-config.md.Bbqf0lgS.lean.js} +1 -1
  80. package/dist/docs/assets/{reference_cli.md.B8GdpaRj.js → reference_cli.md.DHm6DmYk.js} +2 -2
  81. package/dist/docs/assets/{reference_hooks.md.CSWmOwMM.js → reference_hooks.md.vbIM394-.js} +2 -2
  82. package/dist/docs/assets/{reference_hooks.md.CSWmOwMM.lean.js → reference_hooks.md.vbIM394-.lean.js} +1 -1
  83. package/dist/docs/assets/{reference_tools.md.B2OaR1Nb.js → reference_tools.md.BhqW6neF.js} +4 -2
  84. package/dist/docs/assets/{reference_tools.md.B2OaR1Nb.lean.js → reference_tools.md.BhqW6neF.lean.js} +1 -1
  85. package/dist/docs/building-with-agents.html +36 -36
  86. package/dist/docs/building-with-agents.md +3 -3
  87. package/dist/docs/changelog.html +36 -36
  88. package/dist/docs/changelog.md +44 -1
  89. package/dist/docs/deployment.html +37 -37
  90. package/dist/docs/deployment.md +22 -16
  91. package/dist/docs/evals.html +35 -35
  92. package/dist/docs/guides/agent-to-agent.html +37 -37
  93. package/dist/docs/guides/agent-to-agent.md +4 -2
  94. package/dist/docs/guides/bitbucket.html +35 -35
  95. package/dist/docs/guides/cloud-agents.html +35 -35
  96. package/dist/docs/guides/convert-automation.html +35 -35
  97. package/dist/docs/guides/github.html +37 -37
  98. package/dist/docs/guides/github.md +1 -1
  99. package/dist/docs/guides/gitlab.html +35 -35
  100. package/dist/docs/guides/improve.html +35 -35
  101. package/dist/docs/guides/jev.html +35 -35
  102. package/dist/docs/guides/mcp-oauth.html +37 -37
  103. package/dist/docs/guides/mcp-oauth.md +1 -1
  104. package/dist/docs/guides/migrate.html +37 -37
  105. package/dist/docs/guides/migrate.md +1 -1
  106. package/dist/docs/guides/opentelemetry.html +35 -35
  107. package/dist/docs/guides/pagerduty.html +35 -35
  108. package/dist/docs/guides/slack.html +37 -37
  109. package/dist/docs/guides/slack.md +1 -1
  110. package/dist/docs/guides/webhooks.html +35 -35
  111. package/dist/docs/hashmap.json +1 -1
  112. package/dist/docs/hillclimbing.html +36 -36
  113. package/dist/docs/hillclimbing.md +1 -1
  114. package/dist/docs/index.html +42 -48
  115. package/dist/docs/index.md +8 -14
  116. package/dist/docs/llms-full.txt +176 -54
  117. package/dist/docs/quickstart.html +35 -35
  118. package/dist/docs/reference/access.html +35 -35
  119. package/dist/docs/reference/agent-config.html +47 -39
  120. package/dist/docs/reference/agent-config.md +75 -10
  121. package/dist/docs/reference/artifacts.html +35 -35
  122. package/dist/docs/reference/channels.html +35 -35
  123. package/dist/docs/reference/cli.html +38 -38
  124. package/dist/docs/reference/cli.md +2 -2
  125. package/dist/docs/reference/connections.html +35 -35
  126. package/dist/docs/reference/evals.html +35 -35
  127. package/dist/docs/reference/extensions.html +35 -35
  128. package/dist/docs/reference/hooks.html +37 -37
  129. package/dist/docs/reference/hooks.md +1 -1
  130. package/dist/docs/reference/http-api.html +35 -35
  131. package/dist/docs/reference/instructions.html +35 -35
  132. package/dist/docs/reference/limits.html +35 -35
  133. package/dist/docs/reference/memory.html +35 -35
  134. package/dist/docs/reference/playground.html +35 -35
  135. package/dist/docs/reference/project-layout.html +35 -35
  136. package/dist/docs/reference/schedules.html +35 -35
  137. package/dist/docs/reference/sessions.html +35 -35
  138. package/dist/docs/reference/skills.html +35 -35
  139. package/dist/docs/reference/subagents.html +35 -35
  140. package/dist/docs/reference/tools.html +39 -37
  141. package/dist/docs/reference/tools.md +12 -0
  142. package/dist/docs/templates/agentic-owners.html +35 -35
  143. package/dist/docs/templates/reviews.html +35 -35
  144. package/dist/docs/troubleshooting.html +35 -35
  145. package/dist/filesystem.d.ts +12 -412
  146. package/dist/filesystem.d.ts.map +1 -1
  147. package/dist/filesystem.js +37 -980
  148. package/dist/index.d.ts +1 -3
  149. package/dist/index.d.ts.map +1 -1
  150. package/dist/index.js +1 -3
  151. package/dist/internal/authored-alias-hooks.d.ts +6 -0
  152. package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
  153. package/dist/internal/authored-alias-hooks.js +12 -0
  154. package/dist/internal/authored-loaders.js +10 -1
  155. package/dist/internal/cli/commands/scaffold.js +1 -1
  156. package/dist/internal/continuation-channel.d.ts +3 -3
  157. package/dist/internal/continuation-channel.js +3 -3
  158. package/dist/internal/continuation-identity.d.ts +6 -5
  159. package/dist/internal/continuation-identity.d.ts.map +1 -1
  160. package/dist/internal/continuation-identity.js +17 -2
  161. package/dist/internal/continuation-session-ids.d.ts +15 -0
  162. package/dist/internal/continuation-session-ids.d.ts.map +1 -0
  163. package/dist/internal/continuation-session-ids.js +43 -0
  164. package/dist/internal/direct-file-tools.d.ts +21 -0
  165. package/dist/internal/direct-file-tools.d.ts.map +1 -0
  166. package/dist/internal/direct-file-tools.js +60 -0
  167. package/dist/internal/discovery/agent.d.ts.map +1 -1
  168. package/dist/internal/discovery/agent.js +71 -66
  169. package/dist/internal/filesystem/walk.d.ts +4 -56
  170. package/dist/internal/filesystem/walk.d.ts.map +1 -1
  171. package/dist/internal/filesystem/walk.js +4 -198
  172. package/dist/internal/hosted-catch-protocol.d.ts +3 -3
  173. package/dist/internal/hosted-catch-protocol.js +3 -3
  174. package/dist/internal/hosted-fetch.d.ts +7 -0
  175. package/dist/internal/hosted-fetch.d.ts.map +1 -0
  176. package/dist/internal/hosted-fetch.js +26 -0
  177. package/dist/internal/hosted-managed-automation.js +1 -1
  178. package/dist/internal/install-cursor-skills.d.ts +5 -6
  179. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  180. package/dist/internal/install-cursor-skills.js +19 -4
  181. package/dist/internal/mcp-endpoint.js +4 -4
  182. package/dist/internal/model-config.d.ts.map +1 -1
  183. package/dist/internal/model-config.js +11 -4
  184. package/dist/internal/otel/http.d.ts +2 -1
  185. package/dist/internal/otel/http.d.ts.map +1 -1
  186. package/dist/internal/otel/http.js +2 -3
  187. package/dist/internal/platform-timers.d.ts +3 -7
  188. package/dist/internal/platform-timers.d.ts.map +1 -1
  189. package/dist/internal/platform-timers.js +10 -51
  190. package/dist/internal/sdk-runner.d.ts.map +1 -1
  191. package/dist/internal/sdk-runner.js +22 -40
  192. package/dist/internal/server.d.ts.map +1 -1
  193. package/dist/internal/server.js +6 -1
  194. package/dist/internal/session-engine.d.ts +36 -19
  195. package/dist/internal/session-engine.d.ts.map +1 -1
  196. package/dist/internal/session-engine.js +182 -254
  197. package/dist/internal/tool-paths.d.ts +8 -0
  198. package/dist/internal/tool-paths.d.ts.map +1 -0
  199. package/dist/internal/tool-paths.js +12 -0
  200. package/dist/internal/workspace-tree.d.ts +27 -0
  201. package/dist/internal/workspace-tree.d.ts.map +1 -0
  202. package/dist/internal/workspace-tree.js +106 -0
  203. package/dist/playground/assets/index-D0-FHg1x.css +1 -0
  204. package/dist/playground/assets/index-D5SLKUy6.js +62 -0
  205. package/dist/playground/index.html +2 -2
  206. package/dist/types.d.ts +43 -23
  207. package/dist/types.d.ts.map +1 -1
  208. package/dist/types.js +2 -2
  209. package/docs/README.md +8 -14
  210. package/docs/building-with-agents.md +3 -3
  211. package/docs/changelog.md +44 -1
  212. package/docs/deployment.md +22 -16
  213. package/docs/guides/agent-to-agent.md +4 -2
  214. package/docs/guides/github.md +1 -1
  215. package/docs/guides/mcp-oauth.md +1 -1
  216. package/docs/guides/migrate.md +1 -1
  217. package/docs/guides/slack.md +1 -1
  218. package/docs/hillclimbing.md +1 -1
  219. package/docs/reference/agent-config.md +75 -10
  220. package/docs/reference/cli.md +2 -2
  221. package/docs/reference/hooks.md +1 -1
  222. package/docs/reference/tools.md +12 -0
  223. package/package.json +10 -15
  224. package/skills/cli/SKILL.md +1 -1
  225. package/skills/create-agent/SKILL.md +61 -7
  226. package/skills/debug/SKILL.md +1 -1
  227. package/skills/deploy/SKILL.md +3 -3
  228. package/skills/evals/SKILL.md +1 -1
  229. package/skills/framework-map/SKILL.md +2 -2
  230. package/skills/github/SKILL.md +1 -1
  231. package/skills/hillclimb/SKILL.md +1 -1
  232. package/skills/mcp-auth/SKILL.md +1 -1
  233. package/skills/migrate-v2/SKILL.md +2 -2
  234. package/skills/otel/SKILL.md +1 -1
  235. package/skills/setup-slack/SKILL.md +2 -2
  236. package/dist/docs/assets/changelog.md.BWhC6DET.js +0 -1
  237. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +0 -1
  238. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +0 -1
  239. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +0 -1
  240. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +0 -1
  241. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +0 -1
  242. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +0 -1
  243. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +0 -1
  244. package/dist/docs/assets/chunks/wardley-RL74JXVD.BxFEFYZS.js +0 -162
  245. package/dist/docs/assets/index.md.DRfaoRCZ.js +0 -20
  246. package/dist/docs/assets/index.md.DRfaoRCZ.lean.js +0 -1
  247. package/dist/executors.d.ts +0 -11
  248. package/dist/executors.d.ts.map +0 -1
  249. package/dist/executors.js +0 -21
  250. package/dist/internal/filesystem/errors.d.ts +0 -64
  251. package/dist/internal/filesystem/errors.d.ts.map +0 -1
  252. package/dist/internal/filesystem/errors.js +0 -180
  253. package/dist/internal/filesystem/format.d.ts +0 -28
  254. package/dist/internal/filesystem/format.d.ts.map +0 -1
  255. package/dist/internal/filesystem/format.js +0 -209
  256. package/dist/internal/filesystem/merge.d.ts +0 -34
  257. package/dist/internal/filesystem/merge.d.ts.map +0 -1
  258. package/dist/internal/filesystem/merge.js +0 -154
  259. package/dist/internal/filesystem/nearest.d.ts +0 -15
  260. package/dist/internal/filesystem/nearest.d.ts.map +0 -1
  261. package/dist/internal/filesystem/nearest.js +0 -90
  262. package/dist/internal/filesystem/scratch.d.ts +0 -60
  263. package/dist/internal/filesystem/scratch.d.ts.map +0 -1
  264. package/dist/internal/filesystem/scratch.js +0 -187
  265. package/dist/internal/filesystem/sdk-schemas.d.ts +0 -29
  266. package/dist/internal/filesystem/sdk-schemas.d.ts.map +0 -1
  267. package/dist/internal/filesystem/sdk-schemas.js +0 -148
  268. package/dist/internal/filesystem/subagent-inherit.d.ts +0 -39
  269. package/dist/internal/filesystem/subagent-inherit.d.ts.map +0 -1
  270. package/dist/internal/filesystem/subagent-inherit.js +0 -96
  271. package/dist/internal/filesystem/tools.d.ts +0 -59
  272. package/dist/internal/filesystem/tools.d.ts.map +0 -1
  273. package/dist/internal/filesystem/tools.js +0 -634
  274. package/dist/internal/otel/propagation.d.ts +0 -7
  275. package/dist/internal/otel/propagation.d.ts.map +0 -1
  276. package/dist/internal/otel/propagation.js +0 -15
  277. package/dist/internal/sdk-subagent-inherit-support.d.ts +0 -9
  278. package/dist/internal/sdk-subagent-inherit-support.d.ts.map +0 -1
  279. package/dist/internal/sdk-subagent-inherit-support.js +0 -90
  280. package/dist/playground/assets/index-D6mVn9og.js +0 -62
  281. package/dist/playground/assets/index-DlALM6gr.css +0 -1
  282. /package/dist/docs/assets/{building-with-agents.md.BqJ7AAjG.lean.js → building-with-agents.md.Bo3ct-rf.lean.js} +0 -0
  283. /package/dist/docs/assets/{guides_agent-to-agent.md.BcmSqL2z.lean.js → guides_agent-to-agent.md.DcB3nhOz.lean.js} +0 -0
  284. /package/dist/docs/assets/{guides_github.md.6jiEH7dg.lean.js → guides_github.md.CcuZ7keS.lean.js} +0 -0
  285. /package/dist/docs/assets/{guides_mcp-oauth.md.C-Sx_IPa.lean.js → guides_mcp-oauth.md.GVPMKcYl.lean.js} +0 -0
  286. /package/dist/docs/assets/{guides_migrate.md.BbhHYeCr.lean.js → guides_migrate.md.B8CZxnnX.lean.js} +0 -0
  287. /package/dist/docs/assets/{guides_slack.md.BgIGG9ur.lean.js → guides_slack.md.D7Rwyva4.lean.js} +0 -0
  288. /package/dist/docs/assets/{hillclimbing.md.3TkdF79A.lean.js → hillclimbing.md.M51bF-oT.lean.js} +0 -0
  289. /package/dist/docs/assets/{reference_cli.md.B8GdpaRj.lean.js → reference_cli.md.DHm6DmYk.lean.js} +0 -0
@@ -14,13 +14,13 @@ To let a running agent change its own source, see the [self-improvement extensio
14
14
 
15
15
  ## Create an agent from a goal
16
16
 
17
- Tell the coding agent what the agent is for and where people reach it, and ask it to follow the `bdk-create-agent` skill. It asks for any decisions you haven't made, shows a file plan, and scaffolds a small first version with a smoke eval.
17
+ Tell the coding agent what the agent is for and where people reach it, and ask it to follow the `agent-sdk-create-agent` skill. It asks for any decisions you haven't made, shows a file plan, and scaffolds a small first version with a smoke eval.
18
18
 
19
19
  ## Add one capability
20
20
 
21
- For an existing project, name the outcome and point the coding agent at the matching skill, such as `bdk-setup-slack`, `bdk-mcp-auth`, or `bdk-github`. For example:
21
+ For an existing project, name the outcome and point the coding agent at the matching skill, such as `agent-sdk-setup-slack`, `agent-sdk-mcp-auth`, or `agent-sdk-github`. For example:
22
22
 
23
- > Add Slack mentions and DMs to this agent. Follow the bdk-setup-slack
23
+ > Add Slack mentions and DMs to this agent. Follow the agent-sdk-setup-slack
24
24
  > skill, keep replies in the source thread, and verify one local mention.
25
25
 
26
26
  > Connect the private inventory MCP server with host OAuth. Keep its
@@ -54,7 +54,50 @@ Source: /docs/changelog.md
54
54
 
55
55
  # Changelog
56
56
 
57
- ## 0.3.0 (2026-10-23)
57
+ ## 0.5.0 (2026-10-28)
58
+
59
+ ### Breaking changes
60
+
61
+ - No change to which file tools an `fs` agent has or what they do. Their results now use Cursor's native tool-call shape instead of Agent SDK's earlier MCP-style text, in `tool_call` events, transcripts, and direct tool calls. The same holds without `fs`. Update code that parses these results. For example, a direct `read` call returns `{ status: "success", value: { content } }` instead of numbered lines.
62
+ - With `fs`, a `tools` list gets only the file tools it names. Add `"read"`, `"ls"`, `"glob"`, `"grep"`, `"edit"`, and `"delete"` to keep them.
63
+ - `@grok/agent-sdk/executors` is removed. Remove that import. The npm package has no replacement.
64
+ - `synthesizeFileSystemTools` is removed. Pass your tree as `fs`.
65
+ - `nearestNeighborMissHint` is removed. Read suggests nearby names when a file is missing.
66
+ - `RunnerTurnRequest` carries `fs`, `reportedWorkspacePath`, and `settingSources` instead of `root` and `subagentInherit`.
67
+
68
+ ### Behavior changes
69
+
70
+ - With `fs`, `AGENTS.md` and `.cursor/rules/` in the workspace load as project rules, as they do on the host. Don't make a checkout you don't trust the workspace.
71
+ - With `fs`, omitting `tools` gives every tool the tree can back, including subagents, web search, web fetch, todos, and MCP.
72
+ - With `fs`, a `tools` list that names a tool the tree can't run, such as `readLints`, leaves it out with a warning. Before, `readLints` with `fs` failed validation.
73
+ - With `fs`, LS, Grep, and Glob search the workspace when a call names no path.
74
+ - With `fs`, each turn gets an empty `/tmp`. Large web results are written there.
75
+ - With `fs`, subagents work on the agent's tree, and their writes land in it as the agent's own do. Before, each subagent wrote to its own copy.
76
+ - `local.sandbox` works with `fs`. A tool call that needs approval, such as an external MCP call, fails closed. File access doesn't change.
77
+ - With `local.sandbox` and no `fs`, an agent with shell in `tools`, or with `tools` omitted, can read outside the session workspace with the file tools, as its shell already could. Writes and deletes outside it are still refused.
78
+ - With `local.sandbox` and no `fs`, an agent whose `tools` list file tools and no shell runs on its session workspace, mounted at `/workspace`, and its reads stay inside it. Cursor hooks don't run for it, so a Slack follow-up waits for the turn to end. `.cursor/mcp.json` from its working directory isn't loaded, host git status doesn't reach the model, and its skills are at `/agent/skills`.
79
+ - An agent tool can be named `Read`, `Grep`, or another file tool's name.
80
+
81
+ ### New
82
+
83
+ - `workspace` sets the folder inside `fs` that the agent works in. For a sandboxed agent without shell, it sets where the session workspace is mounted.
84
+
85
+ ### Fixes
86
+
87
+ - An agent that exports OpenTelemetry traces no longer logs a duplicate propagator registration error on its first HTTP request.
88
+
89
+ ## 0.4.0 (2026-10-27)
90
+
91
+ ### Breaking changes
92
+
93
+ - The `FileSystem` type, its helpers, and its errors match the file tools, and the package root exports `readOnlyFs`.
94
+
95
+ ### Fixes
96
+
97
+ - A reply in a Slack thread that a schedule started continues that session.
98
+ - A hosted Slack agent with `botMentions.allowFrom` starts a session when an allowed bot mentions it.
99
+
100
+ ## 0.3.0 (2026-10-25)
58
101
 
59
102
  - GA Release
60
103
  - `persistent` option is removed from `defineAgent`
@@ -155,22 +198,28 @@ fails on a literal or a getter.
155
198
 
156
199
  Write each egress host as a lowercase hostname with no scheme or path, such as `api.example.com`, and add a port such as `clickhouse.example.com:9440` only for raw TCP. `agent-sdk deploy` rejects any other form, and the error quotes that host.
157
200
 
158
- Your team's egress policy limits which hosts you can list in
159
- `hosting.egressDomains`. If you list a host that the policy blocks,
160
- `agent-sdk deploy` fails and the error names that host. A deployment that
161
- is already running keeps the policy from its last successful deploy. Ask a
162
- team admin to add the host, or remove it and deploy again.
163
-
164
- | Team egress mode | What `agent-sdk deploy` allows |
165
- | --- | --- |
166
- | No mode set | Every host in `hosting.egressDomains`. |
167
- | Allow all network access | Every host in `hosting.egressDomains`. The bot stays limited to that list. |
168
- | Defaults + team allowlist | The platform default list, plus the team list. |
169
- | Team allowlist only | The team list. |
170
-
171
- No team list can remove the platform base, which includes Cursor's API and
172
- the npm registry. `agent-sdk deploy --json` lists every allowed host under
173
- `egress.effective`.
201
+ ### How egress works
202
+
203
+ A deployed agent can only reach hosts on its egress list. A call to any other
204
+ host fails, usually as a connection reset or a 403 from the proxy. Here's how
205
+ the egress allowlist gets built:
206
+
207
+ 1. **Agent SDK Platform Egress:** Some hosts are required for the Agent SDK to
208
+ work, including the Cursor API.
209
+ 2. **Your Agent's Egress:** The hosts defined in `hosting.egressDomains`, plus
210
+ any hosts that your mounted extensions add. If your Cursor team enables the
211
+ team-wide egress policy, then each of these hosts must also be on the
212
+ team's egress allowlist. If one isn't, `agent-sdk deploy` fails and names
213
+ the host, and the agent that's already running doesn't change.
214
+ 3. **Channel Egress:** Each channel adds the hosts it needs by itself, and the
215
+ team allowlist doesn't apply to them. A Slack app adds `slack.com` and
216
+ `files.slack.com`. A GitHub or GitLab binding on a self-hosted instance
217
+ adds that host. MCP connections don't add anything, so be sure to declare
218
+ their hosts yourself in `hosting.egressDomains`.
219
+
220
+ Cursor saves your agent's list when you deploy, so an egress change only takes
221
+ effect after you deploy again. To check your declared and extension hosts
222
+ first, run `agent-sdk info --dir .`.
174
223
 
175
224
  A team entry `*.example.com` allows `example.com`, every subdomain, and
176
225
  narrower wildcards such as `*.api.example.com`. An agent entry
@@ -474,8 +523,10 @@ await ctx.host.mcp.callTool("weather", "ask", {
474
523
  });
475
524
  ```
476
525
 
477
- If the specialist is still working, `ask` returns `status: "running"`, and
478
- `check` waits for the answer.
526
+ If the specialist is still working, `ask` returns `status: "running"` and a
527
+ `sessionId`. Do not end your turn. Call `check` with that `sessionId` until
528
+ the status is `completed`. Ending your turn drops the reply, because nothing
529
+ else delivers it when the specialist finishes.
479
530
 
480
531
  ```ts
481
532
  await ctx.host.mcp.callTool("weather", "check", {
@@ -1229,7 +1280,7 @@ Pass each credential as `{ secretName: "NAME" }`. When you run locally, the chan
1229
1280
  ## Related
1230
1281
 
1231
1282
  - [Build a PR reviewer](/docs/quickstart.md) covers the full loop.
1232
- - Ask a coding agent to follow the `bdk-github` skill for the GitHub setup steps.
1283
+ - Ask a coding agent to follow the `agent-sdk-github` skill for the GitHub setup steps.
1233
1284
 
1234
1285
  ---
1235
1286
 
@@ -1839,7 +1890,7 @@ gives each caller its own downstream identity.
1839
1890
 
1840
1891
  ## Related
1841
1892
 
1842
- - Follow the `bdk-mcp-auth` skill, then run `agent-sdk mcp oauth <connection>`.
1893
+ - Follow the `agent-sdk-mcp-auth` skill, then run `agent-sdk mcp oauth <connection>`.
1843
1894
  - [MCP connections](/docs/reference/connections.md)
1844
1895
 
1845
1896
  ---
@@ -1891,7 +1942,7 @@ agent-sdk migrate --dir .
1891
1942
  To migrate a pushed source outside your checkout, pass `--repo`, `--ref`, and
1892
1943
  `--path`. The [CLI reference](/docs/reference/cli.md#migrate) lists every flag.
1893
1944
 
1894
- You can also ask a coding agent in your checkout to follow the bundled `bdk-migrate-v2` skill. If the project
1945
+ You can also ask a coding agent in your checkout to follow the bundled `agent-sdk-migrate-v2` skill. If the project
1895
1946
  relies on a v1 capability that has no v2 path, the agent stops and names the
1896
1947
  blocker.
1897
1948
 
@@ -2551,7 +2602,7 @@ The person who runs `slack create` grants Cursor three user scopes on their own
2551
2602
  create and install the app, and `botScopes` doesn't change them.
2552
2603
 
2553
2604
  If you already own the Slack app, run `agent-sdk slack init --manual --dir . --name "Triage"` and
2554
- follow the `bdk-setup-slack` skill for installation and tokens.
2605
+ follow the `agent-sdk-setup-slack` skill for installation and tokens.
2555
2606
 
2556
2607
  ---
2557
2608
 
@@ -2793,7 +2844,7 @@ Source: /docs/hillclimbing.md
2793
2844
  Hillclimbing improves an agent one measured change at a time. Hold the inputs fixed, change one
2794
2845
  thing, and keep it only when the same run gets better without moving the behavior you froze.
2795
2846
 
2796
- A coding agent in your checkout can run this loop by following the `bdk-hillclimb` skill.
2847
+ A coding agent in your checkout can run this loop by following the `agent-sdk-hillclimb` skill.
2797
2848
 
2798
2849
  ## Run one measured round
2799
2850
 
@@ -2879,27 +2930,21 @@ manage it.
2879
2930
 
2880
2931
  ## Get Started with your Coding Agent
2881
2932
 
2882
- Paste this prompt into your coding agent. It installs the CLI, asks what your agent is for, and
2883
- scaffolds a first project from the Markdown version of these docs.
2933
+ Paste this prompt into your coding agent. It installs the CLI, asks what your agent is for,
2934
+ scaffolds and checks a first project, and tells you how to test and deploy it.
2884
2935
 
2885
2936
  ```text
2886
2937
  Set up my first Agent SDK project.
2887
2938
 
2888
- Read https://cursor.com/docs/agent-sdk.md first. Every page under
2889
- https://cursor.com/docs/agent-sdk/ is also available as Markdown when you
2890
- add .md to its URL.
2939
+ Read https://cursor.com/docs/agent-sdk.md. Add .md to any page under
2940
+ https://cursor.com/docs/agent-sdk/ to read it as Markdown.
2891
2941
 
2892
2942
  1. Check that Node is 22.13 or newer, then run:
2893
2943
  npm install --global @grok/agent-sdk
2894
- 2. Read the docs index that ships with the package:
2895
- "$(npm root -g)/@grok/agent-sdk/dist/docs/llms.txt"
2896
- 3. Run agent-sdk login, and wait while I finish the browser sign-in.
2897
- 4. Ask me what the agent should do and where people will reach it. Then
2898
- follow the bdk-create-agent skill at
2899
- "$(npm root -g)/@grok/agent-sdk/skills/create-agent/SKILL.md"
2900
- to scaffold the project with agent-sdk init.
2901
- 5. Run agent-sdk validate --dir . and one agent-sdk run turn, then show me
2902
- the reply.
2944
+ 2. Follow the agent-sdk-create-agent skill at
2945
+ "$(npm root -g)/@grok/agent-sdk/skills/create-agent/SKILL.md".
2946
+ 3. Do not deploy or push until I ask. End by telling me what the agent
2947
+ does, how to test it locally, and how to deploy it.
2903
2948
  ```
2904
2949
 
2905
2950
  ## Why Agent SDK
@@ -3206,9 +3251,9 @@ import { defineAgent } from "@grok/agent-sdk";
3206
3251
 
3207
3252
  export default defineAgent({
3208
3253
  model: {
3209
- id: "grok-4.5",
3254
+ id: "grok-4.7",
3210
3255
  params: [
3211
- { id: "effort", value: "high" },
3256
+ { id: "reasoning_effort", value: "high" },
3212
3257
  { id: "fast", value: "true" },
3213
3258
  ],
3214
3259
  }, // optional; this is the default
@@ -3219,7 +3264,7 @@ export default defineAgent({
3219
3264
 
3220
3265
  | Field | Type | Meaning |
3221
3266
  | --- | --- | --- |
3222
- | `model` | string or `{ id, params }` | Cursor model for turns. Defaults to `grok-4.5` with `effort=high` and `fast=true`. Subagents omit it to inherit. |
3267
+ | `model` | string or `{ id, params }` | Cursor model for turns. Defaults to `grok-4.7` with `reasoning_effort=high` and `fast=true`. Subagents omit it to inherit. |
3223
3268
  | `name` | string | Display name. Defaults to the package or directory name. |
3224
3269
  | `description` | string | What the agent is for. Required on subagents, where the parent model reads it to decide when to delegate. |
3225
3270
  | `instructions` | string | Inline instructions for subagents and generated configs. Prefer `instructions.md`. |
@@ -3229,15 +3274,15 @@ export default defineAgent({
3229
3274
  | `builtinTools` | `{ reminders? }` | Opt-in tools that Agent SDK provides. See [Built-in tools](#built-in-tools). |
3230
3275
  | `tools` | `ToolName[]` | Allowlist of built-in tools. Omit it for the full standard toolset. See [Harness tools](#harness-tools). |
3231
3276
  | `fs` | `FileSystem` or `(ctx) => FileSystem` | Custom file tree for the session. `root` is the deprecated name. See [Custom filesystem](#custom-filesystem). |
3277
+ | `workspace` | string | With `fs`, the folder inside the tree the agent works in, and where project rules load from. Defaults to `/`. For a sandboxed agent without shell, where its session workspace is mounted, `/workspace` by default. |
3232
3278
  | `skills` | `false` or `(ctx) => FileSystem` | Replaces the skills tree mounted at `/agent/skills`, or turns that mount off. |
3233
3279
 
3234
3280
  The `persistent` field was removed. Discovery rejects a config that still sets it, and the error is `persistent was removed. Delete it from defineAgent.`, so `validate`, `dev`, and `deploy` fail until you delete the field. A deployment that is already running keeps serving until you stop or delete it.
3235
3281
 
3236
3282
  ## Model
3237
3283
 
3238
- Effort and speed are params, not id suffixes, so Agent SDK rejects an id like
3239
- `grok-4.5-fast`. Use the object form shown above to set params, or a plain
3240
- string when you don't need any:
3284
+ Set effort and speed with params, not in the id. Use the object form shown above
3285
+ to set params, or a plain string when you don't need any:
3241
3286
 
3242
3287
  ```ts
3243
3288
  model: "composer-2.5",
@@ -3257,10 +3302,34 @@ untrusted input, such as webhook payloads, PR diffs, or inbound chat. The
3257
3302
  sandbox limits the tools themselves, so an injected prompt can't talk the model
3258
3303
  past it.
3259
3304
 
3260
- Agent SDK runs the file tools (`read`, `edit`, `delete`, `grep`, `glob`, `ls`)
3261
- in the serve process, outside the sandbox. With `local.sandbox` on, they refuse
3262
- a path outside the session workspace with `Path is outside the workspace`. With
3263
- it off, they can reach any path the serve process can.
3305
+ With `local.sandbox` on, shell commands run without network access, writes and
3306
+ deletes outside the session workspace are refused, and a tool call that needs
3307
+ approval, such as an external MCP call, fails closed. What the agent can read
3308
+ depends on its `tools`:
3309
+
3310
+ - **With shell** (or with `tools` omitted, which includes it), the agent runs on
3311
+ the host disk. Shell commands and the file tools (`read`, `grep`, `glob`,
3312
+ `ls`) can read any file the serve process can, including credentials on the
3313
+ host.
3314
+ - **With file tools and no shell**, such as `tools: ["read", "grep"]`, the agent
3315
+ runs on its session workspace as a tree, mounted at `/workspace`. Set
3316
+ [`workspace`](#custom-filesystem) to mount it elsewhere. Every file tool sees
3317
+ only the workspace and refuses a path outside it, including through a
3318
+ symlink. Running on a tree also turns off what only the host disk provides:
3319
+ Cursor hooks don't run, so a Slack follow-up waits for the turn to end
3320
+ instead of reaching the running turn; `.cursor/mcp.json` from the workspace
3321
+ or an enclosing checkout isn't loaded (connections in `bot/` still are); host
3322
+ git status doesn't reach the model; and skills are at `/agent/skills`
3323
+ instead of `.cursor/skills`. `AGENTS.md` and `.cursor/rules/` in the
3324
+ workspace still load. Tools a tree can't run, such as `readLints`, are left
3325
+ out with a warning.
3326
+
3327
+ To keep an agent's reads inside a tree you choose, give it
3328
+ [`fs`](#custom-filesystem) instead.
3329
+
3330
+ A [direct tool call](/docs/reference/tools.md#call-a-tool-without-a-model-turn) on a
3331
+ host-disk agent refuses a path outside the session workspace, after symlinks,
3332
+ with `Path is outside the workspace`, whether or not `local.sandbox` is on.
3264
3333
 
3265
3334
  ### Local cwd
3266
3335
 
@@ -3277,8 +3346,49 @@ at a checkout only when the agent should inherit that tree.
3277
3346
 
3278
3347
  ## Custom filesystem
3279
3348
 
3349
+ Set `fs` and the agent's file tools (Read, Write, StrReplace, LS, Grep, Glob,
3350
+ Delete) and its subagents work on your tree instead of the host disk. Build it
3351
+ with `tempFs`, `unionFs`, `overlayFs`, `readOnlyFs`, or your own `FileSystem`.
3352
+
3353
+ ```ts
3354
+ import { defineAgent, readOnlyFs, tempFs, unionFs } from "@grok/agent-sdk";
3355
+
3356
+ export default defineAgent({
3357
+ fs: unionFs({
3358
+ "/repo": readOnlyFs(repoFs),
3359
+ "/notes": tempFs({ "/todo.md": "- check the rollout" }),
3360
+ }),
3361
+ workspace: "/repo",
3362
+ });
3363
+ ```
3364
+
3280
3365
  `fs` is mounted at `/`, and Agent SDK mounts `/tmp` and `/agent/skills` over it. Set `fs` or the deprecated `root`, not both. A tree that already has `/agent/skills` fails session start unless `skills` is `false`.
3281
3366
 
3367
+ Each turn gets an empty `/tmp`, and large web results land there. Write anything
3368
+ the next turn needs elsewhere in the tree. Subagents work on the same tree, so
3369
+ their writes are visible to the agent right away, as subagents share the host
3370
+ workspace without `fs`.
3371
+
3372
+ `workspace` is the folder the model works in. Relative paths resolve against
3373
+ it, and LS, Grep, and Glob search it when a call names no path. It must be an
3374
+ absolute path outside `/tmp`, and defaults to `/`.
3375
+
3376
+ As on the host, the workspace's `AGENTS.md` and `.cursor/rules/` load as
3377
+ project rules. Don't make a checkout you don't trust, such as a pull request
3378
+ under review, the workspace. Mount it beside the workspace instead, for example
3379
+ at `/repo` with `workspace` left at `/`, where its rules don't load.
3380
+
3381
+ An `fs` agent has no shell, and listing `"shell"` in `tools` fails validation.
3382
+ Tools a tree can't run, such as `readLints` or `computerUse`, are left out: an
3383
+ omitted `tools` never includes them, and a `tools` list that names them gets a
3384
+ warning. A `tools` list gets only the file tools it names. Omit `tools` to get
3385
+ all of them. `fs` works on local turns only.
3386
+
3387
+ With `fs`, `local.sandbox` only affects approvals: a tool call that needs
3388
+ approval, such as an external MCP call, fails closed, as it does without `fs`.
3389
+ It changes nothing about file access, because the file tools already see only
3390
+ the tree.
3391
+
3282
3392
  ## Harness tools
3283
3393
 
3284
3394
  Use `tools` to limit which built-in Cursor tools the model can call.
@@ -3994,7 +4104,7 @@ agent-sdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]
3994
4104
 
3995
4105
  `migrate` applies only to projects that deployed with `architecture: "v1"`
3996
4106
  during the early alpha. It starts a Cursor cloud agent on a pushed Git ref
3997
- with the bundled `bdk-migrate-v2` skill, and the agent opens a pull request
4107
+ with the bundled `agent-sdk-migrate-v2` skill, and the agent opens a pull request
3998
4108
  with the source changes. The command never deploys or changes secrets.
3999
4109
 
4000
4110
  With nothing to change, it prints `Nothing to migrate.` and exits `0`, and it exits `1` if the run ends without a pull request. `deploy` refuses a project that sets `architecture: "v1"` and points to `migrate`. See [Migrate an early-alpha project](/docs/guides/migrate.md).
@@ -4006,7 +4116,7 @@ agent-sdk skills install [--dry-run] [--json]
4006
4116
  agent-sdk skills list [--json [--fields <a,b.c>]] [--limit <n>] [--page-token <token>]
4007
4117
  ```
4008
4118
 
4009
- Package installation copies the bundled skills, `skills install` replaces the installed copies and removes stale ones, and `skills list` prints each skill's bundled and installed versions. The `bdk-cli` skill teaches agents to run `agent-sdk` safely.
4119
+ Package installation copies the bundled skills, `skills install` replaces the installed copies and removes stale ones, and `skills list` prints each skill's bundled and installed versions. The `agent-sdk-cli` skill teaches agents to run `agent-sdk` safely.
4010
4120
 
4011
4121
  ### Inspect a project {#info}
4012
4122
 
@@ -5064,7 +5174,7 @@ Keys are event types from the [event vocabulary](/docs/reference/sessions.md#str
5064
5174
  | --- | --- |
5065
5175
  | `message.received` | `{ text }` |
5066
5176
  | `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
5067
- | `turn.failed` | `{ message, status? }`. `status` is `"error"` or `"cancelled"` when present |
5177
+ | `turn.failed` | `{ message, status?, code? }`. `status` is `"error"` or `"cancelled"` when present. `code` is the runner's stable error code, such as a Cursor SDK `RunError.code`, when the failure supplied one |
5068
5178
  | `actions.requested` | `{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }`. One envelope per model step. `parentCallId` marks subagent work |
5069
5179
  | `actions.completed` | `{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }`. Emitted when every call in that batch has a result |
5070
5180
  | `action.result` | `{ callId, toolName, output?, isError, stubbed?, parentCallId? }`. Live per-call envelope. `stubbed` means a dry-run session answered a write without running it |
@@ -6207,6 +6317,18 @@ agent-sdk tool call inspect_pr --dir . \
6207
6317
  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
6208
6318
  ```
6209
6319
 
6320
+ The built-in file tools run the same way: `Read`, `Write`, `StrReplace`,
6321
+ `LS`, `Grep`, `Glob`, and `Delete`, on the agent's `fs` tree or on the
6322
+ session workspace. Your `tools` allowlist applies, and the result is the
6323
+ tool's own result, the same one a turn's tool-call event carries. A read
6324
+ returns `{ "status": "success", "value": { "content": "…" } }`.
6325
+
6326
+ ```bash
6327
+ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/Read \
6328
+ -H 'content-type: application/json' \
6329
+ -d '{"input":{"path":"README.md"},"sessionId":"<session>"}'
6330
+ ```
6331
+
6210
6332
  Programmatically, `callTool(toolName, input, options?)` is available on
6211
6333
  the serve handle, on channel route handlers and `onStart` args, and on
6212
6334
  schedule `run` handlers, so a channel can mix deterministic calls with