@cursor/july 0.1.100 → 0.1.102

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 (484) hide show
  1. package/README.md +27 -0
  2. package/dist/bin/agent-serve.js +3 -2
  3. package/dist/channels/deployments/deployments-channel.d.ts +41 -5
  4. package/dist/channels/deployments/deployments-channel.d.ts.map +1 -1
  5. package/dist/channels/deployments/deployments-channel.js +88 -8
  6. package/dist/channels/deployments/types.d.ts +4 -3
  7. package/dist/channels/deployments/types.d.ts.map +1 -1
  8. package/dist/channels/origin/defaults.d.ts +43 -0
  9. package/dist/channels/origin/defaults.d.ts.map +1 -0
  10. package/dist/channels/origin/defaults.js +111 -0
  11. package/dist/channels/origin/index.d.ts +2 -0
  12. package/dist/channels/origin/index.d.ts.map +1 -1
  13. package/dist/channels/origin/index.js +2 -0
  14. package/dist/channels/origin/origin-channel.d.ts +2 -1
  15. package/dist/channels/origin/origin-channel.d.ts.map +1 -1
  16. package/dist/channels/origin/origin-channel.js +24 -3
  17. package/dist/channels/origin/state.d.ts +32 -0
  18. package/dist/channels/origin/state.d.ts.map +1 -0
  19. package/dist/channels/origin/state.js +23 -0
  20. package/dist/channels/origin/types.d.ts +23 -1
  21. package/dist/channels/origin/types.d.ts.map +1 -1
  22. package/dist/channels/slack/api.d.ts +1 -1
  23. package/dist/channels/slack/api.d.ts.map +1 -1
  24. package/dist/channels/slack/api.js +5 -2
  25. package/dist/channels/slack/assistant.d.ts +1 -1
  26. package/dist/channels/slack/assistant.d.ts.map +1 -1
  27. package/dist/channels/slack/code-fences.d.ts +17 -0
  28. package/dist/channels/slack/code-fences.d.ts.map +1 -0
  29. package/dist/channels/slack/code-fences.js +168 -0
  30. package/dist/channels/slack/dispatch.d.ts +3 -2
  31. package/dist/channels/slack/dispatch.d.ts.map +1 -1
  32. package/dist/channels/slack/dispatch.js +28 -8
  33. package/dist/channels/slack/inbound.d.ts +8 -0
  34. package/dist/channels/slack/inbound.d.ts.map +1 -1
  35. package/dist/channels/slack/inbound.js +28 -0
  36. package/dist/channels/slack/index.d.ts +1 -0
  37. package/dist/channels/slack/index.d.ts.map +1 -1
  38. package/dist/channels/slack/index.js +1 -0
  39. package/dist/channels/slack/live-delivery.d.ts.map +1 -1
  40. package/dist/channels/slack/live-delivery.js +11 -4
  41. package/dist/channels/slack/manifest.d.ts.map +1 -1
  42. package/dist/channels/slack/manifest.js +2 -1
  43. package/dist/connections.d.ts +18 -2
  44. package/dist/connections.d.ts.map +1 -1
  45. package/dist/connections.js +18 -2
  46. package/dist/docs/404.html +2 -2
  47. package/dist/docs/ab.html +4 -4
  48. package/dist/docs/assets/{app.DZ1e0Ycq.js → app.CLA03RCz.js} +1 -1
  49. package/dist/docs/assets/chunks/@localSearchIndexroot.FAqdWIXo.js +1 -0
  50. package/dist/docs/assets/chunks/{VPLocalSearchBox.l8omwc6D.js → VPLocalSearchBox.ifxv-cJV.js} +1 -1
  51. package/dist/docs/assets/chunks/{theme.JVcD6gel.js → theme.DWCwM6p-.js} +2 -2
  52. package/dist/docs/assets/concepts.md.rPzW2HZN.js +1 -0
  53. package/dist/docs/assets/guides_cloud-agents.md.DumwWXba.js +9 -0
  54. package/dist/docs/assets/guides_cloud-agents.md.DumwWXba.lean.js +1 -0
  55. package/dist/docs/assets/{guides_cloud-runtime.md.CkYbjnAX.js → guides_cloud-runtime.md.BRirbRAN.js} +1 -1
  56. package/dist/docs/assets/index.md.Kiht7ell.js +5 -0
  57. package/dist/docs/assets/{index.md.Bb4k8kUm.lean.js → index.md.Kiht7ell.lean.js} +1 -1
  58. package/dist/docs/assets/{reference_connections.md.BiGoBAk2.js → reference_connections.md.Di6jJAXF.js} +12 -2
  59. package/dist/docs/assets/{reference_connections.md.BiGoBAk2.lean.js → reference_connections.md.Di6jJAXF.lean.js} +1 -1
  60. package/dist/docs/assets/reference_extensions.md.9WQMZe1l.js +56 -0
  61. package/dist/docs/assets/reference_extensions.md.9WQMZe1l.lean.js +1 -0
  62. package/dist/docs/assets/{reference_http-api.md.BEJx9XVj.js → reference_http-api.md.oySXBO8o.js} +1 -1
  63. package/dist/docs/assets/{reference_project-layout.md.Bv4KOtlB.js → reference_project-layout.md.CA6QP6Lw.js} +2 -2
  64. package/dist/docs/assets/{reference_project-layout.md.Bv4KOtlB.lean.js → reference_project-layout.md.CA6QP6Lw.lean.js} +1 -1
  65. package/dist/docs/assets/{reference_skills.md.BFW9retM.js → reference_skills.md.l2ezAcaN.js} +1 -1
  66. package/dist/docs/assets/{reference_tools.md.CvAHsdSp.js → reference_tools.md.B1up2r9W.js} +1 -1
  67. package/dist/docs/assets/skills_framework-map.md.DDa4MeEW.js +1 -0
  68. package/dist/docs/assets/{skills_framework-map.md.BTi817yv.lean.js → skills_framework-map.md.DDa4MeEW.lean.js} +1 -1
  69. package/dist/docs/building-with-agents.html +4 -4
  70. package/dist/docs/concepts.html +5 -5
  71. package/dist/docs/concepts.md +3 -3
  72. package/dist/docs/deployment.html +4 -4
  73. package/dist/docs/evals.html +4 -4
  74. package/dist/docs/guides/agent-to-agent.html +4 -4
  75. package/dist/docs/guides/cloud-agents.html +35 -0
  76. package/dist/docs/guides/cloud-agents.md +93 -0
  77. package/dist/docs/guides/cloud-runtime.html +6 -6
  78. package/dist/docs/guides/cloud-runtime.md +2 -0
  79. package/dist/docs/guides/convert-automation.html +4 -4
  80. package/dist/docs/guides/github.html +4 -4
  81. package/dist/docs/guides/human-in-the-loop.html +4 -4
  82. package/dist/docs/guides/mcp-oauth.html +4 -4
  83. package/dist/docs/guides/opentelemetry.html +5 -5
  84. package/dist/docs/guides/slack.html +4 -4
  85. package/dist/docs/guides/webhooks.html +4 -4
  86. package/dist/docs/hashmap.json +1 -1
  87. package/dist/docs/hillclimbing.html +4 -4
  88. package/dist/docs/index.html +6 -6
  89. package/dist/docs/index.md +5 -1
  90. package/dist/docs/llms-full.txt +353 -5
  91. package/dist/docs/llms.txt +2 -0
  92. package/dist/docs/quickstart.html +4 -4
  93. package/dist/docs/reference/agent-config.html +4 -4
  94. package/dist/docs/reference/artifacts.html +4 -4
  95. package/dist/docs/reference/channels.html +5 -5
  96. package/dist/docs/reference/cli.html +4 -4
  97. package/dist/docs/reference/connections.html +16 -6
  98. package/dist/docs/reference/connections.md +31 -0
  99. package/dist/docs/reference/extensions.html +82 -0
  100. package/dist/docs/reference/extensions.md +200 -0
  101. package/dist/docs/reference/hooks.html +4 -4
  102. package/dist/docs/reference/http-api.html +6 -6
  103. package/dist/docs/reference/http-api.md +1 -1
  104. package/dist/docs/reference/instructions.html +4 -4
  105. package/dist/docs/reference/playground.html +4 -4
  106. package/dist/docs/reference/project-layout.html +6 -6
  107. package/dist/docs/reference/project-layout.md +3 -0
  108. package/dist/docs/reference/prompt.html +4 -4
  109. package/dist/docs/reference/schedules.html +4 -4
  110. package/dist/docs/reference/sessions.html +4 -4
  111. package/dist/docs/reference/skills.html +6 -6
  112. package/dist/docs/reference/skills.md +2 -0
  113. package/dist/docs/reference/subagents.html +5 -5
  114. package/dist/docs/reference/tools.html +6 -6
  115. package/dist/docs/reference/tools.md +2 -0
  116. package/dist/docs/scaffolding-agents.html +4 -4
  117. package/dist/docs/skills/ab.html +4 -4
  118. package/dist/docs/skills/create-agent.html +4 -4
  119. package/dist/docs/skills/debug.html +4 -4
  120. package/dist/docs/skills/evals.html +4 -4
  121. package/dist/docs/skills/framework-map.html +5 -5
  122. package/dist/docs/skills/framework-map.md +1 -0
  123. package/dist/docs/skills/github.html +4 -4
  124. package/dist/docs/skills/hillclimb.html +4 -4
  125. package/dist/docs/skills/index.html +4 -4
  126. package/dist/docs/skills/mcp-auth.html +4 -4
  127. package/dist/docs/skills/otel.html +4 -4
  128. package/dist/docs/skills/setup-slack.html +4 -4
  129. package/dist/docs/storage.html +4 -4
  130. package/dist/docs/templates/agentic-owners.html +4 -4
  131. package/dist/docs/templates/agents-md.html +4 -4
  132. package/dist/docs/templates/code-wiki.html +4 -4
  133. package/dist/docs/templates/demo.html +4 -4
  134. package/dist/docs/templates/pr-autofixer.html +4 -4
  135. package/dist/docs/templates/security-help.html +4 -4
  136. package/dist/docs/templates/security-reviewer.html +4 -4
  137. package/dist/docs/templates/triage.html +4 -4
  138. package/dist/docs/troubleshooting.html +4 -4
  139. package/dist/extensions/cursor-cloud-agents/extension.d.ts +57 -0
  140. package/dist/extensions/cursor-cloud-agents/extension.d.ts.map +1 -0
  141. package/dist/extensions/cursor-cloud-agents/extension.js +66 -0
  142. package/dist/extensions/cursor-cloud-agents/lib/backend.d.ts +78 -0
  143. package/dist/extensions/cursor-cloud-agents/lib/backend.d.ts.map +1 -0
  144. package/dist/extensions/cursor-cloud-agents/lib/backend.js +286 -0
  145. package/dist/extensions/cursor-cloud-agents/lib/fleet.d.ts +25 -0
  146. package/dist/extensions/cursor-cloud-agents/lib/fleet.d.ts.map +1 -0
  147. package/dist/extensions/cursor-cloud-agents/lib/fleet.js +85 -0
  148. package/dist/extensions/cursor-cloud-agents/lib/inputs.d.ts +5 -0
  149. package/dist/extensions/cursor-cloud-agents/lib/inputs.d.ts.map +1 -0
  150. package/dist/extensions/cursor-cloud-agents/lib/inputs.js +4 -0
  151. package/dist/extensions/cursor-cloud-agents/lib/repos.d.ts +15 -0
  152. package/dist/extensions/cursor-cloud-agents/lib/repos.d.ts.map +1 -0
  153. package/dist/extensions/cursor-cloud-agents/lib/repos.js +55 -0
  154. package/dist/extensions/cursor-cloud-agents/lib/transcript.d.ts +8 -0
  155. package/dist/extensions/cursor-cloud-agents/lib/transcript.d.ts.map +1 -0
  156. package/dist/extensions/cursor-cloud-agents/lib/transcript.js +15 -0
  157. package/dist/extensions/cursor-cloud-agents/skills/handoff.md +41 -0
  158. package/dist/extensions/cursor-cloud-agents/tools/cancel.d.ts +4 -0
  159. package/dist/extensions/cursor-cloud-agents/tools/cancel.d.ts.map +1 -0
  160. package/dist/extensions/cursor-cloud-agents/tools/cancel.js +26 -0
  161. package/dist/extensions/cursor-cloud-agents/tools/dump.d.ts +4 -0
  162. package/dist/extensions/cursor-cloud-agents/tools/dump.d.ts.map +1 -0
  163. package/dist/extensions/cursor-cloud-agents/tools/dump.js +54 -0
  164. package/dist/extensions/cursor-cloud-agents/tools/get.d.ts +4 -0
  165. package/dist/extensions/cursor-cloud-agents/tools/get.d.ts.map +1 -0
  166. package/dist/extensions/cursor-cloud-agents/tools/get.js +25 -0
  167. package/dist/extensions/cursor-cloud-agents/tools/launch.d.ts +4 -0
  168. package/dist/extensions/cursor-cloud-agents/tools/launch.d.ts.map +1 -0
  169. package/dist/extensions/cursor-cloud-agents/tools/launch.js +59 -0
  170. package/dist/extensions/cursor-cloud-agents/tools/list.d.ts +4 -0
  171. package/dist/extensions/cursor-cloud-agents/tools/list.d.ts.map +1 -0
  172. package/dist/extensions/cursor-cloud-agents/tools/list.js +36 -0
  173. package/dist/extensions/cursor-cloud-agents/tools/reply.d.ts +4 -0
  174. package/dist/extensions/cursor-cloud-agents/tools/reply.d.ts.map +1 -0
  175. package/dist/extensions/cursor-cloud-agents/tools/reply.js +35 -0
  176. package/dist/extensions.d.ts +73 -0
  177. package/dist/extensions.d.ts.map +1 -0
  178. package/dist/extensions.js +112 -0
  179. package/dist/files-backends/cursor-hosted.d.ts +0 -8
  180. package/dist/files-backends/cursor-hosted.d.ts.map +1 -1
  181. package/dist/files-backends/cursor-hosted.js +1 -11
  182. package/dist/files.d.ts +5 -1
  183. package/dist/files.d.ts.map +1 -1
  184. package/dist/files.js +22 -18
  185. package/dist/index.d.ts +4 -3
  186. package/dist/index.d.ts.map +1 -1
  187. package/dist/index.js +3 -2
  188. package/dist/internal/advertise-tools.d.ts +4 -1
  189. package/dist/internal/advertise-tools.d.ts.map +1 -1
  190. package/dist/internal/advertise-tools.js +20 -1
  191. package/dist/internal/as-of.d.ts +18 -0
  192. package/dist/internal/as-of.d.ts.map +1 -1
  193. package/dist/internal/as-of.js +131 -0
  194. package/dist/internal/cli-deploy.d.ts.map +1 -1
  195. package/dist/internal/cli-deploy.js +64 -19
  196. package/dist/internal/continuation-identity.d.ts.map +1 -1
  197. package/dist/internal/continuation-identity.js +3 -1
  198. package/dist/internal/conversation-mirror.d.ts.map +1 -1
  199. package/dist/internal/conversation-mirror.js +13 -15
  200. package/dist/internal/cursor/backend-client.d.ts +8 -1
  201. package/dist/internal/cursor/backend-client.d.ts.map +1 -1
  202. package/dist/internal/cursor/backend-client.js +25 -9
  203. package/dist/internal/cursor/hosted-deployment-secrets.d.ts +16 -0
  204. package/dist/internal/cursor/hosted-deployment-secrets.d.ts.map +1 -0
  205. package/dist/internal/cursor/hosted-deployment-secrets.js +61 -0
  206. package/dist/internal/cursor/hosted-store-secrets.d.ts +11 -0
  207. package/dist/internal/cursor/hosted-store-secrets.d.ts.map +1 -1
  208. package/dist/internal/cursor/hosted-store-secrets.js +15 -0
  209. package/dist/internal/cursor-deployment-relay.d.ts +15 -1
  210. package/dist/internal/cursor-deployment-relay.d.ts.map +1 -1
  211. package/dist/internal/cursor-deployment-relay.js +46 -7
  212. package/dist/internal/deploy-client.d.ts +23 -0
  213. package/dist/internal/deploy-client.d.ts.map +1 -1
  214. package/dist/internal/deploy-client.js +54 -12
  215. package/dist/internal/discovery/ab.d.ts +9 -0
  216. package/dist/internal/discovery/ab.d.ts.map +1 -0
  217. package/dist/internal/discovery/ab.js +101 -0
  218. package/dist/internal/discovery/agent-config.d.ts +35 -0
  219. package/dist/internal/discovery/agent-config.d.ts.map +1 -0
  220. package/dist/internal/discovery/agent-config.js +173 -0
  221. package/dist/internal/discovery/agent.d.ts +11 -0
  222. package/dist/internal/discovery/agent.d.ts.map +1 -0
  223. package/dist/internal/discovery/agent.js +306 -0
  224. package/dist/internal/discovery/channels.d.ts +10 -0
  225. package/dist/internal/discovery/channels.d.ts.map +1 -0
  226. package/dist/internal/discovery/channels.js +97 -0
  227. package/dist/internal/discovery/connections.d.ts +17 -0
  228. package/dist/internal/discovery/connections.d.ts.map +1 -0
  229. package/dist/internal/discovery/connections.js +436 -0
  230. package/dist/internal/discovery/context.d.ts +20 -0
  231. package/dist/internal/discovery/context.d.ts.map +1 -0
  232. package/dist/internal/discovery/context.js +30 -0
  233. package/dist/internal/discovery/cursor-plugin.d.ts +25 -0
  234. package/dist/internal/discovery/cursor-plugin.d.ts.map +1 -0
  235. package/dist/internal/discovery/cursor-plugin.js +570 -0
  236. package/dist/internal/discovery/extensions.d.ts +19 -0
  237. package/dist/internal/discovery/extensions.d.ts.map +1 -0
  238. package/dist/internal/discovery/extensions.js +238 -0
  239. package/dist/internal/discovery/fs.d.ts +15 -0
  240. package/dist/internal/discovery/fs.d.ts.map +1 -0
  241. package/dist/internal/discovery/fs.js +115 -0
  242. package/dist/internal/discovery/hooks.d.ts +7 -0
  243. package/dist/internal/discovery/hooks.d.ts.map +1 -0
  244. package/dist/internal/discovery/hooks.js +48 -0
  245. package/dist/internal/discovery/info.d.ts +6 -0
  246. package/dist/internal/discovery/info.d.ts.map +1 -0
  247. package/dist/internal/discovery/info.js +141 -0
  248. package/dist/internal/discovery/instructions.d.ts +7 -0
  249. package/dist/internal/discovery/instructions.d.ts.map +1 -0
  250. package/dist/internal/discovery/instructions.js +95 -0
  251. package/dist/internal/discovery/modules.d.ts +20 -0
  252. package/dist/internal/discovery/modules.d.ts.map +1 -0
  253. package/dist/internal/discovery/modules.js +101 -0
  254. package/dist/internal/discovery/names.d.ts +12 -0
  255. package/dist/internal/discovery/names.d.ts.map +1 -0
  256. package/dist/internal/discovery/names.js +36 -0
  257. package/dist/internal/discovery/project.d.ts +53 -0
  258. package/dist/internal/discovery/project.d.ts.map +1 -0
  259. package/dist/internal/discovery/project.js +239 -0
  260. package/dist/internal/discovery/runtime.d.ts +34 -0
  261. package/dist/internal/discovery/runtime.d.ts.map +1 -0
  262. package/dist/internal/discovery/runtime.js +98 -0
  263. package/dist/internal/discovery/schedules.d.ts +7 -0
  264. package/dist/internal/discovery/schedules.d.ts.map +1 -0
  265. package/dist/internal/discovery/schedules.js +97 -0
  266. package/dist/internal/discovery/seed-files.d.ts +7 -0
  267. package/dist/internal/discovery/seed-files.d.ts.map +1 -0
  268. package/dist/internal/discovery/seed-files.js +41 -0
  269. package/dist/internal/discovery/services.d.ts +17 -0
  270. package/dist/internal/discovery/services.d.ts.map +1 -0
  271. package/dist/internal/discovery/services.js +104 -0
  272. package/dist/internal/discovery/skills.d.ts +16 -0
  273. package/dist/internal/discovery/skills.d.ts.map +1 -0
  274. package/dist/internal/discovery/skills.js +151 -0
  275. package/dist/internal/discovery/subagent.d.ts +13 -0
  276. package/dist/internal/discovery/subagent.d.ts.map +1 -0
  277. package/dist/internal/discovery/subagent.js +19 -0
  278. package/dist/internal/discovery/tools.d.ts +18 -0
  279. package/dist/internal/discovery/tools.d.ts.map +1 -0
  280. package/dist/internal/discovery/tools.js +159 -0
  281. package/dist/internal/discovery.d.ts +8 -62
  282. package/dist/internal/discovery.d.ts.map +1 -1
  283. package/dist/internal/discovery.js +8 -2210
  284. package/dist/internal/distribution.d.ts.map +1 -1
  285. package/dist/internal/distribution.js +5 -0
  286. package/dist/internal/framework-file-storage.d.ts +3 -3
  287. package/dist/internal/framework-file-storage.d.ts.map +1 -1
  288. package/dist/internal/framework-file-storage.js +38 -9
  289. package/dist/internal/framework-storage-selection.d.ts.map +1 -1
  290. package/dist/internal/framework-storage-selection.js +8 -7
  291. package/dist/internal/frontmatter.d.ts +11 -3
  292. package/dist/internal/frontmatter.d.ts.map +1 -1
  293. package/dist/internal/frontmatter.js +29 -3
  294. package/dist/internal/hosted-delivery.d.ts +3 -1
  295. package/dist/internal/hosted-delivery.d.ts.map +1 -1
  296. package/dist/internal/hosted-delivery.js +19 -32
  297. package/dist/internal/hosted-execution-diag.d.ts +5 -0
  298. package/dist/internal/hosted-execution-diag.d.ts.map +1 -1
  299. package/dist/internal/hosted-execution-diag.js +5 -0
  300. package/dist/internal/hosted-execution-flush.d.ts +46 -0
  301. package/dist/internal/hosted-execution-flush.d.ts.map +1 -0
  302. package/dist/internal/hosted-execution-flush.js +81 -0
  303. package/dist/internal/mcp-endpoint.js +1 -0
  304. package/dist/internal/mcp-host.d.ts +2 -1
  305. package/dist/internal/mcp-host.d.ts.map +1 -1
  306. package/dist/internal/mcp-host.js +66 -29
  307. package/dist/internal/otel/collector.d.ts +13 -0
  308. package/dist/internal/otel/collector.d.ts.map +1 -1
  309. package/dist/internal/otel/collector.js +84 -17
  310. package/dist/internal/otel/http.d.ts.map +1 -1
  311. package/dist/internal/otel/http.js +2 -10
  312. package/dist/internal/otel/mcp.d.ts +16 -0
  313. package/dist/internal/otel/mcp.d.ts.map +1 -0
  314. package/dist/internal/otel/mcp.js +68 -0
  315. package/dist/internal/otel/propagation.d.ts +6 -0
  316. package/dist/internal/otel/propagation.d.ts.map +1 -0
  317. package/dist/internal/otel/propagation.js +14 -0
  318. package/dist/internal/otel/runtime.d.ts.map +1 -1
  319. package/dist/internal/otel/runtime.js +2 -0
  320. package/dist/internal/review-comments.d.ts +1 -1
  321. package/dist/internal/review-comments.d.ts.map +1 -1
  322. package/dist/internal/review-comments.js +4 -4
  323. package/dist/internal/server.d.ts +3 -0
  324. package/dist/internal/server.d.ts.map +1 -1
  325. package/dist/internal/server.js +79 -104
  326. package/dist/internal/session-engine.d.ts +14 -7
  327. package/dist/internal/session-engine.d.ts.map +1 -1
  328. package/dist/internal/session-engine.js +113 -66
  329. package/dist/internal/session-run-log.d.ts +3 -1
  330. package/dist/internal/session-run-log.d.ts.map +1 -1
  331. package/dist/internal/session-run-log.js +14 -14
  332. package/dist/internal/start-log-store.d.ts +60 -0
  333. package/dist/internal/start-log-store.d.ts.map +1 -0
  334. package/dist/internal/start-log-store.js +149 -0
  335. package/dist/internal/storage-coordinator.d.ts +4 -1
  336. package/dist/internal/storage-coordinator.d.ts.map +1 -1
  337. package/dist/internal/storage-coordinator.js +15 -13
  338. package/dist/internal/tool-catalog.d.ts.map +1 -1
  339. package/dist/internal/tool-catalog.js +9 -6
  340. package/dist/internal/tool-policy.d.ts +8 -0
  341. package/dist/internal/tool-policy.d.ts.map +1 -1
  342. package/dist/internal/tool-policy.js +19 -7
  343. package/dist/internal/turn-cost.d.ts +14 -0
  344. package/dist/internal/turn-cost.d.ts.map +1 -1
  345. package/dist/internal/turn-cost.js +41 -9
  346. package/dist/internal/v2-hosting.d.ts +22 -0
  347. package/dist/internal/v2-hosting.d.ts.map +1 -0
  348. package/dist/internal/v2-hosting.js +23 -0
  349. package/dist/otel.d.ts +16 -0
  350. package/dist/otel.d.ts.map +1 -1
  351. package/dist/otel.js +26 -0
  352. package/dist/playground/assets/index-B6C9S9nG.css +1 -0
  353. package/dist/playground/assets/{index-DVs98vPL.js → index-ZqNoT8Ie.js} +45 -45
  354. package/dist/playground/index.html +2 -2
  355. package/dist/storage-protocol.d.ts +47 -22
  356. package/dist/storage-protocol.d.ts.map +1 -1
  357. package/dist/storage-protocol.js +90 -54
  358. package/dist/storage.d.ts +2 -2
  359. package/dist/storage.d.ts.map +1 -1
  360. package/dist/storage.js +1 -1
  361. package/dist/tools.d.ts +9 -0
  362. package/dist/tools.d.ts.map +1 -1
  363. package/dist/tools.js +9 -0
  364. package/dist/types.d.ts +154 -6
  365. package/dist/types.d.ts.map +1 -1
  366. package/dist/types.js +29 -1
  367. package/docs/README.md +5 -1
  368. package/docs/concepts.md +3 -3
  369. package/docs/guides/cloud-agents.md +98 -0
  370. package/docs/guides/cloud-runtime.md +2 -0
  371. package/docs/reference/connections.md +31 -0
  372. package/docs/reference/extensions.md +205 -0
  373. package/docs/reference/http-api.md +1 -1
  374. package/docs/reference/project-layout.md +3 -0
  375. package/docs/reference/skills.md +2 -0
  376. package/docs/reference/tools.md +2 -0
  377. package/package.json +18 -4
  378. package/skills/framework-map/SKILL.md +1 -0
  379. package/src/bin/agent-serve.ts +11 -2
  380. package/src/channels/deployments/deployments-channel.ts +117 -8
  381. package/src/channels/deployments/types.ts +4 -3
  382. package/src/channels/origin/defaults.ts +143 -0
  383. package/src/channels/origin/index.ts +2 -0
  384. package/src/channels/origin/origin-channel.ts +37 -1
  385. package/src/channels/origin/state.ts +54 -0
  386. package/src/channels/origin/types.ts +24 -0
  387. package/src/channels/slack/api.ts +6 -3
  388. package/src/channels/slack/assistant.ts +1 -1
  389. package/src/channels/slack/code-fences.ts +183 -0
  390. package/src/channels/slack/dispatch.ts +27 -2
  391. package/src/channels/slack/inbound.ts +37 -0
  392. package/src/channels/slack/index.ts +1 -0
  393. package/src/channels/slack/live-delivery.ts +16 -13
  394. package/src/channels/slack/manifest.ts +2 -1
  395. package/src/connections.ts +18 -1
  396. package/src/extensions/cursor-cloud-agents/extension.ts +120 -0
  397. package/src/extensions/cursor-cloud-agents/lib/backend.ts +395 -0
  398. package/src/extensions/cursor-cloud-agents/lib/fleet.ts +109 -0
  399. package/src/extensions/cursor-cloud-agents/lib/inputs.ts +5 -0
  400. package/src/extensions/cursor-cloud-agents/lib/repos.ts +81 -0
  401. package/src/extensions/cursor-cloud-agents/lib/transcript.ts +23 -0
  402. package/src/extensions/cursor-cloud-agents/skills/handoff.md +41 -0
  403. package/src/extensions/cursor-cloud-agents/tools/cancel.ts +19 -0
  404. package/src/extensions/cursor-cloud-agents/tools/dump.ts +51 -0
  405. package/src/extensions/cursor-cloud-agents/tools/get.ts +18 -0
  406. package/src/extensions/cursor-cloud-agents/tools/launch.ts +64 -0
  407. package/src/extensions/cursor-cloud-agents/tools/list.ts +31 -0
  408. package/src/extensions/cursor-cloud-agents/tools/reply.ts +34 -0
  409. package/src/extensions.ts +141 -0
  410. package/src/files-backends/cursor-hosted.ts +1 -17
  411. package/src/files.ts +43 -34
  412. package/src/index.ts +11 -0
  413. package/src/internal/advertise-tools.ts +37 -12
  414. package/src/internal/as-of.ts +163 -0
  415. package/src/internal/cli-deploy.ts +86 -23
  416. package/src/internal/continuation-identity.ts +3 -1
  417. package/src/internal/conversation-mirror.ts +23 -18
  418. package/src/internal/cursor/backend-client.ts +32 -10
  419. package/src/internal/cursor/hosted-deployment-secrets.ts +72 -0
  420. package/src/internal/cursor/hosted-store-secrets.ts +27 -0
  421. package/src/internal/cursor-deployment-relay.ts +65 -8
  422. package/src/internal/deploy-client.ts +73 -18
  423. package/src/internal/discovery/ab.ts +111 -0
  424. package/src/internal/discovery/agent-config.ts +222 -0
  425. package/src/internal/discovery/agent.ts +360 -0
  426. package/src/internal/discovery/channels.ts +103 -0
  427. package/src/internal/discovery/connections.ts +540 -0
  428. package/src/internal/discovery/context.ts +46 -0
  429. package/src/internal/discovery/cursor-plugin.ts +708 -0
  430. package/src/internal/discovery/extensions.ts +348 -0
  431. package/src/internal/discovery/fs.ts +108 -0
  432. package/src/internal/discovery/hooks.ts +45 -0
  433. package/src/internal/discovery/info.ts +179 -0
  434. package/src/internal/discovery/instructions.ts +113 -0
  435. package/src/internal/discovery/modules.ts +107 -0
  436. package/src/internal/discovery/names.ts +44 -0
  437. package/src/internal/discovery/project.ts +270 -0
  438. package/src/internal/discovery/runtime.ts +159 -0
  439. package/src/internal/discovery/schedules.ts +94 -0
  440. package/src/internal/discovery/seed-files.ts +37 -0
  441. package/src/internal/discovery/services.ts +124 -0
  442. package/src/internal/discovery/skills.ts +176 -0
  443. package/src/internal/discovery/subagent.ts +29 -0
  444. package/src/internal/discovery/tools.ts +182 -0
  445. package/src/internal/discovery.ts +20 -2724
  446. package/src/internal/distribution.ts +5 -0
  447. package/src/internal/framework-file-storage.ts +43 -9
  448. package/src/internal/framework-storage-selection.ts +9 -9
  449. package/src/internal/frontmatter.ts +36 -3
  450. package/src/internal/hosted-delivery.ts +38 -63
  451. package/src/internal/hosted-execution-diag.ts +6 -0
  452. package/src/internal/hosted-execution-flush.ts +142 -0
  453. package/src/internal/mcp-endpoint.ts +1 -0
  454. package/src/internal/mcp-host.ts +116 -37
  455. package/src/internal/otel/collector.ts +125 -25
  456. package/src/internal/otel/http.ts +2 -12
  457. package/src/internal/otel/mcp.ts +69 -0
  458. package/src/internal/otel/propagation.ts +17 -0
  459. package/src/internal/otel/runtime.ts +2 -0
  460. package/src/internal/review-comments.ts +5 -2
  461. package/src/internal/server.ts +81 -100
  462. package/src/internal/session-engine.ts +152 -39
  463. package/src/internal/session-run-log.ts +18 -16
  464. package/src/internal/start-log-store.ts +174 -0
  465. package/src/internal/storage-coordinator.ts +19 -16
  466. package/src/internal/tool-catalog.ts +9 -6
  467. package/src/internal/tool-policy.ts +39 -9
  468. package/src/internal/turn-cost.ts +47 -4
  469. package/src/internal/v2-hosting.ts +38 -0
  470. package/src/otel.ts +38 -0
  471. package/src/storage-protocol.ts +126 -79
  472. package/src/storage.ts +5 -0
  473. package/src/tools.ts +18 -0
  474. package/src/types.ts +213 -14
  475. package/dist/docs/assets/chunks/@localSearchIndexroot.j70vvPL4.js +0 -1
  476. package/dist/docs/assets/concepts.md.lwAgBIMI.js +0 -1
  477. package/dist/docs/assets/index.md.Bb4k8kUm.js +0 -5
  478. package/dist/docs/assets/skills_framework-map.md.BTi817yv.js +0 -1
  479. package/dist/playground/assets/index-BszoQDc6.css +0 -1
  480. /package/dist/docs/assets/{concepts.md.lwAgBIMI.lean.js → concepts.md.rPzW2HZN.lean.js} +0 -0
  481. /package/dist/docs/assets/{guides_cloud-runtime.md.CkYbjnAX.lean.js → guides_cloud-runtime.md.BRirbRAN.lean.js} +0 -0
  482. /package/dist/docs/assets/{reference_http-api.md.BEJx9XVj.lean.js → reference_http-api.md.oySXBO8o.lean.js} +0 -0
  483. /package/dist/docs/assets/{reference_skills.md.BFW9retM.lean.js → reference_skills.md.l2ezAcaN.lean.js} +0 -0
  484. /package/dist/docs/assets/{reference_tools.md.CvAHsdSp.lean.js → reference_tools.md.B1up2r9W.lean.js} +0 -0
package/dist/docs/reference/extensions.html ADDED
@@ -0,0 +1,82 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en-US" dir="ltr">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width,initial-scale=1">
6
+ <title>Extensions | Agent SDK</title>
7
+ <meta name="description" content="Mount a package of tools and skills or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/.">
8
+ <meta name="generator" content="VitePress v1.6.4">
9
+ <link rel="preload stylesheet" href="/docs/assets/style.BRuM8477.css" as="style">
10
+ <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
+
12
+ <script type="module" src="/docs/assets/app.CLA03RCz.js"></script>
13
+ <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.DWCwM6p-.js">
15
+ <link rel="modulepreload" href="/docs/assets/chunks/framework.BCISBCiQ.js">
16
+ <link rel="modulepreload" href="/docs/assets/reference_extensions.md.9WQMZe1l.lean.js">
17
+ <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
18
+ <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
19
+ <link rel="alternate" type="text/plain" href="/docs/llms.txt">
20
+ <link rel="alternate" type="text/markdown" href="/docs/reference/extensions.md">
21
+ </head>
22
+ <body>
23
+ <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.102" data-v-c26a5f4f>0.1.102</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/demo.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/code-wiki.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Code wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agents-md.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Living AGENTS.md</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-help.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security help</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Coding-agent skills</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>ab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/create-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>create-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/debug.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>debug</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/framework-map.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>framework-map</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>github</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/hillclimb.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>hillclimb</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/mcp-auth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>mcp-auth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/otel.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>otel</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/setup-slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>setup-slack</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cursor cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Extensions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_reference_extensions" data-v-2e506a34><div><h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages tools and skills an agent installs as one unit. You mount it with a single file under <code>agent/extensions/</code>, and its contributions join the agent under a namespace. The package updates like any other dependency; nothing is copied into your project. A Cursor plugin mounts the same way; see <a href="#mount-a-cursor-plugin">Mount a Cursor plugin</a>.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package, then add one file. The filename is the namespace.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/ci.ts</span></span>
24
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ci </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@acme/ci-triage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
25
+ <span class="line"></span>
26
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ci</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ org: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BUILDKITE_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre></div><p>Every contribution is exposed as <code>&lt;namespace&gt;__&lt;name&gt;</code>. A <code>failed_jobs</code> tool from this mount runs in the agent as <code>ci__failed_jobs</code>, and a <code>triage</code> skill loads as <code>ci__triage</code>. <code>agent-sdk info</code> lists each mount with what it contributed, and <code>GET /v1/info</code> returns the same under <code>extensions</code>.</p><p>Pass the configuration the extension asks for. The extension validates it when the agent loads, so a missing or mistyped field fails <code>agent-sdk validate</code> instead of a tool call later.</p><p>Namespaces follow the tool-name rule, and <code>__</code> is reserved: an authored <code>agent/tools/ci__failed_jobs.ts</code> fails discovery, so nothing outside a mount can pose as one of its tools.</p><h2 id="adjust-a-mounted-extension" tabindex="-1">Adjust a mounted extension <a class="header-anchor" href="#adjust-a-mounted-extension" aria-label="Permalink to &quot;Adjust a mounted extension&quot;">​</a></h2><p>To replace or remove a contribution, mount the extension as a directory and overlay the slot you want to change.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/extensions/ci/</span></span>
27
+ <span class="line"><span>├── extension.ts # the mount: export default ci({ ... })</span></span>
28
+ <span class="line"><span>├── tools/</span></span>
29
+ <span class="line"><span>│ ├── job_log.ts # replaces ci__job_log with your own defineTool</span></span>
30
+ <span class="line"><span>│ └── retry_job.ts # export default disableTool() removes ci__retry_job</span></span>
31
+ <span class="line"><span>└── skills/</span></span>
32
+ <span class="line"><span> └── triage.md # replaces ci__triage</span></span></code></pre></div><p>Use the extension&#39;s own names inside the directory, without the namespace. A file with a name the extension doesn&#39;t contribute adds a new tool or skill under the namespace. <code>disableTool()</code> comes from <code>@cursor/july/extensions</code> and fails discovery when it names a tool the extension doesn&#39;t have, so a typo can&#39;t silently keep a tool alive. A Cursor plugin mount overlays its MCP servers the same way; see below.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p>A Cursor plugin is a directory with <code>.cursor-plugin/plugin.json</code> (or <code>.claude-plugin/plugin.json</code>, or <code>plugin.json</code>) and any of <code>skills/</code>, <code>commands/</code>, <code>agents/</code>, and <code>mcp.json</code>. Copy the plugin into your project and mount it with <code>cursorPlugin</code>. The filename is the namespace, as with any extension.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/notion.ts</span></span>
33
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorPlugin } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
34
+ <span class="line"></span>
35
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> cursorPlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
36
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugins/notion-workspace&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// relative to the project root</span></span>
37
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> variables: { NOTION_TOKEN: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NOTION_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
38
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The plugin joins the agent under that namespace:</p><table tabindex="0"><thead><tr><th>Plugin content</th><th>Becomes</th></tr></thead><tbody><tr><td><code>skills/&lt;name&gt;/SKILL.md</code></td><td>skill <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>commands/&lt;name&gt;.md</code></td><td>skill <code>notion__&lt;name&gt;</code>, since a command is a procedure the model runs on request</td></tr><tr><td><code>agents/&lt;name&gt;.md</code></td><td>subagent <code>notion__&lt;name&gt;</code></td></tr><tr><td>MCP servers in <code>mcp.json</code> or the manifest</td><td>connection <code>notion__&lt;server&gt;</code></td></tr></tbody></table><p><code>variables</code> fills the <code>${NAME}</code> placeholders the plugin&#39;s MCP config declares; names you leave out come from the environment by exact name. A placeholder nothing fills fails <code>agent-sdk validate</code>, so a server never attaches half configured. A server that declares an OAuth client authorizes through <a href="./../guides/mcp-oauth.html">host MCP OAuth</a> as <code>agent-sdk mcp oauth notion__&lt;server&gt;</code>; its secret names collapse the namespace separator, so <code>notion__notion</code> stores <code>MCP_OAUTH_NOTION_NOTION_*</code>. A server that lists <code>enabledTools</code> mounts as an advertised connection with that allowlist and requires the local runtime; <code>agent-sdk validate</code> fails otherwise.</p><p>Mounting a plugin trusts it like authored code: its servers run the commands and read the environment variables its config names. Review a plugin before you vendor it.</p><p>Plugin rules and hooks are not mounted; <code>agent-sdk validate</code> warns when a plugin carries them. To drop or reconfigure one of the plugin&#39;s servers, mount as a directory and overlay <code>mcp-connections/&lt;server&gt;.ts</code>. An overlaid server is never read from the plugin, so it needs no variables.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/extensions/cloudflare/</span></span>
39
+ <span class="line"><span>├── extension.ts # export default cursorPlugin({ path: &quot;plugins/cloudflare&quot; })</span></span>
40
+ <span class="line"><span>└── mcp-connections/</span></span>
41
+ <span class="line"><span> ├── cloudflare-docs.ts # replaces cloudflare__cloudflare-docs with your defineConnection</span></span>
42
+ <span class="line"><span> └── cloudflare-bindings.ts # export default disableConnection() drops it</span></span></code></pre></div><p><code>disableConnection()</code> comes from <code>@cursor/july/extensions</code> and fails discovery when it names a server the plugin doesn&#39;t declare.</p><h2 id="build-an-extension" tabindex="-1">Build an extension <a class="header-anchor" href="#build-an-extension" aria-label="Permalink to &quot;Build an extension&quot;">​</a></h2><p>An extension is a directory laid out like <code>agent/</code>. <code>extension.ts</code> declares it; <code>tools/</code> and <code>skills/</code> hold the contributions in the same authoring forms as <a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>@acme/ci-triage/</span></span>
43
+ <span class="line"><span>├── package.json</span></span>
44
+ <span class="line"><span>├── extension.ts # defineExtension</span></span>
45
+ <span class="line"><span>├── tools/</span></span>
46
+ <span class="line"><span>│ ├── failed_jobs.ts</span></span>
47
+ <span class="line"><span>│ ├── job_log.ts</span></span>
48
+ <span class="line"><span>│ └── retry_job.ts</span></span>
49
+ <span class="line"><span>├── skills/</span></span>
50
+ <span class="line"><span>│ └── triage.md</span></span>
51
+ <span class="line"><span>└── lib/</span></span>
52
+ <span class="line"><span> └── buildkite.ts # shared code, never discovered</span></span></code></pre></div><p>Declare the extension with its root and, when consumers must configure it, a schema for their settings.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// extension.ts</span></span>
53
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineExtension } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
54
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
55
+ <span class="line"></span>
56
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineExtension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
57
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> root: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.dirname,</span></span>
58
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Investigate failing CI builds on Buildkite.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
59
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> config: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
60
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> org: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
61
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> token: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
62
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> logTailLines: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">positive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
63
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
64
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The default export is what consumers call to mount the extension, and it is also how your own modules read the consumer&#39;s settings. Import it and read <code>extension.config</code>; the value is validated and has defaults applied.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// tools/job_log.ts</span></span>
65
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
66
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
67
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> extension </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../extension.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
68
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { jobLogTail } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/buildkite.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
69
+ <span class="line"></span>
70
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
71
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Read the tail of a CI job&#39;s log.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
72
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> effect: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
73
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ pipeline: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), build: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), job: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
74
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pipeline</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">job</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
75
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">org</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">token</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">logTailLines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> extension.config;</span></span>
76
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> jobLogTail</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ org, token, pipeline, build, job, lines: logTailLines });</span></span>
77
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
78
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Because the consumer picks the namespace, have skills and tool descriptions refer to sibling tools by their short names and say they appear under the mount&#39;s namespace (<code>&lt;namespace&gt;__job_log</code>).</p><p>Publish the built <code>extension.js</code> as the package entry point with <code>tools/</code> and <code>skills/</code> beside it. <code>root</code> is read from the built file, so copy <code>skills/*.md</code> into the build output or author skills as <code>.ts</code> with <code>defineSkill</code>.</p><p>Only <code>tools/</code> and <code>skills/</code> are mounted from an extension tree. Instructions, connections, hooks, channels, and the runtime configuration belong to the agent that mounts the extension; <code>agent-sdk validate</code> warns when a tree carries agent slots such as <code>instructions.md</code>, <code>connections/</code>, <code>hooks/</code>, <code>channels/</code>, or <code>schedules/</code>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/cloud-agents.html">Cursor cloud agents</a>: the extension that lets an agent launch and steer cloud agents</li><li><a href="./tools.html">Tools</a>: the tool contract extensions contribute to</li><li><a href="./skills.html">Skills</a>: the skill forms an extension can carry</li><li><a href="./project-layout.html">Project layout</a>: where <code>agent/extensions/</code> sits in the tree</li></ul></div></div></main><footer class="VPDocFooter" data-v-2e506a34 data-v-574f06fa><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-574f06fa><span class="visually-hidden" id="doc-footer-aria-label" data-v-574f06fa>Pager</span><div class="pager" data-v-574f06fa><a class="VPLink link pager-link prev" href="/docs/reference/subagents.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Subagents</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/reference/channels.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Channels</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
79
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"mlVgqvSk\",\"building-with-agents.md\":\"CUSWxlP_\",\"concepts.md\":\"rPzW2HZN\",\"deployment.md\":\"MFPKqsqI\",\"evals.md\":\"CPzDAwoH\",\"guides_agent-to-agent.md\":\"BDb0t1QV\",\"guides_cloud-agents.md\":\"DumwWXba\",\"guides_cloud-runtime.md\":\"BRirbRAN\",\"guides_convert-automation.md\":\"B4sjlodG\",\"guides_github.md\":\"BtPr9GaP\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Dp6cDP7f\",\"guides_opentelemetry.md\":\"BVTXDCRg\",\"guides_slack.md\":\"9oHPye9o\",\"guides_webhooks.md\":\"DKdA43Qm\",\"hillclimbing.md\":\"CpTGTCle\",\"index.md\":\"Kiht7ell\",\"quickstart.md\":\"DdQOF7Y8\",\"reference_agent-config.md\":\"BHeYMgme\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"Cd2f2iyV\",\"reference_cli.md\":\"DfoeyvL0\",\"reference_connections.md\":\"Di6jJAXF\",\"reference_extensions.md\":\"9WQMZe1l\",\"reference_hooks.md\":\"a8BJxMR5\",\"reference_http-api.md\":\"oySXBO8o\",\"reference_instructions.md\":\"CR7XSsGk\",\"reference_playground.md\":\"DnX5nL-B\",\"reference_project-layout.md\":\"CA6QP6Lw\",\"reference_prompt.md\":\"DnaD5dNK\",\"reference_schedules.md\":\"DI_JrHgq\",\"reference_sessions.md\":\"NxFP_CAC\",\"reference_skills.md\":\"l2ezAcaN\",\"reference_subagents.md\":\"CfsIloPm\",\"reference_tools.md\":\"B1up2r9W\",\"scaffolding-agents.md\":\"em43xlY1\",\"skills_ab.md\":\"CsFNatVx\",\"skills_create-agent.md\":\"BVoWPcan\",\"skills_debug.md\":\"CDbPhHfg\",\"skills_evals.md\":\"723kpUmA\",\"skills_framework-map.md\":\"DDa4MeEW\",\"skills_github.md\":\"D0JahM8c\",\"skills_hillclimb.md\":\"B_zJerxA\",\"skills_index.md\":\"DKwIxzGg\",\"skills_mcp-auth.md\":\"DGvFP3HE\",\"skills_otel.md\":\"CgiZryR3\",\"skills_setup-slack.md\":\"BBgx8lUz\",\"storage.md\":\"BOHeqk2M\",\"templates_agentic-owners.md\":\"BZSH4N9z\",\"templates_agents-md.md\":\"CXSMZljE\",\"templates_code-wiki.md\":\"CDYZIBFN\",\"templates_demo.md\":\"BeQX9V3H\",\"templates_pr-autofixer.md\":\"x5zl6-GT\",\"templates_security-help.md\":\"C3Ny_Qr2\",\"templates_security-reviewer.md\":\"lshxbCLK\",\"templates_triage.md\":\"Co4UNzkZ\",\"troubleshooting.md\":\"Cus_YZga\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.102\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Templates\",\"link\":\"/templates/demo\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Code wiki\",\"link\":\"/templates/code-wiki\"},{\"text\":\"Living AGENTS.md\",\"link\":\"/templates/agents-md\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Security help\",\"link\":\"/templates/security-help\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Coding-agent skills\",\"collapsed\":true,\"items\":[{\"text\":\"Overview\",\"link\":\"/skills/\"},{\"text\":\"ab\",\"link\":\"/skills/ab\"},{\"text\":\"create-agent\",\"link\":\"/skills/create-agent\"},{\"text\":\"debug\",\"link\":\"/skills/debug\"},{\"text\":\"evals\",\"link\":\"/skills/evals\"},{\"text\":\"framework-map\",\"link\":\"/skills/framework-map\"},{\"text\":\"github\",\"link\":\"/skills/github\"},{\"text\":\"hillclimb\",\"link\":\"/skills/hillclimb\"},{\"text\":\"mcp-auth\",\"link\":\"/skills/mcp-auth\"},{\"text\":\"otel\",\"link\":\"/skills/otel\"},{\"text\":\"setup-slack\",\"link\":\"/skills/setup-slack\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"Cursor cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Extensions\",\"link\":\"/reference/extensions\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
80
+
81
+ </body>
82
+ </html>
package/dist/docs/reference/extensions.md ADDED
@@ -0,0 +1,200 @@
1
+ # Extensions
2
+
3
+ An extension packages tools and skills an agent installs as one unit. You
4
+ mount it with a single file under `agent/extensions/`, and its
5
+ contributions join the agent under a namespace. The package updates
6
+ like any other dependency; nothing is copied into your project. A Cursor
7
+ plugin mounts the same way; see [Mount a Cursor plugin](#mount-a-cursor-plugin).
8
+
9
+ ## Mount an extension
10
+
11
+ Install the package, then add one file. The filename is the namespace.
12
+
13
+ ```ts
14
+ // agent/extensions/ci.ts
15
+ import ci from "@acme/ci-triage";
16
+
17
+ export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
18
+ ```
19
+
20
+ Every contribution is exposed as `<namespace>__<name>`. A `failed_jobs`
21
+ tool from this mount runs in the agent as `ci__failed_jobs`, and a
22
+ `triage` skill loads as `ci__triage`. `agent-sdk info` lists each mount
23
+ with what it contributed, and `GET /v1/info` returns the same under
24
+ `extensions`.
25
+
26
+ Pass the configuration the extension asks for. The extension validates it
27
+ when the agent loads, so a missing or mistyped field fails
28
+ `agent-sdk validate` instead of a tool call later.
29
+
30
+ Namespaces follow the tool-name rule, and `__` is reserved: an authored
31
+ `agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
32
+ mount can pose as one of its tools.
33
+
34
+ ## Adjust a mounted extension
35
+
36
+ To replace or remove a contribution, mount the extension as a directory
37
+ and overlay the slot you want to change.
38
+
39
+ ```text
40
+ agent/extensions/ci/
41
+ ├── extension.ts # the mount: export default ci({ ... })
42
+ ├── tools/
43
+ │ ├── job_log.ts # replaces ci__job_log with your own defineTool
44
+ │ └── retry_job.ts # export default disableTool() removes ci__retry_job
45
+ └── skills/
46
+ └── triage.md # replaces ci__triage
47
+ ```
48
+
49
+ Use the extension's own names inside the directory, without the
50
+ namespace. A file with a name the extension doesn't contribute adds a
51
+ new tool or skill under the namespace. `disableTool()` comes from
52
+ `@cursor/july/extensions` and fails discovery when it names a tool the
53
+ extension doesn't have, so a typo can't silently keep a tool alive.
54
+ A Cursor plugin mount overlays its MCP servers the same way; see below.
55
+
56
+ ## Mount a Cursor plugin
57
+
58
+ A Cursor plugin is a directory with `.cursor-plugin/plugin.json` (or
59
+ `.claude-plugin/plugin.json`, or `plugin.json`) and any of `skills/`,
60
+ `commands/`, `agents/`, and `mcp.json`. Copy the plugin into your project
61
+ and mount it with `cursorPlugin`. The filename is the namespace, as with
62
+ any extension.
63
+
64
+ ```ts
65
+ // agent/extensions/notion.ts
66
+ import { cursorPlugin } from "@cursor/july/extensions";
67
+
68
+ export default cursorPlugin({
69
+ path: "plugins/notion-workspace", // relative to the project root
70
+ variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
71
+ });
72
+ ```
73
+
74
+ The plugin joins the agent under that namespace:
75
+
76
+ | Plugin content | Becomes |
77
+ | --- | --- |
78
+ | `skills/<name>/SKILL.md` | skill `notion__<name>` |
79
+ | `commands/<name>.md` | skill `notion__<name>`, since a command is a procedure the model runs on request |
80
+ | `agents/<name>.md` | subagent `notion__<name>` |
81
+ | MCP servers in `mcp.json` or the manifest | connection `notion__<server>` |
82
+
83
+ `variables` fills the `${NAME}` placeholders the plugin's MCP config
84
+ declares; names you leave out come from the environment by exact name. A
85
+ placeholder nothing fills fails `agent-sdk validate`, so a server never
86
+ attaches half configured. A server that declares an OAuth client
87
+ authorizes through [host MCP OAuth](/docs/guides/mcp-oauth.md) as
88
+ `agent-sdk mcp oauth notion__<server>`; its secret names collapse the
89
+ namespace separator, so `notion__notion` stores `MCP_OAUTH_NOTION_NOTION_*`.
90
+ A server that lists `enabledTools` mounts as an advertised connection with
91
+ that allowlist and requires the local runtime; `agent-sdk validate` fails
92
+ otherwise.
93
+
94
+ Mounting a plugin trusts it like authored code: its servers run the
95
+ commands and read the environment variables its config names. Review a
96
+ plugin before you vendor it.
97
+
98
+ Plugin rules and hooks are not mounted; `agent-sdk validate` warns when a
99
+ plugin carries them. To drop or reconfigure one of the plugin's servers,
100
+ mount as a directory and overlay `mcp-connections/<server>.ts`. An
101
+ overlaid server is never read from the plugin, so it needs no variables.
102
+
103
+ ```text
104
+ agent/extensions/cloudflare/
105
+ ├── extension.ts # export default cursorPlugin({ path: "plugins/cloudflare" })
106
+ └── mcp-connections/
107
+ ├── cloudflare-docs.ts # replaces cloudflare__cloudflare-docs with your defineConnection
108
+ └── cloudflare-bindings.ts # export default disableConnection() drops it
109
+ ```
110
+
111
+ `disableConnection()` comes from `@cursor/july/extensions` and fails
112
+ discovery when it names a server the plugin doesn't declare.
113
+
114
+ ## Build an extension
115
+
116
+ An extension is a directory laid out like `agent/`. `extension.ts`
117
+ declares it; `tools/` and `skills/` hold the contributions in the same
118
+ authoring forms as [Tools](/docs/reference/tools.md) and [Skills](/docs/reference/skills.md).
119
+
120
+ ```text
121
+ @acme/ci-triage/
122
+ ├── package.json
123
+ ├── extension.ts # defineExtension
124
+ ├── tools/
125
+ │ ├── failed_jobs.ts
126
+ │ ├── job_log.ts
127
+ │ └── retry_job.ts
128
+ ├── skills/
129
+ │ └── triage.md
130
+ └── lib/
131
+ └── buildkite.ts # shared code, never discovered
132
+ ```
133
+
134
+ Declare the extension with its root and, when consumers must configure
135
+ it, a schema for their settings.
136
+
137
+ ```ts
138
+ // extension.ts
139
+ import { defineExtension } from "@cursor/july/extensions";
140
+ import { z } from "zod";
141
+
142
+ export default defineExtension({
143
+ root: import.meta.dirname,
144
+ description: "Investigate failing CI builds on Buildkite.",
145
+ config: z.object({
146
+ org: z.string(),
147
+ token: z.string(),
148
+ logTailLines: z.number().int().positive().default(200),
149
+ }),
150
+ });
151
+ ```
152
+
153
+ The default export is what consumers call to mount the extension, and it
154
+ is also how your own modules read the consumer's settings. Import it and
155
+ read `extension.config`; the value is validated and has defaults applied.
156
+
157
+ ```ts
158
+ // tools/job_log.ts
159
+ import { defineTool } from "@cursor/july/tools";
160
+ import { z } from "zod";
161
+ import extension from "../extension.js";
162
+ import { jobLogTail } from "../lib/buildkite.js";
163
+
164
+ export default defineTool({
165
+ description: "Read the tail of a CI job's log.",
166
+ effect: "read",
167
+ inputSchema: z.object({ pipeline: z.string(), build: z.number(), job: z.string() }),
168
+ async execute({ pipeline, build, job }) {
169
+ const { org, token, logTailLines } = extension.config;
170
+ return jobLogTail({ org, token, pipeline, build, job, lines: logTailLines });
171
+ },
172
+ });
173
+ ```
174
+
175
+ Because the consumer picks the namespace, have skills and tool
176
+ descriptions refer to sibling tools by their short names and say they
177
+ appear under the mount's namespace (`<namespace>__job_log`).
178
+
179
+ Publish the built `extension.js` as the package entry point with
180
+ `tools/` and `skills/` beside it. `root` is read from the built file, so
181
+ copy `skills/*.md` into the build output or author skills as `.ts` with
182
+ `defineSkill`.
183
+
184
+ Only `tools/` and `skills/` are mounted from an extension tree.
185
+ Instructions, connections, hooks, channels, and the runtime
186
+ configuration belong to the agent that mounts the extension;
187
+ `agent-sdk validate` warns when a tree carries agent slots such as
188
+ `instructions.md`, `connections/`, `hooks/`, `channels/`, or
189
+ `schedules/`.
190
+
191
+ ## What's next
192
+
193
+ Continue with these pages:
194
+
195
+ - [Cursor cloud agents](/docs/guides/cloud-agents.md): the extension that
196
+ lets an agent launch and steer cloud agents
197
+ - [Tools](/docs/reference/tools.md): the tool contract extensions contribute to
198
+ - [Skills](/docs/reference/skills.md): the skill forms an extension can carry
199
+ - [Project layout](/docs/reference/project-layout.md): where `agent/extensions/` sits
200
+ in the tree