@cursor/july 0.1.111 → 0.1.113

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 (441) hide show
  1. package/README.md +4 -0
  2. package/dist/bin/agent-serve.js +20 -4
  3. package/dist/channels/checks.d.ts +10 -0
  4. package/dist/channels/checks.d.ts.map +1 -1
  5. package/dist/channels/github/github-channel.d.ts +29 -19
  6. package/dist/channels/github/github-channel.d.ts.map +1 -1
  7. package/dist/channels/github/github-channel.js +29 -19
  8. package/dist/channels/origin/checks.d.ts +1 -1
  9. package/dist/channels/origin/checks.d.ts.map +1 -1
  10. package/dist/channels/slack/agentic-delivery.d.ts.map +1 -1
  11. package/dist/channels/slack/agentic-delivery.js +2 -0
  12. package/dist/channels/slack/dispatch.d.ts +11 -1
  13. package/dist/channels/slack/dispatch.d.ts.map +1 -1
  14. package/dist/channels/slack/dispatch.js +146 -39
  15. package/dist/channels/slack/placeholder.d.ts +26 -0
  16. package/dist/channels/slack/placeholder.d.ts.map +1 -1
  17. package/dist/channels/slack/placeholder.js +28 -0
  18. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  19. package/dist/channels/slack/slack-channel.js +9 -16
  20. package/dist/docs/404.html +2 -2
  21. package/dist/docs/assets/{app.Drol6mi6.js → app.CAeK13eM.js} +4 -4
  22. package/dist/docs/assets/building-with-agents.md.BBCx0AUo.js +9 -0
  23. package/dist/docs/assets/building-with-agents.md.BBCx0AUo.lean.js +1 -0
  24. package/dist/docs/assets/chunks/@localSearchIndexroot.Ck9E52Ls.js +1 -0
  25. package/dist/docs/assets/chunks/{VPLocalSearchBox.CdqoBZJX.js → VPLocalSearchBox.C9LbPHod.js} +1 -1
  26. package/dist/docs/assets/chunks/{arc.BVX3ycTn.js → arc.CmMq2zmS.js} +1 -1
  27. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.CcChnMxX.js → architectureDiagram-Q4EWVU46.CCXB8Uj5.js} +1 -1
  28. package/dist/docs/assets/chunks/{baseUniq.xwtXO-yt.js → baseUniq.CyQo6eLe.js} +1 -1
  29. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.CijZ_taK.js → blockDiagram-DXYQGD6D.JYq6w91N.js} +1 -1
  30. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.0FBvwBvK.js → c4Diagram-AHTNJAMY.BRV8GPJJ.js} +1 -1
  31. package/dist/docs/assets/chunks/channel.BHiYmnZ4.js +1 -0
  32. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.CELMmMDA.js → chunk-4BX2VUAB.Bv4ooYQR.js} +1 -1
  33. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.C4bhFtSm.js → chunk-4TB4RGXK.t4JtKPcj.js} +1 -1
  34. package/dist/docs/assets/chunks/{chunk-55IACEB6.ZnQ9gRRQ.js → chunk-55IACEB6.34lCHj9Y.js} +1 -1
  35. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.DPlmglG-.js → chunk-EDXVE4YY.BSwrPNrt.js} +1 -1
  36. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.BrUk8pff.js → chunk-FMBD7UC4.Beeun-R-.js} +1 -1
  37. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CcmWIncu.js → chunk-OYMX7WX6.BUUFUcJc.js} +1 -1
  38. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.D65-cs8I.js → chunk-QZHKN3VN.B2XjHzN_.js} +1 -1
  39. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.qoXZpG9F.js → chunk-YZCP3GAM.CLYG8znk.js} +1 -1
  40. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.Degh8l90.js +1 -0
  41. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.Degh8l90.js +1 -0
  42. package/dist/docs/assets/chunks/clone.BIywbczV.js +1 -0
  43. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.8rYtqudO.js → cose-bilkent-S5V4N54A.DVEa6fZp.js} +1 -1
  44. package/dist/docs/assets/chunks/{dagre-KV5264BT.DrRP1fOh.js → dagre-KV5264BT.C9PZQK-S.js} +1 -1
  45. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.DHj_xA2_.js → diagram-5BDNPKRD.DoN0uv3Y.js} +1 -1
  46. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Bz_6nAKj.js → diagram-G4DWMVQ6.Czv3duqx.js} +1 -1
  47. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.BWA0xSW9.js → diagram-MMDJMWI5.BinJ5kWb.js} +1 -1
  48. package/dist/docs/assets/chunks/{diagram-TYMM5635.CpTJLNJI.js → diagram-TYMM5635.DW326M4K.js} +1 -1
  49. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.-7AWWSrP.js → erDiagram-SMLLAGMA.U2pR_OA7.js} +1 -1
  50. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BTnQ742_.js → flowDiagram-DWJPFMVM.ByWJXeYK.js} +1 -1
  51. package/dist/docs/assets/chunks/framework.BNw1pucY.js +19 -0
  52. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.B5_HiiQ5.js → ganttDiagram-T4ZO3ILL.OquF0Rtg.js} +1 -1
  53. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.CZcNTFZd.js → gitGraphDiagram-UUTBAWPF.Bpn01P7X.js} +1 -1
  54. package/dist/docs/assets/chunks/{graph.V2GLaab4.js → graph.CNRB6ETL.js} +1 -1
  55. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.7pZOkCCU.js → infoDiagram-42DDH7IO.CqhknMWi.js} +1 -1
  56. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.DSMo3Qa3.js → ishikawaDiagram-UXIWVN3A.C6xpR2af.js} +1 -1
  57. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.BNEgWN1S.js → journeyDiagram-VCZTEJTY.Cg5f7oB3.js} +1 -1
  58. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.B-4d4tC7.js → kanban-definition-6JOO6SKY.Cx9YTwlU.js} +1 -1
  59. package/dist/docs/assets/chunks/{layout.Dvbn9nSb.js → layout.ljS-wFtK.js} +1 -1
  60. package/dist/docs/assets/chunks/{linear.D2GM4p4b.js → linear.jSxNrsFC.js} +1 -1
  61. package/dist/docs/assets/chunks/{min.DVBtLK-B.js → min.Cum8AlQw.js} +1 -1
  62. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.CnJRI55x.js → mindmap-definition-QFDTVHPH.BLiysLpe.js} +1 -1
  63. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.CtoaTFlA.js → pieDiagram-DEJITSTG.BoIDyuKF.js} +1 -1
  64. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.DtT24_vN.js → quadrantDiagram-34T5L4WZ.DLkpDytR.js} +1 -1
  65. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.CjSO4o8f.js → requirementDiagram-MS252O5E.DqTVqSu2.js} +1 -1
  66. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.-wWiIVWa.js → sankeyDiagram-XADWPNL6.CG_6FF7j.js} +1 -1
  67. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.DSk8s4gX.js → sequenceDiagram-FGHM5R23.BIp9602K.js} +1 -1
  68. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.BFKAsdkN.js → stateDiagram-FHFEXIEX.COSXsD9I.js} +1 -1
  69. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.qrxrbFsX.js +1 -0
  70. package/dist/docs/assets/chunks/{theme.C0MctGaz.js → theme.CXJ7PNwy.js} +2 -2
  71. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.TUNJbAFe.js → timeline-definition-GMOUNBTQ.CXdVqkLq.js} +1 -1
  72. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.C-RGNnk4.js → vennDiagram-DHZGUBPP.CZxGuc4r.js} +1 -1
  73. package/dist/docs/assets/chunks/{wardley-RL74JXVD.g5efOWmT.js → wardley-RL74JXVD.3oVgfqQk.js} +1 -1
  74. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.DH4zt73Y.js → wardleyDiagram-NUSXRM2D.6_irCgGJ.js} +1 -1
  75. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.B-3k6bF6.js → xychartDiagram-5P7HB3ND.TRPe92m3.js} +1 -1
  76. package/dist/docs/assets/deployment.md.D2jQZuFx.js +32 -0
  77. package/dist/docs/assets/deployment.md.D2jQZuFx.lean.js +1 -0
  78. package/dist/docs/assets/evals.md.D3Y3Aixt.js +72 -0
  79. package/dist/docs/assets/evals.md.D3Y3Aixt.lean.js +1 -0
  80. package/dist/docs/assets/guides_agent-to-agent.md.CD4T5FIl.js +41 -0
  81. package/dist/docs/assets/guides_agent-to-agent.md.CD4T5FIl.lean.js +1 -0
  82. package/dist/docs/assets/guides_bitbucket.md.mpevW-VP.js +145 -0
  83. package/dist/docs/assets/guides_bitbucket.md.mpevW-VP.lean.js +1 -0
  84. package/dist/docs/assets/guides_cloud-agents.md.Cp1O3u-X.js +15 -0
  85. package/dist/docs/assets/guides_cloud-agents.md.Cp1O3u-X.lean.js +1 -0
  86. package/dist/docs/assets/guides_convert-automation.md.CqEyfP6Y.js +43 -0
  87. package/dist/docs/assets/guides_convert-automation.md.CqEyfP6Y.lean.js +1 -0
  88. package/dist/docs/assets/guides_github.md.BwpBp3ed.js +156 -0
  89. package/dist/docs/assets/guides_github.md.BwpBp3ed.lean.js +1 -0
  90. package/dist/docs/assets/guides_gitlab.md.DaEC3nMk.js +153 -0
  91. package/dist/docs/assets/guides_gitlab.md.DaEC3nMk.lean.js +1 -0
  92. package/dist/docs/assets/guides_grokbot-agents.md.CMhZNdEU.js +16 -0
  93. package/dist/docs/assets/guides_grokbot-agents.md.CMhZNdEU.lean.js +1 -0
  94. package/dist/docs/assets/guides_improve.md.Bnp4F99w.js +22 -0
  95. package/dist/docs/assets/guides_improve.md.Bnp4F99w.lean.js +1 -0
  96. package/dist/docs/assets/guides_jev.md.F5fAkkfN.js +189 -0
  97. package/dist/docs/assets/guides_jev.md.F5fAkkfN.lean.js +1 -0
  98. package/dist/docs/assets/guides_mcp-oauth.md.bSFakfCY.js +50 -0
  99. package/dist/docs/assets/guides_mcp-oauth.md.bSFakfCY.lean.js +1 -0
  100. package/dist/docs/assets/guides_opentelemetry.md.BKDxQmmd.js +35 -0
  101. package/dist/docs/assets/guides_opentelemetry.md.BKDxQmmd.lean.js +1 -0
  102. package/dist/docs/assets/guides_slack.md.Bo96y42E.js +70 -0
  103. package/dist/docs/assets/guides_slack.md.Bo96y42E.lean.js +1 -0
  104. package/dist/docs/assets/guides_webhooks.md.1A72_VEE.js +92 -0
  105. package/dist/docs/assets/guides_webhooks.md.1A72_VEE.lean.js +1 -0
  106. package/dist/docs/assets/hillclimbing.md.D4E1o5Sa.js +7 -0
  107. package/dist/docs/assets/hillclimbing.md.D4E1o5Sa.lean.js +1 -0
  108. package/dist/docs/assets/{index.md.BFVyY2KT.js → index.md.C-t81M5J.js} +2 -2
  109. package/dist/docs/assets/{index.md.BFVyY2KT.lean.js → index.md.C-t81M5J.lean.js} +1 -1
  110. package/dist/docs/assets/{quickstart.md.D3MjSZN-.js → quickstart.md.DAvVhuuU.js} +1 -1
  111. package/dist/docs/assets/{quickstart.md.D3MjSZN-.lean.js → quickstart.md.DAvVhuuU.lean.js} +1 -1
  112. package/dist/docs/assets/{reference_agent-config.md.CfVA-LZJ.js → reference_agent-config.md.DGPyw7ms.js} +1 -1
  113. package/dist/docs/assets/{reference_agent-config.md.CfVA-LZJ.lean.js → reference_agent-config.md.DGPyw7ms.lean.js} +1 -1
  114. package/dist/docs/assets/{reference_artifacts.md.Vf7qyIZ-.js → reference_artifacts.md.Bu_4HmsD.js} +1 -1
  115. package/dist/docs/assets/{reference_artifacts.md.Vf7qyIZ-.lean.js → reference_artifacts.md.Bu_4HmsD.lean.js} +1 -1
  116. package/dist/docs/assets/{reference_channels.md.icqLKcTc.js → reference_channels.md.nFWbzAic.js} +1 -1
  117. package/dist/docs/assets/{reference_channels.md.icqLKcTc.lean.js → reference_channels.md.nFWbzAic.lean.js} +1 -1
  118. package/dist/docs/assets/{reference_cli.md.B2dBL6L8.js → reference_cli.md.DLWDz9ij.js} +3 -1
  119. package/dist/docs/assets/{reference_cli.md.B2dBL6L8.lean.js → reference_cli.md.DLWDz9ij.lean.js} +1 -1
  120. package/dist/docs/assets/{reference_connections.md.Cb3U_c8n.js → reference_connections.md.Je9dMsdd.js} +2 -2
  121. package/dist/docs/assets/{reference_connections.md.Cb3U_c8n.lean.js → reference_connections.md.Je9dMsdd.lean.js} +1 -1
  122. package/dist/docs/assets/reference_evals.md.DNJzM_yf.js +57 -0
  123. package/dist/docs/assets/reference_evals.md.DNJzM_yf.lean.js +1 -0
  124. package/dist/docs/assets/reference_extensions.md.Cv5aLCz_.js +58 -0
  125. package/dist/docs/assets/reference_extensions.md.Cv5aLCz_.lean.js +1 -0
  126. package/dist/docs/assets/{reference_hooks.md.CZuynAxj.js → reference_hooks.md.B7uzNENk.js} +2 -2
  127. package/dist/docs/assets/{reference_hooks.md.CZuynAxj.lean.js → reference_hooks.md.B7uzNENk.lean.js} +1 -1
  128. package/dist/docs/assets/{reference_http-api.md.DTKcYE6L.js → reference_http-api.md.CduHavZ2.js} +1 -1
  129. package/dist/docs/assets/{reference_http-api.md.DTKcYE6L.lean.js → reference_http-api.md.CduHavZ2.lean.js} +1 -1
  130. package/dist/docs/assets/{reference_instructions.md.D7gkckK-.js → reference_instructions.md.CU1My5My.js} +1 -1
  131. package/dist/docs/assets/{reference_instructions.md.D7gkckK-.lean.js → reference_instructions.md.CU1My5My.lean.js} +1 -1
  132. package/dist/docs/assets/{reference_playground.md.D2YExv5K.js → reference_playground.md.Ch2d0Iqi.js} +1 -1
  133. package/dist/docs/assets/{reference_playground.md.D2YExv5K.lean.js → reference_playground.md.Ch2d0Iqi.lean.js} +1 -1
  134. package/dist/docs/assets/{reference_project-layout.md.DPxbUJyt.js → reference_project-layout.md.BGhgpy9V.js} +1 -1
  135. package/dist/docs/assets/{reference_project-layout.md.DPxbUJyt.lean.js → reference_project-layout.md.BGhgpy9V.lean.js} +1 -1
  136. package/dist/docs/assets/{reference_prompt.md.BQ5uAv1F.js → reference_prompt.md.Ccp0R53H.js} +1 -1
  137. package/dist/docs/assets/{reference_prompt.md.BQ5uAv1F.lean.js → reference_prompt.md.Ccp0R53H.lean.js} +1 -1
  138. package/dist/docs/assets/{reference_schedules.md.BasfZWO-.js → reference_schedules.md.B2Nm6FaD.js} +1 -1
  139. package/dist/docs/assets/{reference_schedules.md.BasfZWO-.lean.js → reference_schedules.md.B2Nm6FaD.lean.js} +1 -1
  140. package/dist/docs/assets/{reference_sessions.md.YKvIsWAx.js → reference_sessions.md.1_6Vyv7x.js} +1 -1
  141. package/dist/docs/assets/{reference_sessions.md.YKvIsWAx.lean.js → reference_sessions.md.1_6Vyv7x.lean.js} +1 -1
  142. package/dist/docs/assets/{reference_skills.md.rNgpsGd0.js → reference_skills.md.DjQkRefx.js} +1 -1
  143. package/dist/docs/assets/{reference_skills.md.rNgpsGd0.lean.js → reference_skills.md.DjQkRefx.lean.js} +1 -1
  144. package/dist/docs/assets/{reference_subagents.md.e5qitjJt.js → reference_subagents.md.Dl16gcBj.js} +2 -2
  145. package/dist/docs/assets/{reference_subagents.md.e5qitjJt.lean.js → reference_subagents.md.Dl16gcBj.lean.js} +1 -1
  146. package/dist/docs/assets/{reference_tools.md.BdCO2aHZ.js → reference_tools.md.B1dH1lpa.js} +3 -3
  147. package/dist/docs/assets/{reference_tools.md.BdCO2aHZ.lean.js → reference_tools.md.B1dH1lpa.lean.js} +1 -1
  148. package/dist/docs/assets/{templates_agentic-owners.md.Da_AGDlH.js → templates_agentic-owners.md.9M575F5C.js} +1 -1
  149. package/dist/docs/assets/{templates_agentic-owners.md.Da_AGDlH.lean.js → templates_agentic-owners.md.9M575F5C.lean.js} +1 -1
  150. package/dist/docs/assets/{templates_pr-autofixer.md.DqxocIGh.js → templates_pr-autofixer.md.ws0DDXDy.js} +1 -1
  151. package/dist/docs/assets/{templates_pr-autofixer.md.DqxocIGh.lean.js → templates_pr-autofixer.md.ws0DDXDy.lean.js} +1 -1
  152. package/dist/docs/assets/{templates_security-reviewer.md.Bhnvd8VE.js → templates_security-reviewer.md.KEFYXzfK.js} +1 -1
  153. package/dist/docs/assets/{templates_security-reviewer.md.Bhnvd8VE.lean.js → templates_security-reviewer.md.KEFYXzfK.lean.js} +1 -1
  154. package/dist/docs/assets/templates_thermo-quality-review.md.VNJ_mohX.js +3 -0
  155. package/dist/docs/assets/templates_thermo-quality-review.md.VNJ_mohX.lean.js +1 -0
  156. package/dist/docs/assets/templates_thermo-review.md.Hi3zWOkP.js +3 -0
  157. package/dist/docs/assets/templates_thermo-review.md.Hi3zWOkP.lean.js +1 -0
  158. package/dist/docs/assets/{templates_triage.md.BdBWO9Ic.js → templates_triage.md.CVGe_FG6.js} +1 -1
  159. package/dist/docs/assets/{templates_triage.md.BdBWO9Ic.lean.js → templates_triage.md.CVGe_FG6.lean.js} +1 -1
  160. package/dist/docs/assets/troubleshooting.md.mnfFG2Em.js +1 -0
  161. package/dist/docs/assets/troubleshooting.md.mnfFG2Em.lean.js +1 -0
  162. package/dist/docs/building-with-agents.html +44 -48
  163. package/dist/docs/building-with-agents.md +94 -82
  164. package/dist/docs/deployment.html +59 -78
  165. package/dist/docs/deployment.md +117 -363
  166. package/dist/docs/evals.html +85 -224
  167. package/dist/docs/evals.md +149 -673
  168. package/dist/docs/guides/agent-to-agent.html +74 -47
  169. package/dist/docs/guides/agent-to-agent.md +128 -46
  170. package/dist/docs/guides/bitbucket.html +179 -44
  171. package/dist/docs/guides/bitbucket.md +249 -48
  172. package/dist/docs/guides/cloud-agents.html +46 -40
  173. package/dist/docs/guides/cloud-agents.md +119 -66
  174. package/dist/docs/guides/convert-automation.html +80 -49
  175. package/dist/docs/guides/convert-automation.md +156 -147
  176. package/dist/docs/guides/github.html +184 -92
  177. package/dist/docs/guides/github.md +260 -245
  178. package/dist/docs/guides/gitlab.html +184 -45
  179. package/dist/docs/guides/gitlab.md +249 -50
  180. package/dist/docs/guides/grokbot-agents.html +48 -41
  181. package/dist/docs/guides/grokbot-agents.md +99 -53
  182. package/dist/docs/guides/improve.html +48 -40
  183. package/dist/docs/guides/improve.md +111 -58
  184. package/dist/docs/guides/jev.html +248 -0
  185. package/dist/docs/guides/jev.md +348 -0
  186. package/dist/docs/guides/mcp-oauth.html +74 -52
  187. package/dist/docs/guides/mcp-oauth.md +111 -121
  188. package/dist/docs/guides/opentelemetry.html +63 -54
  189. package/dist/docs/guides/opentelemetry.md +96 -165
  190. package/dist/docs/guides/slack.html +83 -59
  191. package/dist/docs/guides/slack.md +157 -227
  192. package/dist/docs/guides/webhooks.html +97 -230
  193. package/dist/docs/guides/webhooks.md +154 -385
  194. package/dist/docs/hashmap.json +1 -1
  195. package/dist/docs/hillclimbing.html +44 -38
  196. package/dist/docs/hillclimbing.md +101 -55
  197. package/dist/docs/index.html +38 -38
  198. package/dist/docs/index.md +2 -0
  199. package/dist/docs/llms-full.txt +3490 -3146
  200. package/dist/docs/llms.txt +22 -18
  201. package/dist/docs/quickstart.html +37 -37
  202. package/dist/docs/reference/agent-config.html +37 -37
  203. package/dist/docs/reference/artifacts.html +38 -38
  204. package/dist/docs/reference/channels.html +37 -37
  205. package/dist/docs/reference/cli.html +39 -37
  206. package/dist/docs/reference/cli.md +2 -0
  207. package/dist/docs/reference/connections.html +38 -38
  208. package/dist/docs/reference/connections.md +1 -1
  209. package/dist/docs/reference/evals.html +116 -0
  210. package/dist/docs/reference/evals.md +293 -0
  211. package/dist/docs/reference/extensions.html +80 -84
  212. package/dist/docs/reference/extensions.md +131 -202
  213. package/dist/docs/reference/hooks.html +39 -39
  214. package/dist/docs/reference/hooks.md +34 -34
  215. package/dist/docs/reference/http-api.html +37 -37
  216. package/dist/docs/reference/instructions.html +37 -37
  217. package/dist/docs/reference/playground.html +37 -37
  218. package/dist/docs/reference/project-layout.html +37 -37
  219. package/dist/docs/reference/prompt.html +37 -37
  220. package/dist/docs/reference/schedules.html +37 -37
  221. package/dist/docs/reference/sessions.html +37 -37
  222. package/dist/docs/reference/skills.html +37 -37
  223. package/dist/docs/reference/subagents.html +38 -38
  224. package/dist/docs/reference/subagents.md +1 -1
  225. package/dist/docs/reference/tools.html +38 -38
  226. package/dist/docs/reference/tools.md +4 -0
  227. package/dist/docs/templates/agentic-owners.html +38 -38
  228. package/dist/docs/templates/pr-autofixer.html +37 -37
  229. package/dist/docs/templates/security-reviewer.html +38 -38
  230. package/dist/docs/templates/thermo-quality-review.html +62 -0
  231. package/dist/docs/templates/thermo-quality-review.md +75 -0
  232. package/dist/docs/templates/thermo-review.html +62 -0
  233. package/dist/docs/templates/thermo-review.md +74 -0
  234. package/dist/docs/templates/triage.html +37 -37
  235. package/dist/docs/troubleshooting.html +38 -38
  236. package/dist/docs/troubleshooting.md +97 -66
  237. package/dist/extensions/cursor-cloud-agents/skills/handoff.md +3 -7
  238. package/dist/extensions/improve/extension.d.ts +3 -1
  239. package/dist/extensions/improve/extension.d.ts.map +1 -1
  240. package/dist/extensions/improve/extension.js +4 -2
  241. package/dist/extensions/improve/skills/yourself.js +1 -1
  242. package/dist/extensions/jev/extension.d.ts +43 -0
  243. package/dist/extensions/jev/extension.d.ts.map +1 -0
  244. package/dist/extensions/jev/extension.js +47 -0
  245. package/dist/extensions/jev/lib/evaluate.d.ts +101 -0
  246. package/dist/extensions/jev/lib/evaluate.d.ts.map +1 -0
  247. package/dist/extensions/jev/lib/evaluate.js +167 -0
  248. package/dist/extensions/jev/skills/gated-write.md +25 -0
  249. package/dist/extensions/jev/skills/questions.md +33 -0
  250. package/dist/extensions/jev/tools/evaluate.d.ts +4 -0
  251. package/dist/extensions/jev/tools/evaluate.d.ts.map +1 -0
  252. package/dist/extensions/jev/tools/evaluate.js +88 -0
  253. package/dist/extensions.d.ts +1 -1
  254. package/dist/extensions.d.ts.map +1 -1
  255. package/dist/extensions.js +2 -0
  256. package/dist/filesystem.d.ts +46 -2
  257. package/dist/filesystem.d.ts.map +1 -1
  258. package/dist/filesystem.js +149 -102
  259. package/dist/index.d.ts +2 -2
  260. package/dist/index.d.ts.map +1 -1
  261. package/dist/index.js +1 -1
  262. package/dist/internal/advertise-tools.d.ts.map +1 -1
  263. package/dist/internal/advertise-tools.js +6 -0
  264. package/dist/internal/cli-ax.d.ts +6 -0
  265. package/dist/internal/cli-ax.d.ts.map +1 -1
  266. package/dist/internal/cli-ax.js +72 -14
  267. package/dist/internal/continuation-identity.d.ts.map +1 -1
  268. package/dist/internal/continuation-identity.js +1 -0
  269. package/dist/internal/cursor-agent-template.d.ts +1 -1
  270. package/dist/internal/cursor-agent-template.d.ts.map +1 -1
  271. package/dist/internal/cursor-agent-template.js +2 -0
  272. package/dist/internal/discovery/connections.d.ts.map +1 -1
  273. package/dist/internal/discovery/connections.js +18 -0
  274. package/dist/internal/discovery/extensions.d.ts.map +1 -1
  275. package/dist/internal/discovery/extensions.js +8 -4
  276. package/dist/internal/discovery/info.d.ts.map +1 -1
  277. package/dist/internal/discovery/info.js +1 -0
  278. package/dist/internal/filesystem/tools.d.ts.map +1 -1
  279. package/dist/internal/filesystem/tools.js +2 -2
  280. package/dist/internal/filesystem/walk.d.ts +7 -4
  281. package/dist/internal/filesystem/walk.d.ts.map +1 -1
  282. package/dist/internal/filesystem/walk.js +34 -11
  283. package/dist/internal/hosted-admission-adapter.d.ts +3 -0
  284. package/dist/internal/hosted-admission-adapter.d.ts.map +1 -1
  285. package/dist/internal/hosted-delivery-protocol.d.ts +20 -0
  286. package/dist/internal/hosted-delivery-protocol.d.ts.map +1 -1
  287. package/dist/internal/hosted-delivery-protocol.js +51 -1
  288. package/dist/internal/hosted-delivery.d.ts.map +1 -1
  289. package/dist/internal/hosted-delivery.js +23 -25
  290. package/dist/internal/hosted-execution-diag.d.ts +12 -4
  291. package/dist/internal/hosted-execution-diag.d.ts.map +1 -1
  292. package/dist/internal/hosted-execution-diag.js +26 -4
  293. package/dist/internal/hosted-execution-flush.d.ts +1 -0
  294. package/dist/internal/hosted-execution-flush.d.ts.map +1 -1
  295. package/dist/internal/hosted-execution-flush.js +4 -2
  296. package/dist/internal/init-project.d.ts.map +1 -1
  297. package/dist/internal/init-project.js +4 -0
  298. package/dist/internal/server.d.ts.map +1 -1
  299. package/dist/internal/server.js +111 -48
  300. package/dist/internal/session-engine.d.ts +4 -1
  301. package/dist/internal/session-engine.d.ts.map +1 -1
  302. package/dist/internal/session-engine.js +39 -9
  303. package/dist/internal/skill-catalog.d.ts +28 -0
  304. package/dist/internal/skill-catalog.d.ts.map +1 -0
  305. package/dist/internal/skill-catalog.js +44 -0
  306. package/dist/playground/assets/index-DSMAewbx.css +1 -0
  307. package/dist/playground/assets/index-De_lpFxE.js +67 -0
  308. package/dist/playground/index.html +2 -2
  309. package/dist/types.d.ts +32 -3
  310. package/dist/types.d.ts.map +1 -1
  311. package/docs/README.md +2 -0
  312. package/docs/building-with-agents.md +96 -84
  313. package/docs/deployment.md +118 -364
  314. package/docs/evals.md +149 -673
  315. package/docs/guides/agent-to-agent.md +130 -48
  316. package/docs/guides/bitbucket.md +250 -49
  317. package/docs/guides/cloud-agents.md +119 -67
  318. package/docs/guides/convert-automation.md +157 -148
  319. package/docs/guides/github.md +261 -246
  320. package/docs/guides/gitlab.md +250 -51
  321. package/docs/guides/grokbot-agents.md +100 -55
  322. package/docs/guides/improve.md +112 -59
  323. package/docs/guides/jev.md +353 -0
  324. package/docs/guides/mcp-oauth.md +112 -122
  325. package/docs/guides/opentelemetry.md +97 -166
  326. package/docs/guides/slack.md +158 -228
  327. package/docs/guides/webhooks.md +155 -386
  328. package/docs/hillclimbing.md +102 -56
  329. package/docs/reference/cli.md +2 -0
  330. package/docs/reference/connections.md +1 -1
  331. package/docs/reference/evals.md +298 -0
  332. package/docs/reference/extensions.md +132 -203
  333. package/docs/reference/hooks.md +34 -34
  334. package/docs/reference/subagents.md +1 -1
  335. package/docs/reference/tools.md +4 -0
  336. package/docs/templates/thermo-quality-review.md +80 -0
  337. package/docs/templates/thermo-review.md +79 -0
  338. package/docs/troubleshooting.md +98 -67
  339. package/package.json +8 -1
  340. package/skills/github/SKILL.md +21 -13
  341. package/src/bin/agent-serve.ts +24 -3
  342. package/src/channels/checks.ts +8 -0
  343. package/src/channels/github/github-channel.ts +29 -19
  344. package/src/channels/origin/checks.ts +3 -1
  345. package/src/channels/slack/agentic-delivery.ts +2 -0
  346. package/src/channels/slack/dispatch.ts +131 -4
  347. package/src/channels/slack/placeholder.ts +51 -0
  348. package/src/channels/slack/slack-channel.ts +9 -2
  349. package/src/extensions/cursor-cloud-agents/skills/handoff.md +3 -7
  350. package/src/extensions/improve/extension.ts +4 -2
  351. package/src/extensions/improve/skills/yourself.ts +1 -1
  352. package/src/extensions/jev/extension.ts +95 -0
  353. package/src/extensions/jev/lib/evaluate.ts +289 -0
  354. package/src/extensions/jev/skills/gated-write.md +25 -0
  355. package/src/extensions/jev/skills/questions.md +33 -0
  356. package/src/extensions/jev/tools/evaluate.ts +90 -0
  357. package/src/extensions.ts +2 -0
  358. package/src/filesystem.ts +168 -65
  359. package/src/index.ts +3 -0
  360. package/src/internal/advertise-tools.ts +6 -0
  361. package/src/internal/cli-ax.ts +88 -15
  362. package/src/internal/continuation-identity.ts +1 -0
  363. package/src/internal/cursor-agent-template.ts +2 -0
  364. package/src/internal/discovery/connections.ts +21 -0
  365. package/src/internal/discovery/extensions.ts +12 -4
  366. package/src/internal/discovery/info.ts +1 -0
  367. package/src/internal/filesystem/tools.ts +2 -0
  368. package/src/internal/filesystem/walk.ts +60 -15
  369. package/src/internal/hosted-admission-adapter.ts +3 -0
  370. package/src/internal/hosted-delivery-protocol.ts +82 -1
  371. package/src/internal/hosted-delivery.ts +23 -0
  372. package/src/internal/hosted-execution-diag.ts +33 -4
  373. package/src/internal/hosted-execution-flush.ts +4 -0
  374. package/src/internal/init-project.ts +4 -0
  375. package/src/internal/server.ts +130 -53
  376. package/src/internal/session-engine.ts +46 -8
  377. package/src/internal/skill-catalog.ts +69 -0
  378. package/src/types.ts +33 -3
  379. package/templates/thermo-quality-review/README.md +35 -0
  380. package/templates/thermo-quality-review/agent/agent.ts +8 -0
  381. package/templates/thermo-quality-review/agent/channels/github.ts +42 -0
  382. package/templates/thermo-quality-review/agent/instructions.md +43 -0
  383. package/templates/thermo-quality-review/agent/tools/post_findings.ts +70 -0
  384. package/templates/thermo-quality-review/evals/evals.config.ts +5 -0
  385. package/templates/thermo-quality-review/evals/review.eval.ts +62 -0
  386. package/templates/thermo-quality-review/package.json +18 -0
  387. package/templates/thermo-quality-review/tsconfig.json +12 -0
  388. package/templates/thermo-review/README.md +35 -0
  389. package/templates/thermo-review/agent/agent.ts +8 -0
  390. package/templates/thermo-review/agent/channels/github.ts +42 -0
  391. package/templates/thermo-review/agent/instructions.md +40 -0
  392. package/templates/thermo-review/agent/tools/post_findings.ts +70 -0
  393. package/templates/thermo-review/evals/evals.config.ts +5 -0
  394. package/templates/thermo-review/evals/review.eval.ts +53 -0
  395. package/templates/thermo-review/package.json +18 -0
  396. package/templates/thermo-review/tsconfig.json +12 -0
  397. package/dist/docs/assets/building-with-agents.md.CEGVXkmO.js +0 -13
  398. package/dist/docs/assets/building-with-agents.md.CEGVXkmO.lean.js +0 -1
  399. package/dist/docs/assets/chunks/@localSearchIndexroot.DtXk1hy-.js +0 -1
  400. package/dist/docs/assets/chunks/channel.Bkv1N-gK.js +0 -1
  401. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CZDco1o8.js +0 -1
  402. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CZDco1o8.js +0 -1
  403. package/dist/docs/assets/chunks/clone.YSt_40_s.js +0 -1
  404. package/dist/docs/assets/chunks/framework.dypDpWZ3.js +0 -19
  405. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.C4CLm481.js +0 -1
  406. package/dist/docs/assets/deployment.md.Dm4Qo3hp.js +0 -51
  407. package/dist/docs/assets/deployment.md.Dm4Qo3hp.lean.js +0 -1
  408. package/dist/docs/assets/evals.md.BLDRt5LH.js +0 -211
  409. package/dist/docs/assets/evals.md.BLDRt5LH.lean.js +0 -1
  410. package/dist/docs/assets/guides_agent-to-agent.md.BI0xclmy.js +0 -14
  411. package/dist/docs/assets/guides_agent-to-agent.md.BI0xclmy.lean.js +0 -1
  412. package/dist/docs/assets/guides_bitbucket.md.CTpCl__f.js +0 -10
  413. package/dist/docs/assets/guides_bitbucket.md.CTpCl__f.lean.js +0 -1
  414. package/dist/docs/assets/guides_cloud-agents.md.lSE_l7lH.js +0 -9
  415. package/dist/docs/assets/guides_cloud-agents.md.lSE_l7lH.lean.js +0 -1
  416. package/dist/docs/assets/guides_convert-automation.md.Ck6Cr68A.js +0 -12
  417. package/dist/docs/assets/guides_convert-automation.md.Ck6Cr68A.lean.js +0 -1
  418. package/dist/docs/assets/guides_github.md.D6ER29dG.js +0 -64
  419. package/dist/docs/assets/guides_github.md.D6ER29dG.lean.js +0 -1
  420. package/dist/docs/assets/guides_gitlab.md.P-TjBnS5.js +0 -14
  421. package/dist/docs/assets/guides_gitlab.md.P-TjBnS5.lean.js +0 -1
  422. package/dist/docs/assets/guides_grokbot-agents.md.WBZIOvkz.js +0 -9
  423. package/dist/docs/assets/guides_grokbot-agents.md.WBZIOvkz.lean.js +0 -1
  424. package/dist/docs/assets/guides_improve.md.BKaDuKKK.js +0 -14
  425. package/dist/docs/assets/guides_improve.md.BKaDuKKK.lean.js +0 -1
  426. package/dist/docs/assets/guides_mcp-oauth.md.DMNMpXtO.js +0 -28
  427. package/dist/docs/assets/guides_mcp-oauth.md.DMNMpXtO.lean.js +0 -1
  428. package/dist/docs/assets/guides_opentelemetry.md._CRfDyzH.js +0 -26
  429. package/dist/docs/assets/guides_opentelemetry.md._CRfDyzH.lean.js +0 -1
  430. package/dist/docs/assets/guides_slack.md.DdT8rmsj.js +0 -46
  431. package/dist/docs/assets/guides_slack.md.DdT8rmsj.lean.js +0 -1
  432. package/dist/docs/assets/guides_webhooks.md.aQW10HRe.js +0 -225
  433. package/dist/docs/assets/guides_webhooks.md.aQW10HRe.lean.js +0 -1
  434. package/dist/docs/assets/hillclimbing.md.Dq4kkVIL.js +0 -1
  435. package/dist/docs/assets/hillclimbing.md.Dq4kkVIL.lean.js +0 -1
  436. package/dist/docs/assets/reference_extensions.md.wlFD3cUR.js +0 -62
  437. package/dist/docs/assets/reference_extensions.md.wlFD3cUR.lean.js +0 -1
  438. package/dist/docs/assets/troubleshooting.md.BcgNoYtJ.js +0 -1
  439. package/dist/docs/assets/troubleshooting.md.BcgNoYtJ.lean.js +0 -1
  440. package/dist/playground/assets/index-BLlKgZtI.css +0 -1
  441. package/dist/playground/assets/index-CDS5p9sR.js +0 -67
@@ -1,174 +1,164 @@
1
1
  ---
2
2
  title: "Host MCP OAuth"
3
- description: "Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."
3
+ description: "Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."
4
4
  ---
5
5
 
6
- # Host MCP OAuth
6
+ # Connect a private MCP server with OAuth
7
7
 
8
- Use host MCP OAuth when your agent talks to a remote MCP server that
9
- speaks OAuth, and you want credentials on the serve host (or the hosted
10
- engine) instead of a Cursor account connector. Local login writes tokens
11
- next to your Cursor credentials. `--store` copies those tokens onto the
12
- deployment as secrets so prod can reconnect after a redeploy. Hosted
13
- Connect lets the current process retry.
8
+ Host MCP OAuth lets an Agent SDK process authorize a remote MCP server
9
+ without putting tokens in the agent's source or workspace. Use it when
10
+ the server speaks OAuth and its credentials should belong to the serve
11
+ host instead of a person's Cursor account.
14
12
 
15
- The companion skill is
16
- [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
13
+ ## Use a private MCP tool locally
17
14
 
18
- ## What can host MCP OAuth do?
15
+ Declare the remote server, authorize it once in the browser, and start
16
+ the agent. The next local turn can call the server's named tools with
17
+ the credentials stored on that host.
19
18
 
20
- - Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
21
- flow (`agent-sdk mcp oauth <connection>`)
22
- - Keep tokens in `mcp-auth.json` under the CLI config directory, bound
23
- to that connection's resource URL
24
- - Upsert deployment secrets with `--store` so the next deploy seeds the
25
- same tokens from env. Hosted Connect lets the current process retry.
26
- - Use `advertiseTools: true` when local turns should call the server by
27
- name. Host tools can still call it through `ctx.host.mcp`.
19
+ ```ts
20
+ // agent/mcp-connections/inventory.ts
21
+ import { defineConnection } from "@cursor/july/connections";
28
22
 
29
- Prefer a Cursor account MCP connection when the connector already lives
30
- in the signed-in account dashboard:
23
+ export default defineConnection({
24
+ url: "https://mcp.example.com/inventory",
25
+ oauth: true,
26
+ advertiseTools: true,
27
+ });
28
+ ```
31
29
 
32
- ```ts
33
- defineConnection({ cursorAccount: true }) // every connected connector
34
- // or servers: "*" / servers: ["Linear"]
30
+ ```bash
31
+ agent-sdk mcp oauth inventory
32
+ agent-sdk run --dir . \
33
+ --message "Which east-coast warehouse has SKU-142 in stock?"
35
34
  ```
36
35
 
37
- Use host OAuth when the server is yours (or private to your network)
38
- and the host must hold tokens.
36
+ The filename is the connection name used by the CLI and
37
+ `ctx.host.mcp`. Changing the server URL invalidates its saved
38
+ authorization, so run `mcp oauth` again after moving the endpoint.
39
39
 
40
- ## How do I declare a host-OAuth connection?
40
+ ## Connect on first use
41
41
 
42
- Add one file under `agent/mcp-connections/` (model + host) or
43
- `agent/host-connections/` (host + `mcp oauth` only). The filename is the
44
- connection name you pass to the CLI and to `host.mcp`.
42
+ You can also let the first unauthenticated call ask for authorization.
43
+ The turn parks and the playground shows **Connect**. Finish the browser
44
+ flow, return to the playground, and confirm **Connected**; the same call
45
+ retries and the turn continues without restarting the agent.
46
+
47
+ ```bash
48
+ agent-sdk serve --dir . --dev
49
+ ```
50
+
51
+ Connect authorizes the process that is running now. It does not seed
52
+ credentials for a future hosted replacement; use `--store` for that
53
+ separate outcome.
54
+
55
+ ## Keep privileged tools behind a wrapper
56
+
57
+ Put a connection under `agent/host-connections/` when the model should
58
+ not receive the MCP server's tools directly. A server tool can expose
59
+ one constrained operation while `ctx.host.mcp` keeps the broader server
60
+ on the host.
45
61
 
46
62
  ```ts
47
- // agent/mcp-connections/inventory.ts
63
+ // agent/host-connections/inventory.ts
48
64
  import { defineConnection } from "@cursor/july/connections";
49
65
 
50
66
  export default defineConnection({
51
67
  url: "https://mcp.example.com/inventory",
52
68
  oauth: true,
53
- description: "Inventory MCP.",
69
+ tools: ["lookup_stock"],
70
+ });
71
+ ```
72
+
73
+ ```ts
74
+ // agent/tools/get_stock.ts
75
+ import { defineTool } from "@cursor/july/tools";
76
+ import { z } from "zod";
77
+
78
+ export default defineTool({
79
+ description: "Read stock for one approved region.",
80
+ inputSchema: z.object({
81
+ sku: z.string(),
82
+ region: z.enum(["us-east", "us-west"]),
83
+ }),
84
+ async execute(input, ctx) {
85
+ const result = await ctx.host.mcp.callTool(
86
+ "inventory",
87
+ "lookup_stock",
88
+ input
89
+ );
90
+ return {
91
+ ok: result.isError !== true,
92
+ stock: result.structuredContent ?? null,
93
+ };
94
+ },
54
95
  });
55
96
  ```
56
97
 
57
- Rules of the road:
98
+ The model sees `get_stock`, not the unrestricted inventory server.
99
+ Use this shape when code should own an allowlist, approval, or other
100
+ side-effect gate.
58
101
 
59
- - `oauth: true` is required for `agent-sdk mcp oauth`
60
- - A file under `mcp-connections/` is visible to the model and to `ctx.host.mcp`. A file under `host-connections/` stays on the host.
61
- - Declare expected secret names on the agent when you plan to `--store`:
102
+ ## Keep OAuth across hosted replacements
103
+
104
+ Declare the server's egress domain and the OAuth secret names, authorize
105
+ from a signed-in machine, then store the credentials and redeploy. The
106
+ next hosted process can reconnect without opening a browser.
62
107
 
63
108
  ```ts
64
109
  // agent/agent.ts
65
110
  export default defineAgent({
66
- // …
67
111
  hosting: {
112
+ egressDomains: ["mcp.example.com"],
68
113
  secretNames: [
69
114
  "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
70
115
  "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
71
116
  "MCP_OAUTH_INVENTORY_CLIENT_ID",
72
117
  ],
73
- // Hosted engines need an explicit allowlist for non-bootstrap hosts.
74
- egressDomains: ["mcp.example.com"],
75
118
  },
76
119
  });
77
120
  ```
78
121
 
79
- Secret names follow `MCP_OAUTH_<CONNECTION>_*` where `<CONNECTION>` is
80
- the connection filename uppercased with non-alphanumerics turned into
81
- underscores (`inventory` → `MCP_OAUTH_INVENTORY_…`).
82
-
83
- ## How do I authorize locally?
84
-
85
- From the agent project (Node 22.13+, not Bun):
86
-
87
- ```bash
88
- agent-sdk mcp oauth inventory
89
- ```
90
-
91
- What happens:
92
-
93
- 1. The Agent SDK loads the connection file and checks `oauth: true`
94
- 2. It opens the authorization URL in your browser
95
- 3. The callback lands on `http://localhost:8787/callback`
96
- 4. Tokens land in `mcp-auth.json` under the CLI config directory
97
- (override with `AGENT_SERVE_CONFIG_DIR`)
98
-
99
- If you're already authorized, the command prints that and exits. Re-run
100
- it after rotating tokens on the MCP server, or after you change the
101
- connection URL (tokens are bound to the resource URL).
102
-
103
- ## How do I store credentials on a hosted deployment?
104
-
105
- Authorize once. Then get the tokens onto the deployment.
106
-
107
- On a hosted engine, finishing Connect lets the current process retry.
108
- Self-hosted serve writes tokens locally only.
109
-
110
- `--store` from a signed-in laptop is the reliable way to put
111
- `MCP_OAUTH_*` on the next deploy. If `agent-sdk secrets list` is
112
- empty, run `--store` and redeploy.
113
-
114
- From a laptop, push secrets with the CLI:
115
-
116
122
  ```bash
117
123
  agent-sdk mcp oauth inventory --store
118
- # optional:
119
- # --slug my-agent
120
- # --team <cursor-team-id>
124
+ agent-sdk secrets list my-agent
125
+ agent-sdk deploy
121
126
  ```
122
127
 
123
- `--store` upserts:
124
-
125
- | Secret | Source |
126
- | --- | --- |
127
- | `MCP_OAUTH_<NAME>_ACCESS_TOKEN` | access token (required) |
128
- | `MCP_OAUTH_<NAME>_REFRESH_TOKEN` | refresh token when the server returns one |
129
- | `MCP_OAUTH_<NAME>_CLIENT_ID` | dynamic client id when registration returned one |
130
-
131
- You must be signed in (`agent-sdk login`) with permission to set secrets
132
- on that slug. Secrets apply on the **next** deploy. Run
133
- `agent-sdk deploy` after `--store`. A fresh pod sees `MCP_OAUTH_*`
134
- only after that deploy.
128
+ `--store` writes deployment secrets; it does not restart the current
129
+ engine. Follow the CLI or dashboard prompt to redeploy, then exercise
130
+ the hosted agent.
135
131
 
136
- On the engine, when `mcp-auth.json` is empty, serve seeds the OAuth
137
- provider from those env vars so host MCP calls work without a browser
138
- on the pod.
132
+ These credentials belong to the deployment, not to the person who
133
+ clicked Connect. Anyone able to use that agent can reach the MCP
134
+ capabilities you expose, so keep privileged servers host-only or narrow
135
+ their tool list.
139
136
 
140
- These secrets are deployment-wide. Anyone who can list or set secrets
141
- on that slug, and the hosted engine's runtime env, can use them. That
142
- is the same blast radius as `--store`. They are not scoped to the
143
- caller who clicked Connect. `cursorAccount: true` tokens stay on the
144
- Cursor backend for the deployment service account and do not use
145
- `MCP_OAUTH_*`.
137
+ ## Choose where credentials live
146
138
 
147
- ## How do host tools call the server?
139
+ Use the credential shape that matches who should own access:
148
140
 
149
- ```ts
150
- const result = await ctx.host.mcp.callTool(
151
- "inventory",
152
- "list_warehouses",
153
- { region: "us-east" }
154
- );
155
- ```
141
+ - Choose `cursorAccount: true` for connectors already authorized under
142
+ MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.
156
143
 
157
- The model can call the same server. Use a host tool when the write needs
158
- an allowlist or other deterministic gate.
144
+ - Choose `url` with `oauth: true` when the serve host or hosted
145
+ deployment should hold OAuth credentials.
159
146
 
160
- ## What if authorization fails?
147
+ - Choose `url` with static `headers` when the server uses an API key or
148
+ bearer token instead of OAuth.
161
149
 
162
- | What you see | What to do |
163
- | --- | --- |
164
- | `must be defineConnection({ url, oauth: true })` | Add `oauth: true` on that connection, or pick the right connection name |
165
- | Callback never completes | Keep port `8787` free; finish the browser login on this machine |
166
- | Hosted calls unauthorized after Connect or `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
167
- | Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
150
+ Host OAuth and per-session `auth` are different identity models and
151
+ cannot be combined on one connection. Use per-session auth when each
152
+ caller needs a different downstream identity.
168
153
 
169
- ## What's next
154
+ ## Related
170
155
 
171
- - [MCP connections](../reference/connections.md): transports, account MCP
172
- - [CLI](../reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
173
- - [Deployment](../deployment.md): secrets, egress, and hosted engines
174
- - [Fix common agent problems](../troubleshooting.md): more symptom → fix tables
156
+ - [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md): the
157
+ companion setup procedure for coding agents
158
+ - [MCP connections](../reference/connections.md): transports, account
159
+ connectors, per-session auth, and tool filtering
160
+ - [CLI reference](../reference/cli.md#mcp-oauth): OAuth command flags
161
+ and browser callback behavior
162
+ - [Deployment](../deployment.md): hosted secrets and egress
163
+ - [Troubleshooting](../troubleshooting.md): authorization symptoms and
164
+ remedies
@@ -1,224 +1,155 @@
1
1
  ---
2
2
  title: "OpenTelemetry"
3
- description: "Push session, turn, and tool traces from the serve process to an OTLP collector you run."
3
+ description: "Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."
4
4
  ---
5
5
 
6
- # OpenTelemetry
6
+ # Observe an agent with OpenTelemetry
7
7
 
8
- Agent SDK can push traces, metrics, and logs from the serve process to
9
- an OTLP collector you run. Point the process at the collector with
10
- standard `OTEL_EXPORTER_OTLP_*` environment variables, or pass the
11
- same options to `serve({ otel })`. Traces cover the inbound request,
12
- each turn, and every tool call.
8
+ OpenTelemetry connects an agent turn to the observability system your
9
+ team already uses. Once you configure an OTLP collector, each request,
10
+ model turn, tool call, and subagent appears alongside token, tool, and
11
+ cost metrics from the serve process.
13
12
 
14
- Export is opt-in. Nothing leaves the process until you set an endpoint.
13
+ Export is opt-in. Nothing leaves the process until you configure a
14
+ destination.
15
15
 
16
- ## What does Agent SDK export?
16
+ ## Connect an OTLP collector
17
17
 
18
- | Signal | Default | What you get |
19
- | --- | --- | --- |
20
- | Traces | on | `agent_sdk.http` (per request) and `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
21
- | Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` session and turn counts |
22
- | Logs | off | Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in |
23
-
24
- Turn off a signal with `traces: false`, `metrics: false`, or `logs: false`
25
- on `serve({ otel })`. Logs also turn on when you set `OTEL_LOGS_EXPORTER` to
26
- anything other than `none`, or when you set the content flags below.
27
-
28
- ## How do I turn OpenTelemetry export on?
29
-
30
- Set a collector URL in the serve process environment:
18
+ Set the collector endpoint, start the agent, and send it a message. You
19
+ should see an `agent_sdk.http` request span and an `agent_sdk.turn`
20
+ trace, with any tool or subagent work nested under the turn.
31
21
 
32
22
  ```bash
33
23
  export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
34
- export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer "
35
- ```
24
+ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $OTEL_TOKEN"
25
+ export OTEL_SERVICE_NAME=incident-agent
36
26
 
37
- The default wire format is OTLP/HTTP protobuf. That matches
38
- [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export).
39
- Set `OTEL_EXPORTER_OTLP_PROTOCOL=http/json` when your collector only
40
- accepts JSON. The runtime accepts `http/protobuf` and `http/json`.
41
- `grpc` falls back to protobuf and logs a warning.
42
-
43
- `OTEL_EXPORTER_OTLP_ENDPOINT` is the base URL. The runtime appends
44
- `/v1/traces`, `/v1/metrics`, and `/v1/logs`. If you pass a signal path,
45
- it is stripped back to the base first.
46
-
47
- To send each signal to a different collector, omit the base URL and set
48
- the per-signal vars:
49
-
50
- ```bash
51
- export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://traces.example.com/v1/traces
52
- export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metrics.example.com/v1/metrics
53
- export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.example.com/v1/logs
27
+ agent-sdk serve --dir . --dev
54
28
  ```
55
29
 
56
- Optional:
57
-
58
- | Variable | Effect |
59
- | --- | --- |
60
- | `OTEL_SERVICE_NAME` | Resource `service.name`. Default `cursor` |
61
- | `OTEL_LOG_USER_PROMPTS=1` | Include user prompt text on logs and span events |
62
- | `OTEL_LOG_TOOL_CONTENT=1` | Include tool payloads and failure text (truncated) |
63
-
64
- `serve(dir, { otel: false })` turns export off even when env is set.
65
-
66
- You can pass the same options object to `serve(dir, { otel })`.
67
- Precedence is `serve({ otel })` over env.
30
+ The default protocol is OTLP/HTTP protobuf. If you already call
31
+ `serve()` from TypeScript, you can configure the same destination in
32
+ code:
68
33
 
69
34
  ```ts
70
35
  await serve(dir, {
71
36
  otel: {
72
- serviceName: "cursor",
37
+ serviceName: "incident-agent",
73
38
  exporters: [
74
39
  {
75
40
  url: "https://otel.example.com",
76
- protocol: "http/protobuf",
77
- headers: { Authorization: "Bearer …" },
41
+ headers: {
42
+ Authorization: `Bearer ${process.env.OTEL_TOKEN ?? ""}`,
43
+ },
78
44
  },
79
45
  ],
80
46
  },
81
47
  });
82
48
  ```
83
49
 
84
- Multiple `exporters` fan out to every destination. Restrict one
85
- destination with `signals: ["traces"]`.
50
+ Use environment variables when you start the agent with
51
+ `agent-sdk serve`. Use `serve({ otel })` when your TypeScript
52
+ application starts the server itself.
86
53
 
87
- `defineOtel` / `agent/otel.ts` (`@cursor/july/internal/otel`) is
88
- factory-only. Discovery still loads that file for Cursor factory
89
- agents. It is not a public Agent SDK export.
54
+ ## Follow one conversation
90
55
 
91
- The companion skill is [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md).
56
+ Copy the complete session ID from the playground or session API, then
57
+ filter your observability system on either `agent_sdk.session_id` or
58
+ `cursor.conversation.id`. Every turn in that conversation carries the
59
+ same value, including follow-ups and tool work.
92
60
 
93
- ## What spans does a session produce?
61
+ The trace shape stays small:
94
62
 
95
63
  ```text
96
- agent_sdk.http inbound channel request (W3C traceparent)
97
- agent_sdk.turn one root per turn (`agent_sdk.session_id` = session id)
98
- ├─ agent_sdk.tool
99
- └─ agent_sdk.subagent
100
- └─ agent_sdk.tool
101
- ```
102
-
103
- Conversational sessions stay on `session.waiting` and can take more
104
- turns, so there is no `agent_sdk.session` span — it would never end
105
- and OTel only exports ended spans. Each turn is its own root. Inbound
106
- HTTP is a separate SERVER span (it extracts W3C `traceparent`) and
107
- does not parent the turn, so the turn tree can export when the turn
108
- ends. Hosted flush ends that SERVER span before the one-shot export so
109
- `agent_sdk.http` is in the same batch.
110
-
111
- Turns that resume after restore, or a direct `callTool` with no
112
- `turn.started` in this process, open a synthetic turn span so tool
113
- calls still nest.
64
+ request: agent_sdk.http
114
65
 
115
- ## Which attributes land on the wire?
116
-
117
- Every signal carries these resource attributes:
118
-
119
- - `service.name` (`cursor` unless you override it)
120
- - `cursor.entrypoint=sdk_ts`
121
- - `cursor.surface=unspecified`
122
- - `agent_sdk.framework=@cursor/july`
123
-
124
- Span attributes (not process resource attributes — one serve process
125
- handles many sessions):
126
-
127
- - `agent_sdk.session_id` / `cursor.conversation.id`: the session id.
128
- Search all turns for one conversation with `@agent_sdk.session_id`.
129
-
130
- Shared names (same keys as enterprise export):
131
-
132
- - `cursor.conversation.id`: the session id
133
- - `cursor.model.name`
134
- - `cursor.token.usage` with `cursor.token.type` of `input`, `output`,
135
- `cache_read`, `cache_creation`, or `reasoning`
136
- - `cursor.tool.calls` with `cursor.tool.name`, `cursor.tool.kind`, and
137
- `cursor.tool.status`
138
- - `cursor.cost.usage` (USD)
139
-
140
- Agent SDK only (`agent_sdk.*`): session id, agent name, turn id, channel,
141
- call id, subagent name, session mode, and HTTP duration
142
- (`agent_sdk.http.duration`).
66
+ turn: agent_sdk.turn
67
+ |- agent_sdk.tool
68
+ `- agent_sdk.subagent
69
+ `- agent_sdk.tool
70
+ ```
143
71
 
144
- ## How do I emit my own metrics?
72
+ A conversation can produce several turn traces, so use the session ID
73
+ as the join key instead of expecting one long-lived session span.
145
74
 
146
- `ctx.host.otel` is always present on tools, hooks, and channel
147
- handlers. Counters and histograms no-op when no meter is running.
148
- `setAttributes` still tags open turn/tool spans when a collector is
149
- attached.
75
+ ## Add domain telemetry
150
76
 
151
- Prefix metric names with your team or agent. First-party names
152
- (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`,
153
- `agent_sdk.session.count`, `agent_sdk.turn.count`,
154
- `agent_sdk.subagent.count`, `agent_sdk.http.duration`) and join keys
155
- (`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
156
- `agent_sdk.turn_id`, `agent_sdk.framework`) are reserved. Custom spans
157
- are not on this
158
- surface.
77
+ Use `ctx.host.otel` when your dashboard should answer questions the
78
+ built-in telemetry cannot, such as which incident a turn handled or how
79
+ long approval took. Attributes appear on the active turn and tool
80
+ spans, while counters and histograms give you metrics to graph and
81
+ alert on.
159
82
 
160
83
  ```ts
161
84
  ctx.host.otel.setAttributes({
162
- "abc.ticket_id": "INC-123",
163
- "abc.queue": "p1",
85
+ "support.ticket_id": "INC-123",
86
+ "support.queue": "p1",
164
87
  });
165
- ctx.host.otel.increment("abc.ticket.resolved");
166
- ctx.host.otel.record("abc.approval.duration_ms", 1420, {
88
+
89
+ ctx.host.otel.increment("support.ticket.resolved", {
90
+ outcome: "fixed",
91
+ });
92
+
93
+ ctx.host.otel.record("support.approval.duration_ms", 1420, {
167
94
  outcome: "approved",
168
95
  });
169
96
  ```
170
97
 
171
- A session-bound host (tools and hooks) adds `cursor.conversation.id`
172
- and `agent_sdk.agent` for you. Tags merge: later `setAttributes` calls
173
- paint open spans and later first-party metrics.
174
-
175
- ## What stays off the OpenTelemetry wire?
98
+ This API is available in tools, hooks, and channel handlers. A
99
+ session-bound context adds `cursor.conversation.id` and
100
+ `agent_sdk.agent` automatically, so custom measurements join the
101
+ first-party telemetry without extra plumbing.
176
102
 
177
- User prompts, tool arguments, tool results, and failure messages are
178
- omitted by default. Failure spans still record an error status with a
179
- generic message (`turn failed` / `session failed`).
103
+ Prefix custom names with your team or agent. First-party metric names
104
+ and join keys are reserved, and this surface does not create custom
105
+ spans.
180
106
 
181
- Opt in with `OTEL_LOG_USER_PROMPTS=1` and `OTEL_LOG_TOOL_CONTENT=1`, or
182
- the matching `logs: { userPrompts, toolContent }` fields on
183
- `serve({ otel })`. Opted-in strings truncate at 2,048 characters.
107
+ ## Choose signals
184
108
 
185
- Deployment URLs from `agent.bound` stay off spans unless
186
- `toolContent` is on.
109
+ Once export has a destination, traces and metrics are on by default;
110
+ logs remain off until you opt in.
187
111
 
188
- ## How does Agent SDK export relate to Cursor enterprise export?
112
+ | Signal | What appears |
113
+ | --- | --- |
114
+ | Traces | HTTP requests, turns, tools, and subagents |
115
+ | Metrics | Token usage, tool calls, cost, and Agent SDK session or turn counts |
116
+ | Logs | Session events, after you enable log export |
189
117
 
190
- [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export)
191
- is the team-admin path. Cursor servers send org-wide metrics and logs
192
- to a collector you configure in Team Settings.
118
+ The first metrics to look for are `cursor.token.usage`,
119
+ `cursor.tool.calls`, and `cursor.cost.usage`. Configure
120
+ `traces: false`, `metrics: false`, or `logs: true` under
121
+ `serve({ otel })` when you need a different signal mix.
193
122
 
194
- Agent SDK export is the process-local path. The serve process sends
195
- per-run traces, and optional metrics and logs, to a collector you
196
- point it at.
123
+ ## Control what leaves the process
197
124
 
198
- Point both at the same collector when you want one view. Group on
199
- `cursor.conversation.id`. Resource defaults (`service.name=cursor`,
200
- `cursor.entrypoint=sdk_ts`) keep the streams next to each other. The
201
- [wire reference](https://cursor.com/docs/enterprise/opentelemetry-export/wire)
202
- lists the shared attribute names.
125
+ User prompts, tool arguments, tool results, and failure text stay off
126
+ the wire by default. You still get trace structure, tool names and
127
+ status, usage metrics, and generic failure status without exporting the
128
+ underlying content.
203
129
 
204
- Evals (`defineEval`) stay the in-product regression check. OpenTelemetry
205
- is the graph in your observability stack.
130
+ Turn on logs first, then opt into prompt or tool content separately:
206
131
 
207
- ## What if another OpenTelemetry SDK is already running?
132
+ ```bash
133
+ export OTEL_LOGS_EXPORTER=otlp
134
+ export OTEL_LOG_USER_PROMPTS=1
135
+ export OTEL_LOG_TOOL_CONTENT=1
136
+ ```
208
137
 
209
- OTel providers are process-global. If Cursor CLI, an extension host, or
210
- another library already registered a TracerProvider, MeterProvider, or
211
- LoggerProvider, Agent SDK reuses it. Run `serve` as its own process
212
- when the Agent SDK exporters should own the destination.
138
+ `OTEL_LOG_USER_PROMPTS` exports user text. `OTEL_LOG_TOOL_CONTENT`
139
+ exports tool inputs, outputs, and failure details. Enable either only
140
+ when the collector's access and retention policies are appropriate for
141
+ that data.
213
142
 
214
- Two mounts with different authored OTel configs fail at serve start.
215
- Configure once through `serve({ otel })` or env.
143
+ The same controls are available as
144
+ `logs: { userPrompts, toolContent }` under `serve({ otel })`.
216
145
 
217
- ## What's next
146
+ ## Related
218
147
 
219
148
  - [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md): compact
220
- env / `serve({ otel })` reference for coding agents
221
- - [Hooks](../reference/hooks.md): observe the same session event stream
222
- in-process
223
- - [Deployment](../deployment.md): env, secrets, and self-hosting
224
- - [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export)
149
+ configuration and custom-metric reference for coding agents
150
+ - [Hooks](../reference/hooks.md): emit domain telemetry from session
151
+ events
152
+ - [Deployment](../deployment.md): set collector endpoints and secrets
153
+ on hosted or self-hosted agents
154
+ - [Cursor enterprise OpenTelemetry Export](https://cursor.com/docs/enterprise/opentelemetry-export):
155
+ send organization-wide Cursor telemetry to the same collector