@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
@@ -1,114 +1,21 @@
1
1
  import { Buffer } from "node:buffer";
2
2
  import { lstat, mkdir, readdir, readFile, readlink, realpath, rm, stat, writeFile, } from "node:fs/promises";
3
3
  import path from "node:path";
4
+ import { FileNotFoundError, InvalidGrepPatternError, PathError, unionFs, WriteFailedError, } from "@cursor/sdk";
4
5
  import { minimatch } from "minimatch";
5
6
  import { FileConflictError } from "./files.js";
6
- import { EditError, FileNotFoundError, InvalidGrepPatternError, isFileNotFoundError, isInvalidGrepPatternError, NoMountError, PathError, ReadOnlyMountError, remapPathError, WriteFailedError, } from "./internal/filesystem/errors.js";
7
7
  import { MEMORY_DIR_NAME } from "./internal/memory-dir.js";
8
- export { DeleteNotSupportedError, EditError, FileNotFoundError, InvalidGrepPatternError, isFileNotFoundError, isInvalidGrepPatternError, NoMountError, PathError, ReadOnlyMountError, WriteFailedError, } from "./internal/filesystem/errors.js";
9
- import { mergeSorted } from "./internal/filesystem/merge.js";
10
- import { isExcludedPath, listFilesFromPaths, mergeSortedByPath, statFromFilePaths, } from "./internal/filesystem/walk.js";
11
- /**
12
- * Default scan cap for synthesized LS / Glob and for Origin
13
- * `ListRepoPaths` from `/repo`. Smaller than Origin's 10k default
14
- * so a recursive listing does not materialize a huge response.
15
- */
16
- export const FILE_SYSTEM_SCAN_LIMIT = 1_000;
17
- export const FILE_SYSTEM_TOOL_NAMES = [
18
- "Read",
19
- "LS",
20
- "Glob",
21
- "Grep",
22
- "Write",
23
- "StrReplace",
24
- "Delete",
25
- ];
26
- const FILE_SYSTEM_TOOL_NAME_SET = new Set(FILE_SYSTEM_TOOL_NAMES);
27
- const FILE_SYSTEM_TOOL_ALIASES = {
28
- read: "Read",
29
- Read: "Read",
30
- ls: "LS",
31
- LS: "LS",
32
- glob: "Glob",
33
- Glob: "Glob",
34
- grep: "Grep",
35
- Grep: "Grep",
36
- write: "Write",
37
- Write: "Write",
38
- edit: "StrReplace",
39
- StrReplace: "StrReplace",
40
- delete: "Delete",
41
- Delete: "Delete",
42
- };
43
- export function canonicalizeFileSystemToolName(name) {
44
- return FILE_SYSTEM_TOOL_ALIASES[name];
45
- }
46
- export function isFileSystemToolName(name) {
47
- return FILE_SYSTEM_TOOL_NAME_SET.has(name);
48
- }
49
- export function isFileSystemToolAlias(name) {
50
- return canonicalizeFileSystemToolName(name) !== undefined;
51
- }
52
- /** Direct `callTool` names that mutate the tree and must wait on a busy turn. */
53
- export function isMutatingFileSystemTool(name) {
54
- const canonical = canonicalizeFileSystemToolName(name);
55
- return canonical === "Write" || canonical === "StrReplace" || canonical === "Delete";
56
- }
57
- export function isFileSystemMethodPresent(root, method) {
58
- return typeof root[method] === "function";
59
- }
60
- const ADVERTISED_FILE_SYSTEM_TOOL_NAMES = [
61
- "Read",
62
- "LS",
63
- "Glob",
64
- "Grep",
65
- "Write",
66
- "StrReplace",
67
- "Delete",
68
- ];
69
- export function fileSystemToolNames(_root) {
70
- return [...ADVERTISED_FILE_SYSTEM_TOOL_NAMES];
71
- }
72
- function fileSystemMethodForTool(name) {
73
- switch (name) {
74
- case "Read":
75
- return "read";
76
- case "LS":
77
- return "list";
78
- case "Glob":
79
- return "glob";
80
- case "Grep":
81
- return "grep";
82
- case "Write":
83
- case "StrReplace":
84
- return "write";
85
- case "Delete":
86
- return "delete";
87
- default: {
88
- const unexpected = name;
89
- return unexpected;
90
- }
91
- }
92
- }
93
- function fileSystemSatisfiesFileTool(root, name) {
94
- const canonical = canonicalizeFileSystemToolName(name);
95
- if (canonical === undefined) {
96
- return true;
97
- }
98
- const method = fileSystemMethodForTool(canonical);
99
- return method !== undefined && isFileSystemMethodPresent(root, method);
100
- }
8
+ import { hostPathFromToolPath } from "./internal/tool-paths.js";
9
+ import { isExcludedPath, listFilesFromPaths, statFromFilePaths, } from "./internal/filesystem/walk.js";
10
+ export { childOverlayFs, DeleteNotSupportedError, EditError, emptyFs, FILE_SYSTEM_SCAN_LIMIT, FileNotFoundError, InvalidGrepPatternError, isFileNotFoundError, isInvalidGrepPatternError, NoMountError, overlayFs, PathError, ReadOnlyMountError, readOnlyFs, remapPathError, strReplaceOnFileSystem, tempFs, unionFs, WriteFailedError, } from "@cursor/sdk";
101
11
  export class FileSystemConfigError extends Error {
102
12
  constructor(message) {
103
13
  super(message);
104
14
  this.name = "FileSystemConfigError";
105
15
  }
106
16
  }
107
- function allowlistHas(tools, ...names) {
108
- return tools.some((name) => names.includes(name));
109
- }
110
17
  /**
111
- * Native semantic-search built-in. Host-default turns disallow it.
18
+ * Native semantic-search built-in. Host-disk turns disallow it.
112
19
  * The name is assembled so a source search for the old spelling does not
113
20
  * treat this disallow list as a live tool.
114
21
  */
@@ -134,87 +41,23 @@ export function assertNoRemovedFileSearchTools(tools) {
134
41
  }
135
42
  throw new FileSystemConfigError(`Semantic search has been removed. Use Grep. \`tools\` lists ${listed.join(", ")}.`);
136
43
  }
137
- export function resolveRootHarnessAllowlist(tools) {
138
- assertNoRemovedFileSearchTools(tools);
139
- if (tools === undefined) {
140
- // File verbs are synthesized from the tree. Web tools are safe under the `/tmp` scratch
141
- // overlay. Todos are harness conversation state. `task`
142
- // children inherit filesystem executors and this allowlist.
143
- // Do not unlock shell.
144
- return ["webSearch", "webFetch", "updateTodos", "readTodos", "task", "mcp"];
145
- }
146
- if (allowlistHas(tools, "shell", "Shell")) {
147
- throw new FileSystemConfigError('`fs` cannot be combined with `tools` containing `"shell"`. ' +
148
- "Shell is not a FileSystem method and must not bind the host shell onto a virtual tree.");
149
- }
150
- if (allowlistHas(tools, "readLints", "ReadLints")) {
151
- throw new FileSystemConfigError("`fs` cannot list `readLints`: FileSystem has no diagnostics " +
152
- "verb, so the host language service would run against the real workspace.");
153
- }
154
- const extras = tools.filter((name) => !isFileSystemToolAlias(name));
155
- return withMcpGrant(extras);
156
- }
157
- export function resolveFileSystemTools(options) {
158
- const harness = resolveRootHarnessAllowlist(options.tools);
159
- if (options.tools === undefined) {
160
- return harness;
161
- }
162
- const implemented = fileSystemToolNames(options.root);
163
- const missing = [];
164
- for (const name of options.tools) {
165
- if (!fileSystemSatisfiesFileTool(options.root, name)) {
166
- missing.push(name);
167
- }
168
- }
169
- if (missing.length > 0) {
170
- throw new FileSystemConfigError(`\`tools\` names FileSystem method(s) that are not implemented: ${missing.join(", ")}. ` +
171
- `Implemented file tools: ${implemented.length > 0 ? implemented.join(", ") : "(none)"}.`);
172
- }
173
- return harness;
174
- }
175
44
  export function withMcpGrant(tools) {
176
45
  return tools.includes("mcp") ? [...tools] : [...tools, "mcp"];
177
46
  }
178
47
  /**
179
- * Native Cursor SDK file tools replaced by synthesized FileSystem tools
180
- * on every local turn. SDK allowlist names (`edit`, not `Write`).
181
- */
182
- export const REPLACED_NATIVE_FILE_TOOLS = [
183
- "read",
184
- "ls",
185
- "grep",
186
- "glob",
187
- "edit",
188
- "delete",
189
- removedNativeFileSearchTool(),
190
- ];
191
- /**
192
- * Host-default harness options: keep shell / webSearch / sandbox, but
193
- * hide the native file tools the synthesized FileSystem now owns.
194
- *
195
- * Omitted `tools` leaves the SDK default set and only excludes the
196
- * replaced natives. `[]` stays empty. A non-empty allowlist drops file
197
- * aliases (those ride synthesized tools) and grants `mcp`.
48
+ * Host-disk harness options. Omitted `tools` keeps the SDK default set
49
+ * without semantic search. `[]` stays empty. A non-empty allowlist
50
+ * grants `mcp`, which carries the agent's own server tools.
198
51
  */
199
52
  export function resolveHostHarnessToolOptions(tools) {
200
53
  if (tools === undefined) {
201
- return { disallowedTools: [...REPLACED_NATIVE_FILE_TOOLS] };
54
+ return { disallowedTools: [removedNativeFileSearchTool()] };
202
55
  }
203
56
  if (tools.length === 0) {
204
57
  return { tools: [] };
205
58
  }
206
59
  assertNoRemovedFileSearchTools(tools);
207
- return {
208
- tools: withMcpGrant(tools.filter((name) => !isReplacedHostFileAlias(name))),
209
- };
210
- }
211
- /** File aliases host-default synthesizes in place of the native tools. */
212
- function isReplacedHostFileAlias(name) {
213
- return canonicalizeFileSystemToolName(name) !== undefined;
214
- }
215
- /** Decode a {@link FileSystem.read} result as UTF-8 text. */
216
- export function fileSystemText(content) {
217
- return typeof content === "string" ? content : Buffer.from(content).toString("utf8");
60
+ return { tools: withMcpGrant(tools) };
218
61
  }
219
62
  /**
220
63
  * Native Read image formats. Magic bytes first, then extension.
@@ -263,16 +106,6 @@ export function detectImageMimeType(bytes, filePath) {
263
106
  }
264
107
  return undefined;
265
108
  }
266
- export function fileSystemImage(content, path) {
267
- if (!(content instanceof Uint8Array)) {
268
- return undefined;
269
- }
270
- const mimeType = detectImageMimeType(content, path);
271
- if (mimeType === undefined) {
272
- return undefined;
273
- }
274
- return { mimeType, bytes: content };
275
- }
276
109
  function compileGrepPattern(pattern, caseInsensitive, path = "/") {
277
110
  try {
278
111
  return new RegExp(pattern, caseInsensitive === true ? "i" : undefined);
@@ -310,104 +143,6 @@ async function* limitResults(source, maxResults) {
310
143
  }
311
144
  }
312
145
  }
313
- function grepPushdownLimit(query, opts) {
314
- // Count and files_with_matches paginate after grouping by file.
315
- // A line-level cap would hide later files once one file fills the window.
316
- if (opts.outputMode === "count" || opts.outputMode === "files_with_matches") {
317
- return query.maxResults;
318
- }
319
- const headLimit = opts.headLimit !== undefined && opts.headLimit > 0 ? opts.headLimit : undefined;
320
- if (headLimit === undefined) {
321
- return query.maxResults;
322
- }
323
- const toolCap = opts.offset + headLimit;
324
- return query.maxResults === undefined ? toolCap : Math.min(query.maxResults, toolCap);
325
- }
326
- function compareGrepResult(left, right) {
327
- return left.path < right.path
328
- ? -1
329
- : left.path > right.path
330
- ? 1
331
- : left.lineNumber - right.lineNumber;
332
- }
333
- export async function collectGrepMatches(root, query, opts) {
334
- const matches = [];
335
- const offset = opts.offset !== undefined && opts.offset > 0 ? opts.offset : 0;
336
- const headLimit = opts.headLimit !== undefined && opts.headLimit > 0 ? opts.headLimit : undefined;
337
- const skippedFiles = new Set();
338
- const acceptedFiles = new Set();
339
- let skippedItems = 0;
340
- let takenItems = 0;
341
- const pushdown = grepPushdownLimit(query, {
342
- outputMode: opts.outputMode,
343
- offset,
344
- ...(opts.headLimit === undefined ? {} : { headLimit: opts.headLimit }),
345
- });
346
- const grepQuery = pushdown === undefined ? query : { ...query, maxResults: pushdown };
347
- for await (const match of root.grep(grepQuery)) {
348
- if (opts.outputMode === "content") {
349
- if (skippedItems < offset) {
350
- skippedItems++;
351
- continue;
352
- }
353
- matches.push(match);
354
- takenItems++;
355
- if (headLimit !== undefined && takenItems >= headLimit) {
356
- break;
357
- }
358
- continue;
359
- }
360
- if (skippedFiles.has(match.path)) {
361
- continue;
362
- }
363
- if (!acceptedFiles.has(match.path)) {
364
- if (skippedItems < offset) {
365
- skippedFiles.add(match.path);
366
- skippedItems++;
367
- continue;
368
- }
369
- if (headLimit !== undefined && takenItems >= headLimit) {
370
- break;
371
- }
372
- acceptedFiles.add(match.path);
373
- takenItems++;
374
- }
375
- matches.push(match);
376
- }
377
- return matches;
378
- }
379
- export function shapeGrepUnion(matches, outputMode) {
380
- if (outputMode === "files_with_matches") {
381
- const files = [...new Set(matches.map((match) => match.path))];
382
- return { type: "files", output: { files, count: files.length } };
383
- }
384
- if (outputMode === "count") {
385
- const counts = new Map();
386
- for (const match of matches) {
387
- counts.set(match.path, (counts.get(match.path) ?? 0) + 1);
388
- }
389
- return {
390
- type: "count",
391
- output: {
392
- counts: [...counts].map(([file, count]) => ({ file, count })),
393
- total: matches.length,
394
- },
395
- };
396
- }
397
- return {
398
- type: "content",
399
- output: {
400
- matches: matches.map((match) => ({
401
- file: match.path,
402
- lineNumber: match.lineNumber,
403
- line: match.line,
404
- ...(match.beforeContext === undefined ? {} : { beforeContext: match.beforeContext }),
405
- ...(match.afterContext === undefined ? {} : { afterContext: match.afterContext }),
406
- })),
407
- totalMatches: matches.length,
408
- },
409
- };
410
- }
411
146
  export function normalizeFsPath(input) {
412
147
  const slashes = input.replace(/\\/g, "/");
413
148
  if (slashes === "") {
@@ -499,219 +234,6 @@ export async function writeWorkspaceFilesToRoot(root, files) {
499
234
  }
500
235
  }
501
236
  }
502
- function replaceLiteral(args) {
503
- if (args.replaceAll) {
504
- return args.existing.split(args.oldText).join(args.newText);
505
- }
506
- const index = args.existing.indexOf(args.oldText);
507
- if (index === -1) {
508
- return args.existing;
509
- }
510
- return (args.existing.slice(0, index) + args.newText + args.existing.slice(index + args.oldText.length));
511
- }
512
- function countNonOverlapping(haystack, needle) {
513
- let count = 0;
514
- let from = 0;
515
- while (from <= haystack.length - needle.length) {
516
- const index = haystack.indexOf(needle, from);
517
- if (index === -1) {
518
- break;
519
- }
520
- count++;
521
- from = index + needle.length;
522
- }
523
- return count;
524
- }
525
- /**
526
- * Exact, non-overlapping str-replace. Uniqueness is the FileSystem
527
- * contract: more than one match fails unless `replaceAll`.
528
- */
529
- function applyExactEdit(args) {
530
- if (args.oldText === "") {
531
- throw new EditError(args.path, "oldText is empty");
532
- }
533
- if (args.oldText === args.newText) {
534
- throw new EditError(args.path, "oldText and newText are exactly the same");
535
- }
536
- const occurrences = countNonOverlapping(args.existing, args.oldText);
537
- if (occurrences === 0) {
538
- throw new EditError(args.path, "The string to replace was not found in the file");
539
- }
540
- if (occurrences > 1 && !args.replaceAll) {
541
- throw new EditError(args.path, "The string to replace was found multiple times in the file. Use replace_all to replace all occurrences, or include more context to only edit one occurrence.");
542
- }
543
- return {
544
- contents: replaceLiteral({
545
- existing: args.existing,
546
- oldText: args.oldText,
547
- newText: args.newText,
548
- replaceAll: args.replaceAll,
549
- }),
550
- occurrencesModified: occurrences,
551
- };
552
- }
553
- /**
554
- * Exact str-replace as `read` + apply + `write`. Uniqueness is
555
- * this helper's contract; FileSystem implementations do not
556
- * implement edit. Native StrReplace calls this.
557
- */
558
- export async function strReplaceOnFileSystem(root, query) {
559
- const existing = await root.read(query.path);
560
- if (typeof existing !== "string") {
561
- throw new EditError(query.path, `${query.path} is not text`);
562
- }
563
- const applied = applyExactEdit({
564
- existing,
565
- oldText: query.oldText,
566
- newText: query.newText,
567
- replaceAll: query.replaceAll === true,
568
- path: query.path,
569
- });
570
- await root.write(query.path, applied.contents);
571
- return { occurrencesModified: applied.occurrencesModified };
572
- }
573
- /** Native Read offset/limit: 1-indexed, negative offset counts from the end. */
574
- export function sliceReadContent(content, offset, limit) {
575
- if (offset === undefined && limit === undefined) {
576
- return content;
577
- }
578
- const lines = content === "" ? [] : content.split("\n");
579
- const total = lines.length;
580
- const effectiveOffset = offset ?? 1;
581
- const effectiveLimit = limit ?? (effectiveOffset < 0 ? Math.abs(effectiveOffset) : total);
582
- const startIndex = effectiveOffset < 0 ? Math.max(0, total + effectiveOffset) : Math.max(0, effectiveOffset - 1);
583
- const endIndex = Math.min(total, startIndex + effectiveLimit);
584
- return lines.slice(startIndex, endIndex).join("\n");
585
- }
586
- async function* emptyStream() { }
587
- /**
588
- * A FileSystem with no files. Use as an overlay leaf or a missing
589
- * catalog so a miss stays {@link FileNotFoundError} instead of
590
- * {@link NoMountError}. Writes and deletes throw
591
- * {@link ReadOnlyMountError} — an empty tree is never a sink.
592
- */
593
- export function emptyFs() {
594
- return {
595
- list: () => emptyStream(),
596
- glob: () => emptyStream(),
597
- async *grep(query) {
598
- compileGrepPattern(query.pattern, query.caseInsensitive, query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path));
599
- yield* emptyStream();
600
- },
601
- async stat(path) {
602
- return statFromFilePaths([], path);
603
- },
604
- async read(path) {
605
- throw new FileNotFoundError(normalizeFsPath(path));
606
- },
607
- async write(path) {
608
- throw new ReadOnlyMountError(normalizeFsPath(path));
609
- },
610
- async delete(path) {
611
- throw new ReadOnlyMountError(normalizeFsPath(path));
612
- },
613
- };
614
- }
615
- /**
616
- * In-memory FileSystem for tests and fixtures. Keys are absolute
617
- * posix paths (`/a.txt`) and are normalized on ingest. Honors the
618
- * {@link FileSystem} order and path contracts.
619
- * Creates `/agent-tools` on first scratch
620
- * write the same way any other path is created.
621
- */
622
- export function tempFs(files = {}) {
623
- const store = new Map();
624
- for (const [path, content] of Object.entries(files)) {
625
- store.set(normalizeFsPath(path), content);
626
- }
627
- const listed = {
628
- list(prefix, options) {
629
- return listFilesFromPaths([...store.entries()].map(([filePath, content]) => ({
630
- path: filePath,
631
- size: typeof content === "string" ? content.length : content.byteLength,
632
- })), prefix, options);
633
- },
634
- async stat(path) {
635
- return statFromFilePaths(store.keys(), path);
636
- },
637
- };
638
- return {
639
- list(prefix, options) {
640
- return listed.list(prefix, options);
641
- },
642
- async stat(path) {
643
- return listed.stat(path);
644
- },
645
- async read(inputPath) {
646
- const path = normalizeFsPath(inputPath);
647
- const content = store.get(path);
648
- if (content === undefined) {
649
- throw new FileNotFoundError(path);
650
- }
651
- return content;
652
- },
653
- async *grep(query) {
654
- yield* limitResults(uncapped(), query.maxResults);
655
- async function* uncapped() {
656
- const regex = compileGrepPattern(query.pattern, query.caseInsensitive, query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path));
657
- const scope = query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
658
- const exact = store.get(scope);
659
- if (scope !== "/" && exact !== undefined) {
660
- if (query.glob !== undefined &&
661
- !pathMatchesGlob(scope, scope, query.glob, {
662
- matchBasename: true,
663
- })) {
664
- return;
665
- }
666
- if (isExcludedPath(scope, query.excludes)) {
667
- return;
668
- }
669
- yield* grepFileContent({
670
- path: scope,
671
- content: fileSystemText(exact),
672
- regex,
673
- });
674
- return;
675
- }
676
- for await (const entry of listed.list(scope === "/" ? undefined : scope, query.excludes === undefined ? undefined : { excludes: query.excludes })) {
677
- if (query.glob !== undefined &&
678
- !pathMatchesGlob(entry.path, scope, query.glob, {
679
- matchBasename: true,
680
- })) {
681
- continue;
682
- }
683
- const content = store.get(entry.path);
684
- if (content === undefined) {
685
- continue;
686
- }
687
- yield* grepFileContent({
688
- path: entry.path,
689
- content: fileSystemText(content),
690
- regex,
691
- });
692
- }
693
- }
694
- },
695
- async *glob(pattern, dir, options) {
696
- const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
697
- yield* globFromList(listed.list(scope === "/" ? undefined : scope), {
698
- pattern,
699
- dir: scope,
700
- ...(options?.limit === undefined ? {} : { limit: options.limit }),
701
- });
702
- },
703
- async write(inputPath, contents) {
704
- store.set(normalizeFsPath(inputPath), contents);
705
- },
706
- async delete(inputPath) {
707
- const path = normalizeFsPath(inputPath);
708
- if (!store.has(path)) {
709
- throw new FileNotFoundError(path);
710
- }
711
- store.delete(path);
712
- },
713
- };
714
- }
715
237
  function fsErrorMessage(error, fallback) {
716
238
  return error instanceof Error ? error.message : fallback;
717
239
  }
@@ -864,8 +386,13 @@ export function localFileSystem(options) {
864
386
  const cwd = path.resolve(options.cwd);
865
387
  const confineToWorkspace = options.confineToWorkspace === true;
866
388
  const readOnlyRoots = (options.readOnlyRoots ?? []).map((root) => path.resolve(root));
867
- const resolvePath = (input) => path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
868
- const resolveWritable = (input) => confineToWorkspace ? confinedHostPath(cwd, input) : Promise.resolve(resolvePath(input));
389
+ const resolvePath = (toolPath) => {
390
+ const input = hostPathFromToolPath(toolPath);
391
+ return path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
392
+ };
393
+ const resolveWritable = (toolPath) => confineToWorkspace
394
+ ? confinedHostPath(cwd, hostPathFromToolPath(toolPath))
395
+ : Promise.resolve(resolvePath(toolPath));
869
396
  const resolveLocated = async (input) => {
870
397
  try {
871
398
  return await resolveWritable(input);
@@ -970,7 +497,9 @@ export function localFileSystem(options) {
970
497
  const filePath = await resolveWritable(inputPath);
971
498
  try {
972
499
  await mkdir(path.dirname(filePath), { recursive: true });
973
- await writeFile(filePath, contents, "utf8");
500
+ await (typeof contents === "string"
501
+ ? writeFile(filePath, contents, "utf8")
502
+ : writeFile(filePath, contents));
974
503
  }
975
504
  catch (error) {
976
505
  throw new WriteFailedError(filePath, fsErrorMessage(error, `write failed: ${filePath}`));
@@ -987,94 +516,28 @@ export function localFileSystem(options) {
987
516
  },
988
517
  };
989
518
  }
990
- function longestMount(path, mounts) {
991
- let best;
992
- for (const mount of mounts) {
993
- if (!pathHasSegmentPrefix({ path, prefix: mount.prefix })) {
994
- continue;
995
- }
996
- if (best === undefined || mount.prefix.length > best.prefix.length) {
997
- best = mount;
998
- }
999
- }
1000
- return best;
1001
- }
1002
- /** Each mount strictly under `path`. */
1003
- function nestedMounts(path, mounts) {
1004
- return mounts.filter((mount) => mount.prefix !== path && pathHasSegmentPrefix({ path: mount.prefix, prefix: path }));
1005
- }
1006
- /**
1007
- * A glob from `scope` into a mount nested under it. The pattern is relative
1008
- * to `scope`, not to the mount, so the mount is listed and each path matched.
1009
- */
1010
- async function* globNestedMount(mount, scope, pattern) {
1011
- for await (const entry of mapMountEntries(mount.fs.list(undefined), mount.prefix)) {
1012
- if (pathMatchesGlob(entry.path, scope, pattern)) {
1013
- yield entry;
1014
- }
1015
- }
1016
- }
1017
- /** Namespace path → child path. `/host/a.md` on `/host` is `/a.md`. */
1018
- function toChildPath(path, prefix) {
1019
- if (prefix === "/") {
1020
- return path;
1021
- }
1022
- if (path === prefix) {
1023
- return "/";
1024
- }
1025
- if (path.startsWith(`${prefix}/`)) {
1026
- return path.slice(prefix.length);
1027
- }
1028
- return path;
1029
- }
1030
- /** Child path → namespace path. `/a.md` on `/host` is `/host/a.md`. */
1031
- function toParentPath(path, prefix) {
1032
- if (prefix === "/") {
1033
- return path;
1034
- }
1035
- if (path === "/" || path === "") {
1036
- return prefix;
1037
- }
1038
- return path.startsWith("/") ? `${prefix}${path}` : `${prefix}/${path}`;
1039
- }
1040
- async function* mapMountEntries(source, prefix) {
1041
- try {
1042
- for await (const entry of source) {
1043
- yield { ...entry, path: toParentPath(entry.path, prefix) };
1044
- }
1045
- }
1046
- catch (error) {
1047
- throw remapPathError(error, prefix);
1048
- }
1049
- }
1050
- async function* mapMountGrep(source, prefix) {
1051
- try {
1052
- for await (const hit of source) {
1053
- yield { ...hit, path: toParentPath(hit.path, prefix) };
1054
- }
1055
- }
1056
- catch (error) {
1057
- throw remapPathError(error, prefix);
1058
- }
1059
- }
1060
519
  function omittedScan(path) {
1061
520
  return path === undefined || path === "";
1062
521
  }
1063
522
  /**
1064
- * The turn tree: authored files at `/`, scratch at `/tmp`, and an optional
1065
- * skills mount. An omitted `grep` or `glob` path searches the authored
1066
- * tree only, so a tree that narrows that call (for example to `/repo`)
1067
- * does not also scan skills or scratch. An explicit path searches every
1068
- * mount under it.
523
+ * The session tree: authored files at `/` and an optional skills mount.
524
+ * `scratch`, when given, is mounted at `/tmp`; a turn leaves it out
525
+ * because the SDK mounts its own `/tmp` for each run. An omitted `grep`
526
+ * or `glob` path searches the authored tree only, so a tree that narrows
527
+ * that call (for example to `/repo`) does not also scan skills or
528
+ * scratch. An explicit path searches every mount under it.
1069
529
  */
1070
530
  export function sessionFileSystem(options) {
1071
- const mounts = {
1072
- "/": options.authored,
1073
- "/tmp": options.scratch ?? tempFs(),
1074
- };
531
+ const mounts = { "/": options.authored };
532
+ if (options.scratch !== undefined) {
533
+ mounts["/tmp"] = options.scratch;
534
+ }
1075
535
  if (options.skills !== undefined) {
1076
536
  mounts[options.skills.path] = options.skills.fs;
1077
537
  }
538
+ if (Object.keys(mounts).length === 1) {
539
+ return options.authored;
540
+ }
1078
541
  const union = unionFs(mounts);
1079
542
  return {
1080
543
  list: (prefix, listOptions) => union.list(prefix, listOptions),
@@ -1088,416 +551,6 @@ export function sessionFileSystem(options) {
1088
551
  grep: (query) => (omittedScan(query.path) ? options.authored.grep(query) : union.grep(query)),
1089
552
  };
1090
553
  }
1091
- /** Forwards reads. `write` and `delete` throw `read-only mount`. */
1092
- export function readOnlyFs(inner) {
1093
- return {
1094
- list: (prefix, options) => inner.list(prefix, options),
1095
- stat: (path) => inner.stat(path),
1096
- glob: (pattern, dir, options) => inner.glob(pattern, dir, options),
1097
- read: (path) => inner.read(path),
1098
- grep: (query) => inner.grep(query),
1099
- async write(path) {
1100
- throw new ReadOnlyMountError(normalizeFsPath(path));
1101
- },
1102
- async delete(path) {
1103
- throw new ReadOnlyMountError(normalizeFsPath(path));
1104
- },
1105
- };
1106
- }
1107
- /**
1108
- * Longest-prefix compose, path-segment match. Every verb is
1109
- * defined. Does not synthesize `shell`. `/agent` is not a
1110
- * prefix of `/agent-tools`.
1111
- *
1112
- * The record keys are mount points. Each child is a FileSystem
1113
- * rooted at `/`. `unionFs` strips the prefix on the way in and
1114
- * re-prefixes yields (and error paths) on the way out:
1115
- * `unionFs({ "/host": hostFs(...) })` — the child never sees
1116
- * `/host`.
1117
- *
1118
- * A path with no mount:
1119
- * - `read` / `write` / `delete`: throw
1120
- * `no mount for path: ${path}`
1121
- * - `list` / `glob` / `grep`: empty iterator
1122
- * - `stat`: `{ kind: "missing" }` (`/`, exact mount prefixes, and
1123
- * their parents are `{ kind: "directory" }`)
1124
- *
1125
- * `list` and `glob` below `/` also yield the files of each mount nested
1126
- * under that directory, as `list` and `glob` of `/` do. A nested glob
1127
- * lists that mount and matches each path against the pattern. `grep`
1128
- * stays on the mount that covers the path.
1129
- *
1130
- * Sources are already sorted longest prefix first. List and glob use
1131
- * `unique` so that earlier source wins a tie.
1132
- */
1133
- export function unionFs(mounts) {
1134
- const entries = Object.entries(mounts).map(([prefix, fs]) => ({
1135
- prefix: normalizeFsPath(prefix),
1136
- fs,
1137
- }));
1138
- entries.sort((a, b) => b.prefix.length - a.prefix.length);
1139
- const noMount = (path) => {
1140
- throw new NoMountError(path);
1141
- };
1142
- const forward = async (path, run) => {
1143
- const mount = longestMount(path, entries);
1144
- if (mount === undefined) {
1145
- return noMount(path);
1146
- }
1147
- const childPath = toChildPath(path, mount.prefix);
1148
- try {
1149
- return await run(mount.fs, childPath);
1150
- }
1151
- catch (error) {
1152
- throw remapPathError(error, mount.prefix);
1153
- }
1154
- };
1155
- const isRootPath = (value) => value === undefined || value === "" || value === "/";
1156
- return {
1157
- async *list(prefix, options) {
1158
- yield* limitResults(uncapped(), options?.limit);
1159
- async function* uncapped() {
1160
- if (isRootPath(prefix)) {
1161
- yield* mergeSortedByPath(entries.map((mount) => mapMountEntries(mount.fs.list(undefined, options), mount.prefix)), { unique: true });
1162
- return;
1163
- }
1164
- const path = normalizeFsPath(prefix ?? "/");
1165
- const mount = longestMount(path, entries);
1166
- const sources = nestedMounts(path, entries).map((nested) => mapMountEntries(nested.fs.list(undefined, options), nested.prefix));
1167
- if (mount !== undefined) {
1168
- const childPath = toChildPath(path, mount.prefix);
1169
- sources.push(mapMountEntries(mount.fs.list(childPath === "/" ? undefined : childPath, options), mount.prefix));
1170
- }
1171
- yield* mergeSortedByPath(sources, { unique: true });
1172
- }
1173
- },
1174
- async stat(path) {
1175
- const normalized = normalizeFsPath(path);
1176
- if (normalized === "/") {
1177
- return { kind: "directory" };
1178
- }
1179
- if (entries.some((entry) => entry.prefix === normalized)) {
1180
- return { kind: "directory" };
1181
- }
1182
- const mount = longestMount(normalized, entries);
1183
- const info = mount === undefined
1184
- ? { kind: "missing" }
1185
- : await mount.fs.stat(toChildPath(normalized, mount.prefix));
1186
- if (info.kind === "missing" && nestedMounts(normalized, entries).length > 0) {
1187
- return { kind: "directory" };
1188
- }
1189
- return info;
1190
- },
1191
- async read(path) {
1192
- const normalized = normalizeFsPath(path);
1193
- return forward(normalized, (fs, childPath) => fs.read(childPath));
1194
- },
1195
- async write(path, contents) {
1196
- const normalized = normalizeFsPath(path);
1197
- return forward(normalized, (fs, childPath) => fs.write(childPath, contents));
1198
- },
1199
- async delete(path) {
1200
- const normalized = normalizeFsPath(path);
1201
- return forward(normalized, (fs, childPath) => fs.delete(childPath));
1202
- },
1203
- async *grep(query) {
1204
- yield* limitResults(uncapped(), query.maxResults);
1205
- async function* uncapped() {
1206
- const scope = query.path === undefined || query.path === "" ? "/" : normalizeFsPath(query.path);
1207
- if (scope === "/") {
1208
- yield* mergeSorted(entries.map((mount) => mapMountGrep(mount.fs.grep({ ...query, path: undefined }), mount.prefix)), { compare: compareGrepResult });
1209
- return;
1210
- }
1211
- const mount = longestMount(scope, entries);
1212
- if (mount === undefined) {
1213
- return;
1214
- }
1215
- const childPath = toChildPath(scope, mount.prefix);
1216
- yield* mapMountGrep(mount.fs.grep({
1217
- ...query,
1218
- path: childPath === "/" ? undefined : childPath,
1219
- }), mount.prefix);
1220
- }
1221
- },
1222
- async *glob(pattern, dir, options) {
1223
- yield* limitResults(uncapped(), options?.limit);
1224
- async function* uncapped() {
1225
- const scope = dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
1226
- if (scope === "/") {
1227
- yield* mergeSortedByPath(entries.map((mount) => mapMountEntries(mount.fs.glob(pattern, undefined, options), mount.prefix)), { unique: true });
1228
- return;
1229
- }
1230
- const mount = longestMount(scope, entries);
1231
- const sources = nestedMounts(scope, entries).map((nested) => globNestedMount(nested, scope, pattern));
1232
- if (mount !== undefined) {
1233
- const childPath = toChildPath(scope, mount.prefix);
1234
- sources.push(mapMountEntries(mount.fs.glob(pattern, childPath === "/" ? undefined : childPath, options), mount.prefix));
1235
- }
1236
- yield* mergeSortedByPath(sources, { unique: true });
1237
- }
1238
- },
1239
- };
1240
- }
1241
- async function collectLayerPaths(layer) {
1242
- const paths = [];
1243
- try {
1244
- for await (const entry of layer.list()) {
1245
- paths.push(entry.path);
1246
- }
1247
- }
1248
- catch {
1249
- // A layer that cannot list also cannot own paths.
1250
- }
1251
- return paths;
1252
- }
1253
- /**
1254
- * Same-root overlay: earlier layers win. Read-only.
1255
- *
1256
- * A downed layer costs its own files, not the overlay. Mutations
1257
- * throw `read-only mount` / `read-only mount: ${path}`. Empty
1258
- * `layers` throws `overlayFs needs at least one layer.`
1259
- */
1260
- export function overlayFs(layers) {
1261
- if (layers.length === 0) {
1262
- throw new Error("overlayFs needs at least one layer.");
1263
- }
1264
- const walkLayers = async (collect) => {
1265
- const streams = [];
1266
- let failure;
1267
- let served = false;
1268
- for (const layer of layers) {
1269
- const collected = [];
1270
- try {
1271
- for await (const entry of await collect(layer)) {
1272
- collected.push(entry);
1273
- }
1274
- }
1275
- catch (error) {
1276
- failure ??= error;
1277
- continue;
1278
- }
1279
- served = true;
1280
- streams.push(collected);
1281
- }
1282
- return { streams, failure, served };
1283
- };
1284
- const collectOverlayHits = async (queryFn, rethrow) => {
1285
- const streams = [];
1286
- const shadowed = new Set();
1287
- let failure;
1288
- let served = false;
1289
- for (const layer of layers) {
1290
- const collected = [];
1291
- try {
1292
- for await (const hit of queryFn(layer)) {
1293
- if (!shadowed.has(hit.path)) {
1294
- collected.push(hit);
1295
- }
1296
- }
1297
- served = true;
1298
- }
1299
- catch (error) {
1300
- if (rethrow?.(error) === true) {
1301
- throw error;
1302
- }
1303
- failure ??= error;
1304
- continue;
1305
- }
1306
- streams.push(collected);
1307
- for (const path of await collectLayerPaths(layer)) {
1308
- shadowed.add(path);
1309
- }
1310
- }
1311
- if (!served && failure !== undefined) {
1312
- throw failure;
1313
- }
1314
- return streams;
1315
- };
1316
- return {
1317
- async *list(prefix, options) {
1318
- const { streams, failure, served } = await walkLayers((layer) => layer.list(prefix, options));
1319
- if (!served && failure !== undefined) {
1320
- throw failure;
1321
- }
1322
- yield* limitResults(mergeSortedByPath(streams, { unique: true }), options?.limit);
1323
- },
1324
- async stat(path) {
1325
- let failure;
1326
- let sawMissing = false;
1327
- for (const layer of layers) {
1328
- try {
1329
- const info = await layer.stat(path);
1330
- if (info.kind !== "missing") {
1331
- return info;
1332
- }
1333
- sawMissing = true;
1334
- }
1335
- catch (error) {
1336
- failure ??= error;
1337
- }
1338
- }
1339
- if (!sawMissing && failure !== undefined) {
1340
- throw failure;
1341
- }
1342
- return { kind: "missing" };
1343
- },
1344
- async *glob(pattern, dir, options) {
1345
- const { streams, failure, served } = await walkLayers((layer) => layer.glob(pattern, dir, options));
1346
- if (!served && failure !== undefined) {
1347
- throw failure;
1348
- }
1349
- yield* limitResults(mergeSortedByPath(streams, { unique: true }), options?.limit);
1350
- },
1351
- async read(path) {
1352
- let failure;
1353
- for (const layer of layers) {
1354
- try {
1355
- return await layer.read(path);
1356
- }
1357
- catch (error) {
1358
- if (isFileNotFoundError(error)) {
1359
- continue;
1360
- }
1361
- failure ??= error;
1362
- }
1363
- }
1364
- if (failure !== undefined) {
1365
- throw failure;
1366
- }
1367
- throw new FileNotFoundError(path);
1368
- },
1369
- async *grep(query) {
1370
- const { maxResults, ...uncappedQuery } = query;
1371
- yield* limitResults(mergeSorted(await collectOverlayHits((layer) => layer.grep(uncappedQuery), (error) => isInvalidGrepPatternError(error)), { compare: compareGrepResult }), maxResults);
1372
- },
1373
- async write(path) {
1374
- throw new ReadOnlyMountError(path);
1375
- },
1376
- async delete(path) {
1377
- throw new ReadOnlyMountError(path);
1378
- },
1379
- };
1380
- }
1381
- /**
1382
- * Hide `hidden` paths on `base` without mutating it. Used as the
1383
- * lower layer of {@link childOverlayFs}. Deletes of parent files
1384
- * are whiteouts in that set; writes never reach `base`.
1385
- */
1386
- function hidePaths(base, hidden) {
1387
- const visible = (filePath) => !hidden.has(normalizeFsPath(filePath));
1388
- return {
1389
- async *list(prefix, options) {
1390
- for await (const entry of base.list(prefix, options)) {
1391
- if (visible(entry.path)) {
1392
- yield entry;
1393
- }
1394
- }
1395
- },
1396
- async stat(path) {
1397
- const normalized = normalizeFsPath(path);
1398
- if (hidden.has(normalized)) {
1399
- return { kind: "missing" };
1400
- }
1401
- return base.stat(path);
1402
- },
1403
- async *glob(pattern, dir, options) {
1404
- for await (const entry of base.glob(pattern, dir, options)) {
1405
- if (visible(entry.path)) {
1406
- yield entry;
1407
- }
1408
- }
1409
- },
1410
- async read(path) {
1411
- const normalized = normalizeFsPath(path);
1412
- if (hidden.has(normalized)) {
1413
- throw new FileNotFoundError(normalized);
1414
- }
1415
- return base.read(path);
1416
- },
1417
- async *grep(query) {
1418
- for await (const hit of base.grep(query)) {
1419
- if (visible(hit.path)) {
1420
- yield hit;
1421
- }
1422
- }
1423
- },
1424
- async write(path) {
1425
- throw new ReadOnlyMountError(normalizeFsPath(path));
1426
- },
1427
- async delete(path) {
1428
- throw new ReadOnlyMountError(normalizeFsPath(path));
1429
- },
1430
- };
1431
- }
1432
- /**
1433
- * `stat` reports `{ kind: "missing" }` for both a hole in a mount and
1434
- * a path no mount owns. `read` is the verb that throws
1435
- * `no mount for path` — reuse that so a child write cannot invent
1436
- * a file outside the parent's root.
1437
- */
1438
- async function assertParentAddressable(parent, path) {
1439
- const info = await parent.stat(path);
1440
- if (info.kind !== "missing") {
1441
- return;
1442
- }
1443
- try {
1444
- await parent.read(path);
1445
- }
1446
- catch (error) {
1447
- if (isFileNotFoundError(error)) {
1448
- return;
1449
- }
1450
- throw error;
1451
- }
1452
- }
1453
- /**
1454
- * Writable child view over `parent`. Reads use `overlayFs` order:
1455
- * a private `tempFs` scratch, then `parent`. Writes and deletes land
1456
- * on that scratch. A delete of a parent file is a whiteout, so the
1457
- * child stops seeing it. `parent` is never mutated.
1458
- *
1459
- * FileSystem has no shell. Callers that bind executors to this handle
1460
- * omit shell.
1461
- */
1462
- export function childOverlayFs(parent) {
1463
- const scratch = tempFs();
1464
- const hidden = new Set();
1465
- const view = overlayFs([scratch, hidePaths(parent, hidden)]);
1466
- return {
1467
- list: (prefix, options) => view.list(prefix, options),
1468
- stat: (path) => view.stat(path),
1469
- glob: (pattern, dir, options) => view.glob(pattern, dir, options),
1470
- read: (path) => view.read(path),
1471
- grep: (query) => view.grep(query),
1472
- async write(path, contents) {
1473
- const normalized = normalizeFsPath(path);
1474
- await assertParentAddressable(parent, normalized);
1475
- const existing = await view.stat(normalized);
1476
- if (existing.kind === "directory") {
1477
- throw new WriteFailedError(normalized, `path is a directory: ${normalized}`);
1478
- }
1479
- hidden.delete(normalized);
1480
- await scratch.write(normalized, contents);
1481
- },
1482
- async delete(path) {
1483
- const normalized = normalizeFsPath(path);
1484
- await assertParentAddressable(parent, normalized);
1485
- const info = await view.stat(normalized);
1486
- if (info.kind !== "file") {
1487
- throw new FileNotFoundError(normalized);
1488
- }
1489
- hidden.add(normalized);
1490
- try {
1491
- await scratch.delete(normalized);
1492
- }
1493
- catch (error) {
1494
- if (!isFileNotFoundError(error)) {
1495
- throw error;
1496
- }
1497
- }
1498
- },
1499
- };
1500
- }
1501
554
  function hostKey(path) {
1502
555
  const normalized = normalizeFsPath(path);
1503
556
  return normalized === "/" ? "" : normalized.slice(1);
@@ -1639,6 +692,10 @@ export function hostFs(files, scope) {
1639
692
  });
1640
693
  },
1641
694
  async write(inputPath, contents) {
695
+ if (typeof contents !== "string") {
696
+ const path = normalizeFsPath(inputPath);
697
+ throw new WriteFailedError(path, `write failed: ${path} (host files store text only)`);
698
+ }
1642
699
  await writeHost(inputPath, contents);
1643
700
  },
1644
701
  async delete(inputPath) {