@cursor/july 0.1.1 → 0.1.3

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 (298) hide show
  1. package/AGENTS.md +40 -7
  2. package/README.md +33 -24
  3. package/dist/bin/agent-serve.d.ts +3 -1
  4. package/dist/bin/agent-serve.d.ts.map +1 -1
  5. package/dist/bin/agent-serve.js +466 -140
  6. package/dist/channels/github/api.d.ts.map +1 -1
  7. package/dist/channels/github/api.js +31 -14
  8. package/dist/channels/github/cursor-account.d.ts +43 -0
  9. package/dist/channels/github/cursor-account.d.ts.map +1 -0
  10. package/dist/channels/github/cursor-account.js +95 -0
  11. package/dist/channels/github/github-channel.d.ts.map +1 -1
  12. package/dist/channels/github/github-channel.js +46 -9
  13. package/dist/channels/github/index.d.ts +2 -2
  14. package/dist/channels/github/index.js +2 -2
  15. package/dist/channels/github/types.d.ts +17 -0
  16. package/dist/channels/github/types.d.ts.map +1 -1
  17. package/dist/channels/slack/slack-channel.d.ts +8 -2
  18. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  19. package/dist/channels/slack/slack-channel.js +8 -0
  20. package/dist/channels/slack/types.d.ts +24 -3
  21. package/dist/channels/slack/types.d.ts.map +1 -1
  22. package/dist/channels/slack/types.js +15 -1
  23. package/dist/docs/404.html +2 -2
  24. package/dist/docs/ab.html +8 -8
  25. package/dist/docs/assets/{ab.md.COdXkces.js → ab.md.BMCZ6Hd7.js} +3 -3
  26. package/dist/docs/assets/{ab.md.COdXkces.lean.js → ab.md.BMCZ6Hd7.lean.js} +1 -1
  27. package/dist/docs/assets/{app.DqfFEmJd.js → app.BR0RbIdx.js} +1 -1
  28. package/dist/docs/assets/chunks/@localSearchIndexroot.DtIOQzGj.js +1 -0
  29. package/dist/docs/assets/chunks/{VPLocalSearchBox.BaLEdS15.js → VPLocalSearchBox.qjsVTneI.js} +1 -1
  30. package/dist/docs/assets/chunks/{theme.CZRvu_0q.js → theme.2Kg8jIp_.js} +2 -2
  31. package/dist/docs/assets/{deployment.md.Dx1TYNk5.js → deployment.md.DTKwE15Z.js} +3 -3
  32. package/dist/docs/assets/{deployment.md.Dx1TYNk5.lean.js → deployment.md.DTKwE15Z.lean.js} +1 -1
  33. package/dist/docs/assets/{evals.md.DPZ_MAnI.js → evals.md.DAgEc_hL.js} +3 -3
  34. package/dist/docs/assets/{guides_agent-to-agent.md.CrtrsySy.js → guides_agent-to-agent.md.Bpzgq2Pq.js} +1 -1
  35. package/dist/docs/assets/{guides_cloud-runtime.md.CYlNMTNp.js → guides_cloud-runtime.md.gVzabdQL.js} +1 -1
  36. package/dist/docs/assets/{guides_github.md.DwbKhCeS.js → guides_github.md.DOOCpqsW.js} +11 -4
  37. package/dist/docs/assets/{guides_github.md.DwbKhCeS.lean.js → guides_github.md.DOOCpqsW.lean.js} +1 -1
  38. package/dist/docs/assets/{guides_human-in-the-loop.md.Dvuctx7s.js → guides_human-in-the-loop.md.DlUqsp1S.js} +2 -2
  39. package/dist/docs/assets/{guides_slack.md.bv41fHfW.js → guides_slack.md.CCwqHvSV.js} +4 -4
  40. package/dist/docs/assets/{guides_slack.md.bv41fHfW.lean.js → guides_slack.md.CCwqHvSV.lean.js} +1 -1
  41. package/dist/docs/assets/{guides_webhooks.md.hFTik3lf.js → guides_webhooks.md.B1EswtUu.js} +2 -2
  42. package/dist/docs/assets/index.md.m81y7TY7.js +20 -0
  43. package/dist/docs/assets/{index.md.BPKcj5AI.lean.js → index.md.m81y7TY7.lean.js} +1 -1
  44. package/dist/docs/assets/quickstart.md.BU6Iwi_9.js +204 -0
  45. package/dist/docs/assets/quickstart.md.BU6Iwi_9.lean.js +1 -0
  46. package/dist/docs/assets/{reference_agent-config.md.Bpd7HQwf.js → reference_agent-config.md.DrW2JUM8.js} +4 -4
  47. package/dist/docs/assets/{reference_agent-config.md.Bpd7HQwf.lean.js → reference_agent-config.md.DrW2JUM8.lean.js} +1 -1
  48. package/dist/docs/assets/{reference_channels.md.D7JTR03W.js → reference_channels.md.DdmiKgqf.js} +4 -4
  49. package/dist/docs/assets/{reference_channels.md.D7JTR03W.lean.js → reference_channels.md.DdmiKgqf.lean.js} +1 -1
  50. package/dist/docs/assets/{reference_cli.md.DA730zCu.js → reference_cli.md.Bv6pOxcF.js} +11 -6
  51. package/dist/docs/assets/{reference_cli.md.DA730zCu.lean.js → reference_cli.md.Bv6pOxcF.lean.js} +1 -1
  52. package/dist/docs/assets/{reference_connections.md.C3vNH_DE.js → reference_connections.md.zaEYCLHT.js} +1 -1
  53. package/dist/docs/assets/{reference_hooks.md.BCEc3MyM.js → reference_hooks.md.DyLVfE1O.js} +1 -1
  54. package/dist/docs/assets/{reference_hooks.md.BCEc3MyM.lean.js → reference_hooks.md.DyLVfE1O.lean.js} +1 -1
  55. package/dist/docs/assets/{reference_http-api.md.DBAahtdz.js → reference_http-api.md.Dx_nmDG6.js} +1 -1
  56. package/dist/docs/assets/{reference_instructions.md.BC05LEQ8.js → reference_instructions.md.CgoV-YEb.js} +9 -7
  57. package/dist/docs/assets/{reference_instructions.md.BC05LEQ8.lean.js → reference_instructions.md.CgoV-YEb.lean.js} +1 -1
  58. package/dist/docs/assets/{reference_schedules.md.D7qijxLk.js → reference_schedules.md.w_F2mXB6.js} +2 -2
  59. package/dist/docs/assets/{reference_skills.md.VQnlBT3Q.js → reference_skills.md.B_jHN7JL.js} +3 -3
  60. package/dist/docs/assets/{reference_skills.md.VQnlBT3Q.lean.js → reference_skills.md.B_jHN7JL.lean.js} +1 -1
  61. package/dist/docs/assets/{reference_subagents.md.CIRAVcPK.js → reference_subagents.md.zWAMNfi1.js} +1 -1
  62. package/dist/docs/assets/{reference_tools.md.DF5kwlt0.js → reference_tools.md.CqgJroI0.js} +2 -2
  63. package/dist/docs/assets/scaffolding-agents.md.C3pTrmoE.js +1 -0
  64. package/dist/docs/assets/scaffolding-agents.md.C3pTrmoE.lean.js +1 -0
  65. package/dist/docs/assets/storage.md.CVnInNiN.js +17 -0
  66. package/dist/docs/assets/storage.md.CVnInNiN.lean.js +1 -0
  67. package/dist/docs/building-with-agents.html +4 -4
  68. package/dist/docs/concepts.html +4 -4
  69. package/dist/docs/deployment.html +7 -7
  70. package/dist/docs/evals.html +7 -7
  71. package/dist/docs/guides/agent-to-agent.html +6 -6
  72. package/dist/docs/guides/cloud-runtime.html +5 -5
  73. package/dist/docs/guides/github.html +14 -7
  74. package/dist/docs/guides/human-in-the-loop.html +6 -6
  75. package/dist/docs/guides/slack.html +8 -8
  76. package/dist/docs/guides/webhooks.html +6 -6
  77. package/dist/docs/hashmap.json +1 -1
  78. package/dist/docs/hillclimbing.html +5 -5
  79. package/dist/docs/index.html +7 -7
  80. package/dist/docs/quickstart.html +195 -26
  81. package/dist/docs/reference/agent-config.html +7 -7
  82. package/dist/docs/reference/channels.html +8 -8
  83. package/dist/docs/reference/cli.html +14 -9
  84. package/dist/docs/reference/connections.html +5 -5
  85. package/dist/docs/reference/hooks.html +5 -5
  86. package/dist/docs/reference/http-api.html +6 -6
  87. package/dist/docs/reference/instructions.html +13 -11
  88. package/dist/docs/reference/playground.html +4 -4
  89. package/dist/docs/reference/project-layout.html +4 -4
  90. package/dist/docs/reference/schedules.html +7 -7
  91. package/dist/docs/reference/sessions.html +4 -4
  92. package/dist/docs/reference/skills.html +6 -6
  93. package/dist/docs/reference/subagents.html +6 -6
  94. package/dist/docs/reference/tools.html +7 -7
  95. package/dist/docs/scaffolding-agents.html +5 -5
  96. package/dist/docs/storage.html +41 -0
  97. package/dist/docs/troubleshooting.html +4 -4
  98. package/dist/index.d.ts +2 -0
  99. package/dist/index.d.ts.map +1 -1
  100. package/dist/index.js +1 -0
  101. package/dist/internal/chat-client.d.ts +29 -3
  102. package/dist/internal/chat-client.d.ts.map +1 -1
  103. package/dist/internal/chat-client.js +180 -27
  104. package/dist/internal/cli-ax.d.ts +75 -2
  105. package/dist/internal/cli-ax.d.ts.map +1 -1
  106. package/dist/internal/cli-ax.js +600 -52
  107. package/dist/internal/cli-cursor.d.ts.map +1 -1
  108. package/dist/internal/cli-cursor.js +8 -36
  109. package/dist/internal/cli-deploy.d.ts +108 -0
  110. package/dist/internal/cli-deploy.d.ts.map +1 -0
  111. package/dist/internal/cli-deploy.js +1009 -0
  112. package/dist/internal/cursor/backend-client.d.ts +10 -1
  113. package/dist/internal/cursor/backend-client.d.ts.map +1 -1
  114. package/dist/internal/cursor/backend-client.js +79 -1
  115. package/dist/internal/cursor/credentials.d.ts +9 -0
  116. package/dist/internal/cursor/credentials.d.ts.map +1 -1
  117. package/dist/internal/cursor/credentials.js +12 -0
  118. package/dist/internal/cursor/github-credentials.d.ts +44 -0
  119. package/dist/internal/cursor/github-credentials.d.ts.map +1 -0
  120. package/dist/internal/cursor/github-credentials.js +195 -0
  121. package/dist/internal/deploy-client.d.ts +184 -0
  122. package/dist/internal/deploy-client.d.ts.map +1 -0
  123. package/dist/internal/deploy-client.js +395 -0
  124. package/dist/internal/deploy-source.d.ts +35 -0
  125. package/dist/internal/deploy-source.d.ts.map +1 -0
  126. package/dist/internal/deploy-source.js +118 -0
  127. package/dist/internal/discovery.d.ts +11 -0
  128. package/dist/internal/discovery.d.ts.map +1 -1
  129. package/dist/internal/discovery.js +116 -19
  130. package/dist/internal/distribution.d.ts.map +1 -1
  131. package/dist/internal/distribution.js +1 -0
  132. package/dist/internal/eval-run-store.d.ts +22 -3
  133. package/dist/internal/eval-run-store.d.ts.map +1 -1
  134. package/dist/internal/eval-run-store.js +39 -20
  135. package/dist/internal/eval-runner.d.ts +2 -0
  136. package/dist/internal/eval-runner.d.ts.map +1 -1
  137. package/dist/internal/eval-runner.js +2 -0
  138. package/dist/internal/event-mapper.d.ts +54 -1
  139. package/dist/internal/event-mapper.d.ts.map +1 -1
  140. package/dist/internal/event-mapper.js +151 -41
  141. package/dist/internal/handleAgentServeTrigger.d.ts.map +1 -1
  142. package/dist/internal/handleAgentServeTrigger.js +10 -12
  143. package/dist/internal/host-platforms.d.ts +7 -2
  144. package/dist/internal/host-platforms.d.ts.map +1 -1
  145. package/dist/internal/host-platforms.js +15 -10
  146. package/dist/internal/hosting.d.ts +37 -0
  147. package/dist/internal/hosting.d.ts.map +1 -0
  148. package/dist/internal/hosting.js +67 -0
  149. package/dist/internal/init-project.d.ts +88 -1
  150. package/dist/internal/init-project.d.ts.map +1 -1
  151. package/dist/internal/init-project.js +221 -31
  152. package/dist/internal/install-cursor-skills.d.ts +64 -0
  153. package/dist/internal/install-cursor-skills.d.ts.map +1 -0
  154. package/dist/internal/install-cursor-skills.js +274 -0
  155. package/dist/internal/logs-client.d.ts +60 -0
  156. package/dist/internal/logs-client.d.ts.map +1 -0
  157. package/dist/internal/logs-client.js +311 -0
  158. package/dist/internal/open-browser.d.ts +5 -0
  159. package/dist/internal/open-browser.d.ts.map +1 -0
  160. package/dist/internal/open-browser.js +34 -0
  161. package/dist/internal/playground/toolchain.d.ts.map +1 -1
  162. package/dist/internal/playground/toolchain.js +16 -11
  163. package/dist/internal/playground-proxy.d.ts +69 -0
  164. package/dist/internal/playground-proxy.d.ts.map +1 -0
  165. package/dist/internal/playground-proxy.js +468 -0
  166. package/dist/internal/prompt-context.d.ts +35 -0
  167. package/dist/internal/prompt-context.d.ts.map +1 -0
  168. package/dist/internal/prompt-context.js +71 -0
  169. package/dist/internal/reminder-runner.d.ts +7 -0
  170. package/dist/internal/reminder-runner.d.ts.map +1 -1
  171. package/dist/internal/reminder-runner.js +50 -6
  172. package/dist/internal/reminder-store.d.ts +2 -0
  173. package/dist/internal/reminder-store.d.ts.map +1 -1
  174. package/dist/internal/reminder-store.js +18 -0
  175. package/dist/internal/request-headers.d.ts +11 -0
  176. package/dist/internal/request-headers.d.ts.map +1 -0
  177. package/dist/internal/request-headers.js +14 -0
  178. package/dist/internal/resolve-prod-target.d.ts +42 -0
  179. package/dist/internal/resolve-prod-target.d.ts.map +1 -0
  180. package/dist/internal/resolve-prod-target.js +111 -0
  181. package/dist/internal/run-client.d.ts +2 -2
  182. package/dist/internal/run-client.d.ts.map +1 -1
  183. package/dist/internal/run-client.js +38 -23
  184. package/dist/internal/server.d.ts.map +1 -1
  185. package/dist/internal/server.js +182 -45
  186. package/dist/internal/session-engine.d.ts +50 -1
  187. package/dist/internal/session-engine.d.ts.map +1 -1
  188. package/dist/internal/session-engine.js +267 -23
  189. package/dist/internal/sessions-client.d.ts +21 -0
  190. package/dist/internal/sessions-client.d.ts.map +1 -0
  191. package/dist/internal/sessions-client.js +168 -0
  192. package/dist/internal/storage-coordinator.d.ts +139 -0
  193. package/dist/internal/storage-coordinator.d.ts.map +1 -0
  194. package/dist/internal/storage-coordinator.js +499 -0
  195. package/dist/internal/stream-progress.d.ts.map +1 -1
  196. package/dist/internal/stream-progress.js +31 -3
  197. package/dist/internal/terminal-style.d.ts +22 -0
  198. package/dist/internal/terminal-style.d.ts.map +1 -0
  199. package/dist/internal/terminal-style.js +49 -0
  200. package/dist/internal/trajectory.d.ts +10 -5
  201. package/dist/internal/trajectory.d.ts.map +1 -1
  202. package/dist/internal/trajectory.js +82 -10
  203. package/dist/internal/workspace.d.ts +11 -0
  204. package/dist/internal/workspace.d.ts.map +1 -1
  205. package/dist/internal/workspace.js +38 -4
  206. package/dist/playground/assets/cursor-icons-outline-BxTT_FVJ.woff2 +0 -0
  207. package/dist/playground/assets/index-D-vo2lV_.css +1 -0
  208. package/dist/playground/assets/index-x60b9q2j.js +312 -0
  209. package/dist/playground/index.html +2 -2
  210. package/dist/storage.d.ts +204 -0
  211. package/dist/storage.d.ts.map +1 -0
  212. package/dist/storage.js +153 -0
  213. package/dist/types.d.ts +70 -4
  214. package/dist/types.d.ts.map +1 -1
  215. package/docs/README.md +3 -2
  216. package/docs/guides/github.md +43 -8
  217. package/docs/guides/slack.md +1 -1
  218. package/docs/quickstart.md +350 -57
  219. package/docs/reference/cli.md +51 -3
  220. package/docs/reference/instructions.md +8 -6
  221. package/docs/scaffolding-agents.md +1 -1
  222. package/docs/storage.md +98 -0
  223. package/package.json +10 -1
  224. package/skills/ab/SKILL.md +8 -8
  225. package/skills/create-agent/SKILL.md +28 -22
  226. package/skills/debug/SKILL.md +11 -11
  227. package/skills/evals/SKILL.md +16 -16
  228. package/skills/framework-map/SKILL.md +6 -6
  229. package/skills/github/SKILL.md +22 -14
  230. package/skills/hillclimb/SKILL.md +10 -10
  231. package/skills/setup-slack/SKILL.md +13 -13
  232. package/src/bin/agent-serve.ts +552 -179
  233. package/src/channels/github/api.ts +42 -23
  234. package/src/channels/github/cursor-account.ts +165 -0
  235. package/src/channels/github/github-channel.ts +66 -6
  236. package/src/channels/github/index.ts +2 -2
  237. package/src/channels/github/types.ts +19 -0
  238. package/src/channels/slack/slack-channel.ts +17 -3
  239. package/src/channels/slack/types.ts +44 -3
  240. package/src/index.ts +13 -0
  241. package/src/internal/chat-client.ts +252 -37
  242. package/src/internal/cli-ax.ts +722 -72
  243. package/src/internal/cli-cursor.ts +14 -42
  244. package/src/internal/cli-deploy.ts +1319 -0
  245. package/src/internal/cursor/backend-client.ts +103 -1
  246. package/src/internal/cursor/credentials.ts +14 -0
  247. package/src/internal/cursor/github-credentials.ts +248 -0
  248. package/src/internal/deploy-client.ts +632 -0
  249. package/src/internal/deploy-source.ts +133 -0
  250. package/src/internal/discovery.ts +141 -17
  251. package/src/internal/distribution.ts +1 -0
  252. package/src/internal/eval-run-store.ts +50 -20
  253. package/src/internal/eval-runner.ts +5 -0
  254. package/src/internal/event-mapper.ts +222 -42
  255. package/src/internal/handleAgentServeTrigger.ts +10 -12
  256. package/src/internal/host-platforms.ts +28 -11
  257. package/src/internal/hosting.ts +77 -0
  258. package/src/internal/init-project.ts +333 -51
  259. package/src/internal/install-cursor-skills.ts +327 -0
  260. package/src/internal/logs-client.ts +442 -0
  261. package/src/internal/open-browser.ts +41 -0
  262. package/src/internal/playground/toolchain.ts +15 -13
  263. package/src/internal/playground-proxy.ts +576 -0
  264. package/src/internal/prompt-context.ts +95 -0
  265. package/src/internal/reminder-runner.ts +50 -6
  266. package/src/internal/reminder-store.ts +21 -0
  267. package/src/internal/request-headers.ts +23 -0
  268. package/src/internal/resolve-prod-target.ts +150 -0
  269. package/src/internal/run-client.ts +39 -36
  270. package/src/internal/server.ts +223 -28
  271. package/src/internal/session-engine.ts +307 -10
  272. package/src/internal/sessions-client.ts +182 -0
  273. package/src/internal/storage-coordinator.ts +615 -0
  274. package/src/internal/stream-progress.ts +36 -2
  275. package/src/internal/terminal-style.ts +74 -0
  276. package/src/internal/trajectory.ts +91 -13
  277. package/src/internal/workspace.ts +42 -4
  278. package/src/storage.ts +325 -0
  279. package/src/types.ts +82 -8
  280. package/dist/docs/assets/chunks/@localSearchIndexroot.CcVk1uKq.js +0 -1
  281. package/dist/docs/assets/index.md.BPKcj5AI.js +0 -20
  282. package/dist/docs/assets/quickstart.md.tVPiGK_L.js +0 -35
  283. package/dist/docs/assets/quickstart.md.tVPiGK_L.lean.js +0 -1
  284. package/dist/docs/assets/scaffolding-agents.md.CyYfWGdc.js +0 -1
  285. package/dist/docs/assets/scaffolding-agents.md.CyYfWGdc.lean.js +0 -1
  286. package/dist/playground/assets/cursor-icons-outline-oY2V_mvK.woff2 +0 -0
  287. package/dist/playground/assets/index-1K-hG-7p.css +0 -1
  288. package/dist/playground/assets/index-FlWjhg3x.js +0 -79
  289. /package/dist/docs/assets/{evals.md.DPZ_MAnI.lean.js → evals.md.DAgEc_hL.lean.js} +0 -0
  290. /package/dist/docs/assets/{guides_agent-to-agent.md.CrtrsySy.lean.js → guides_agent-to-agent.md.Bpzgq2Pq.lean.js} +0 -0
  291. /package/dist/docs/assets/{guides_cloud-runtime.md.CYlNMTNp.lean.js → guides_cloud-runtime.md.gVzabdQL.lean.js} +0 -0
  292. /package/dist/docs/assets/{guides_human-in-the-loop.md.Dvuctx7s.lean.js → guides_human-in-the-loop.md.DlUqsp1S.lean.js} +0 -0
  293. /package/dist/docs/assets/{guides_webhooks.md.hFTik3lf.lean.js → guides_webhooks.md.B1EswtUu.lean.js} +0 -0
  294. /package/dist/docs/assets/{reference_connections.md.C3vNH_DE.lean.js → reference_connections.md.zaEYCLHT.lean.js} +0 -0
  295. /package/dist/docs/assets/{reference_http-api.md.DBAahtdz.lean.js → reference_http-api.md.Dx_nmDG6.lean.js} +0 -0
  296. /package/dist/docs/assets/{reference_schedules.md.D7qijxLk.lean.js → reference_schedules.md.w_F2mXB6.lean.js} +0 -0
  297. /package/dist/docs/assets/{reference_subagents.md.CIRAVcPK.lean.js → reference_subagents.md.zWAMNfi1.lean.js} +0 -0
  298. /package/dist/docs/assets/{reference_tools.md.DF5kwlt0.lean.js → reference_tools.md.CqgJroI0.lean.js} +0 -0
package/dist/playground/index.html CHANGED
@@ -8,8 +8,8 @@
8
8
  />
9
9
  <meta name="viewport" content="width=device-width, initial-scale=1" />
10
10
  <title>agent-serve playground</title>
11
- <script type="module" crossorigin src="./assets/index-FlWjhg3x.js"></script>
12
- <link rel="stylesheet" crossorigin href="./assets/index-1K-hG-7p.css">
11
+ <script type="module" crossorigin src="./assets/index-x60b9q2j.js"></script>
12
+ <link rel="stylesheet" crossorigin href="./assets/index-D-vo2lV_.css">
13
13
  </head>
14
14
  <body>
15
15
  <div id="root"></div>
package/dist/storage.d.ts ADDED
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Durable storage plug-in for agent-serve.
3
+ *
4
+ * Author `agent/storage.ts` with {@link defineStorage} to mirror the
5
+ * framework's durable state into storage you own (a database, S3, a data
6
+ * pipeline, …). Without it, state lives under `--state-root` on local disk
7
+ * only (and eval/A/B history follows the narrower `persistRuns` /
8
+ * `persistSamples` / `persistSnapshots` hooks).
9
+ *
10
+ * The sink is a plain key-value store — four functions, no schema:
11
+ *
12
+ * ```ts
13
+ * import { defineStorage } from "@anysphere/agent-serve/storage";
14
+ *
15
+ * export default defineStorage({
16
+ * put: (key, value) => db.upsert(key, value),
17
+ * get: (key) => db.get(key),
18
+ * delete: (key) => db.delete(key),
19
+ * list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
20
+ * });
21
+ * ```
22
+ *
23
+ * The **framework mints every key** from a stable, versioned scheme (see
24
+ * {@link storageKeys}) and decides **when** to call the sink: session
25
+ * records and event chunks flush when a turn's handlers have settled,
26
+ * reads happen at serve start (bulk restore), on continuation-token misses
27
+ * (lazy restore), and at playground hydration. Authors do not schedule
28
+ * reads or writes — the only timing knobs are {@link StoragePolicy}'s
29
+ * `debounceMs` (event write batching) and `restore` (startup hydration).
30
+ *
31
+ * Because keys are opaque strings to the sink, new kinds of durable state
32
+ * (channel cursors, thread affinity, …) are new key prefixes — existing
33
+ * sinks store them with no code changes.
34
+ *
35
+ * Delivery semantics: writes are **serialized** (one sink call in flight
36
+ * per agent, in order), **bounded** (a sink that falls behind sheds writes
37
+ * rather than growing memory), and **at-most-once** — a throwing `put` is
38
+ * logged and dropped, never retried, and never fails a turn. The local
39
+ * event log under `--state-root` remains the live source of truth; this
40
+ * interface is the durable mirror.
41
+ */
42
+ import type { JsonValue } from "./types.js";
43
+ /** One `{ key, value }` pair returned by {@link StorageConfig.list}. */
44
+ export interface StorageEntry {
45
+ key: string;
46
+ value: JsonValue;
47
+ }
48
+ /** Context passed to every sink call. */
49
+ export interface StorageContext {
50
+ /** Agent name (also baked into every key; see {@link storageKeys}). */
51
+ agentName: string;
52
+ /** Absolute agent project root (directory that contains `agent/`). */
53
+ projectRoot: string;
54
+ /**
55
+ * Why the framework is calling:
56
+ * - `"policy"` — a flush trigger fired (turn end, debounce, change)
57
+ * - `"shutdown"` — the serve process is draining; last chance to write
58
+ * - `"restore"` — serve start or a lazy restore; reads rebuilding state
59
+ */
60
+ reason: "policy" | "shutdown" | "restore";
61
+ }
62
+ export interface StoragePolicy {
63
+ /**
64
+ * Batch event-chunk writes on a quiet-period timer instead of flushing
65
+ * once per turn. The debounce **spans turn boundaries** — a rapid
66
+ * multi-turn exchange becomes one write when the session goes quiet —
67
+ * so it is the right choice for chatty sessions where per-turn writes
68
+ * are too many. Unset (default): one event chunk per turn.
69
+ */
70
+ debounceMs?: number;
71
+ /**
72
+ * Guardrails for the **startup bulk restore**. Whatever `list` returns
73
+ * is filtered to these caps before anything is written to local disk, so
74
+ * a large store cannot blow up `--state-root` or stall serve start.
75
+ * Newest sessions (by `updatedAt`) win within each cap.
76
+ *
77
+ * `"off"` disables the startup restore entirely — sessions then restore
78
+ * one at a time as follow-ups actually arrive (lazy-only; recommended
79
+ * for high-traffic deployments).
80
+ */
81
+ restore?: StorageRestorePolicy | "off";
82
+ }
83
+ /** Caps applied to the startup bulk restore. See {@link StoragePolicy.restore}. */
84
+ export interface StorageRestorePolicy {
85
+ /** Max sessions materialized (default {@link STORAGE_DEFAULT_RESTORE_MAX_SESSIONS}). */
86
+ maxSessions?: number;
87
+ /**
88
+ * Skip sessions whose `updatedAt` is older than this (default
89
+ * {@link STORAGE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
90
+ * reachable lazily on their next follow-up.
91
+ */
92
+ maxAgeMs?: number;
93
+ /**
94
+ * Stop restoring once this many bytes of records + events have been
95
+ * written (default {@link STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
96
+ * Checked before each session is written, so one oversized stream
97
+ * cannot blow past the budget.
98
+ */
99
+ maxTotalBytes?: number;
100
+ }
101
+ export interface StorageConfig {
102
+ /** Optional label surfaced on `GET /v1/info` diagnostics. */
103
+ name?: string;
104
+ /** Timing knobs; see {@link StoragePolicy}. */
105
+ policy?: StoragePolicy;
106
+ /**
107
+ * Store one value under a key (upsert, last-write-wins). Called on the
108
+ * framework's schedule — never concurrently, always in order. Keep it
109
+ * fast or buffer internally: the delivery queue is bounded, so a sink
110
+ * that falls behind sustained traffic sheds writes (logged) instead of
111
+ * growing memory; it never stalls the agent loop.
112
+ */
113
+ put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
114
+ /** Remove a key. Optional — without it, deletions are skipped. */
115
+ delete?(key: string, ctx: StorageContext): void | Promise<void>;
116
+ /**
117
+ * Point lookup. Optional — required for **lazy restore** (resolving a
118
+ * continuation token on a replacement host) and the A/B backfill.
119
+ * Return `undefined`/`null` only for a **definitive** miss: on the lazy
120
+ * restore path a throw propagates and fails the follow-up (retryable) —
121
+ * a store outage must not read as "unknown token", which would fork the
122
+ * conversation onto a new session.
123
+ */
124
+ get?(key: string, ctx: StorageContext): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
125
+ /**
126
+ * All entries under a key prefix, in ascending key order. Optional —
127
+ * required for the **startup bulk restore** (sessions + event streams)
128
+ * and playground eval history.
129
+ */
130
+ list?(prefix: string, ctx: StorageContext): StorageEntry[] | Promise<StorageEntry[]>;
131
+ }
132
+ export type StorageDefinition = StorageConfig & {
133
+ readonly __agentServe: "storage";
134
+ };
135
+ /**
136
+ * Author the project storage sink (`agent/storage.ts`, default
137
+ * export). See the module doc for semantics and an example.
138
+ */
139
+ export declare function defineStorage(config: StorageConfig): StorageDefinition;
140
+ /**
141
+ * Framework-owned key root. All {@link storageKeys} values live under this
142
+ * prefix so a shared store can route or namespace agentkit data.
143
+ */
144
+ export declare const STORAGE_KEY_ROOT: "agentkit/v1";
145
+ /**
146
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
147
+ * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
148
+ * route on prefixes (e.g. event chunks to object storage, everything else
149
+ * to a database). Channel ids and continuation tokens are the only segments
150
+ * that may contain caller-controlled characters; they are URI-encoded, and
151
+ * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
152
+ * by a `sha256:…` digest — so every minted key has a bounded length that any
153
+ * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
154
+ * no matter what a caller stuffs into a token. The substitution is
155
+ * deterministic: writes and continuation lookups build the same key.
156
+ *
157
+ * | Key | Value |
158
+ * | --- | --- |
159
+ * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
160
+ * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
161
+ * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
162
+ * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
163
+ * | `agentkit/v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
164
+ * | `agentkit/v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
165
+ * | `agentkit/v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
166
+ */
167
+ export declare const storageKeys: {
168
+ readonly session: (agent: string, sessionId: string) => string;
169
+ readonly sessionPrefix: (agent: string) => string;
170
+ readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
171
+ readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
172
+ readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
173
+ readonly reminder: (agent: string, reminderId: string) => string;
174
+ readonly reminderPrefix: (agent: string) => string;
175
+ readonly evalRun: (agent: string, runId: string) => string;
176
+ readonly evalRunPrefix: (agent: string) => string;
177
+ readonly abSample: (agent: string, sessionId: string, at: string) => string;
178
+ readonly abSnapshot: (agent: string) => string;
179
+ };
180
+ /**
181
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
182
+ * Chosen so full keys stay well under common backend limits (Postgres btree
183
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
184
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
185
+ */
186
+ export declare const MAX_KEY_SEGMENT_BYTES = 256;
187
+ export declare const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;
188
+ export declare const STORAGE_DEFAULT_RESTORE_MAX_AGE_MS: number;
189
+ export declare const STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1073741824;
190
+ /** {@link StoragePolicy} with defaults applied. */
191
+ export interface ResolvedStoragePolicy {
192
+ /** Event-chunk flush trigger: per turn, or debounced across turns. */
193
+ events: "turnEnd" | {
194
+ debounceMs: number;
195
+ };
196
+ restore: "off" | {
197
+ maxSessions: number;
198
+ maxAgeMs: number;
199
+ maxTotalBytes: number;
200
+ };
201
+ }
202
+ /** Apply {@link StoragePolicy} defaults (exposed for tooling/tests). */
203
+ export declare function resolveStoragePolicy(policy: StoragePolicy | undefined): ResolvedStoragePolicy;
204
+ //# sourceMappingURL=storage.d.ts.map
package/dist/storage.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}
package/dist/storage.js ADDED
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Durable storage plug-in for agent-serve.
3
+ *
4
+ * Author `agent/storage.ts` with {@link defineStorage} to mirror the
5
+ * framework's durable state into storage you own (a database, S3, a data
6
+ * pipeline, …). Without it, state lives under `--state-root` on local disk
7
+ * only (and eval/A/B history follows the narrower `persistRuns` /
8
+ * `persistSamples` / `persistSnapshots` hooks).
9
+ *
10
+ * The sink is a plain key-value store — four functions, no schema:
11
+ *
12
+ * ```ts
13
+ * import { defineStorage } from "@anysphere/agent-serve/storage";
14
+ *
15
+ * export default defineStorage({
16
+ * put: (key, value) => db.upsert(key, value),
17
+ * get: (key) => db.get(key),
18
+ * delete: (key) => db.delete(key),
19
+ * list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
20
+ * });
21
+ * ```
22
+ *
23
+ * The **framework mints every key** from a stable, versioned scheme (see
24
+ * {@link storageKeys}) and decides **when** to call the sink: session
25
+ * records and event chunks flush when a turn's handlers have settled,
26
+ * reads happen at serve start (bulk restore), on continuation-token misses
27
+ * (lazy restore), and at playground hydration. Authors do not schedule
28
+ * reads or writes — the only timing knobs are {@link StoragePolicy}'s
29
+ * `debounceMs` (event write batching) and `restore` (startup hydration).
30
+ *
31
+ * Because keys are opaque strings to the sink, new kinds of durable state
32
+ * (channel cursors, thread affinity, …) are new key prefixes — existing
33
+ * sinks store them with no code changes.
34
+ *
35
+ * Delivery semantics: writes are **serialized** (one sink call in flight
36
+ * per agent, in order), **bounded** (a sink that falls behind sheds writes
37
+ * rather than growing memory), and **at-most-once** — a throwing `put` is
38
+ * logged and dropped, never retried, and never fails a turn. The local
39
+ * event log under `--state-root` remains the live source of truth; this
40
+ * interface is the durable mirror.
41
+ */
42
+ import { createHash } from "node:crypto";
43
+ import { brandDefinition } from "./internal/brand.js";
44
+ /**
45
+ * Author the project storage sink (`agent/storage.ts`, default
46
+ * export). See the module doc for semantics and an example.
47
+ */
48
+ export function defineStorage(config) {
49
+ if (typeof config.put !== "function") {
50
+ throw new Error("defineStorage: config.put must be a function");
51
+ }
52
+ for (const hook of ["get", "list", "delete"]) {
53
+ const value = config[hook];
54
+ if (value !== undefined && typeof value !== "function") {
55
+ throw new Error(`defineStorage: config.${hook} must be a function when set`);
56
+ }
57
+ }
58
+ // Validate eagerly so a bad policy fails at discovery, not first flush.
59
+ resolveStoragePolicy(config.policy);
60
+ return brandDefinition("storage", config);
61
+ }
62
+ // ============================================================================
63
+ // Key scheme
64
+ // ============================================================================
65
+ /**
66
+ * Framework-owned key root. All {@link storageKeys} values live under this
67
+ * prefix so a shared store can route or namespace agentkit data.
68
+ */
69
+ export const STORAGE_KEY_ROOT = "agentkit/v1";
70
+ /**
71
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
72
+ * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
73
+ * route on prefixes (e.g. event chunks to object storage, everything else
74
+ * to a database). Channel ids and continuation tokens are the only segments
75
+ * that may contain caller-controlled characters; they are URI-encoded, and
76
+ * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
77
+ * by a `sha256:…` digest — so every minted key has a bounded length that any
78
+ * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
79
+ * no matter what a caller stuffs into a token. The substitution is
80
+ * deterministic: writes and continuation lookups build the same key.
81
+ *
82
+ * | Key | Value |
83
+ * | --- | --- |
84
+ * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
85
+ * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
86
+ * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
87
+ * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
88
+ * | `agentkit/v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
89
+ * | `agentkit/v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
90
+ * | `agentkit/v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
91
+ */
92
+ export const storageKeys = {
93
+ session: (agent, sessionId) => `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
94
+ sessionPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/session/`,
95
+ sessionEvents: (agent, sessionId, firstIndex) => `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
96
+ sessionEventsPrefix: (agent, sessionId) => `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
97
+ continuation: (agent, channelId, continuationKey) => `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
98
+ reminder: (agent, reminderId) => `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
99
+ reminderPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
100
+ evalRun: (agent, runId) => `${STORAGE_KEY_ROOT}/${agent}/eval-run/${runId}`,
101
+ evalRunPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/eval-run/`,
102
+ abSample: (agent, sessionId, at) => `${STORAGE_KEY_ROOT}/${agent}/ab-sample/${sessionId}/${at}`,
103
+ abSnapshot: (agent) => `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
104
+ };
105
+ /**
106
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
107
+ * Chosen so full keys stay well under common backend limits (Postgres btree
108
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
109
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
110
+ */
111
+ export const MAX_KEY_SEGMENT_BYTES = 256;
112
+ /**
113
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
114
+ * digest of the raw value when the encoding exceeds
115
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
116
+ * write path and the continuation-lookup path always agree.
117
+ */
118
+ function keySegment(raw) {
119
+ const encoded = encodeURIComponent(raw);
120
+ if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
121
+ return encoded;
122
+ }
123
+ return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
124
+ }
125
+ // ============================================================================
126
+ // Policy resolution
127
+ // ============================================================================
128
+ export const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;
129
+ export const STORAGE_DEFAULT_RESTORE_MAX_AGE_MS = 30 * 24 * 60 * 60000;
130
+ export const STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1073741824; // 1 GiB
131
+ /** Apply {@link StoragePolicy} defaults (exposed for tooling/tests). */
132
+ export function resolveStoragePolicy(policy) {
133
+ var _a, _b, _c;
134
+ return {
135
+ events: (policy === null || policy === void 0 ? void 0 : policy.debounceMs) === undefined
136
+ ? "turnEnd"
137
+ : { debounceMs: clampInt(policy.debounceMs, 2000, 0, 60000) },
138
+ restore: (policy === null || policy === void 0 ? void 0 : policy.restore) === "off"
139
+ ? "off"
140
+ : {
141
+ maxSessions: clampInt((_a = policy === null || policy === void 0 ? void 0 : policy.restore) === null || _a === void 0 ? void 0 : _a.maxSessions, STORAGE_DEFAULT_RESTORE_MAX_SESSIONS, 0, 1000000),
142
+ maxAgeMs: clampInt((_b = policy === null || policy === void 0 ? void 0 : policy.restore) === null || _b === void 0 ? void 0 : _b.maxAgeMs, STORAGE_DEFAULT_RESTORE_MAX_AGE_MS, 0, 10 * 365 * 24 * 60 * 60000),
143
+ maxTotalBytes: clampInt((_c = policy === null || policy === void 0 ? void 0 : policy.restore) === null || _c === void 0 ? void 0 : _c.maxTotalBytes, STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES, 0, 1099511627776 // 1 TiB
144
+ ),
145
+ },
146
+ };
147
+ }
148
+ function clampInt(value, fallback, min, max) {
149
+ if (value === undefined || !Number.isFinite(value)) {
150
+ return fallback;
151
+ }
152
+ return Math.min(max, Math.max(min, Math.floor(value)));
153
+ }
package/dist/types.d.ts CHANGED
@@ -10,6 +10,7 @@
10
10
  import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
11
11
  import type { z } from "zod";
12
12
  import type { ABConfigFile } from "./ab.js";
13
+ import type { StorageDefinition } from "./storage.js";
13
14
  export type JsonPrimitive = string | number | boolean | null;
14
15
  export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject;
15
16
  export type JsonObject = {
@@ -21,7 +22,7 @@ export type JsonSchemaObject = Record<string, unknown>;
21
22
  * Discriminates the `define*` helper that produced a module's default export
22
23
  * so discovery can validate that a file landed in the right authored slot.
23
24
  */
24
- export type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "ab";
25
+ export type DefinitionKind = "agent" | "instructions" | "tool" | "skill" | "connection" | "channel" | "http-channel" | "schedule" | "reminder" | "hook" | "eval" | "ab" | "storage";
25
26
  export interface BrandedDefinition<K extends DefinitionKind> {
26
27
  readonly __agentServe: K;
27
28
  }
@@ -120,6 +121,33 @@ export interface AgentConfig {
120
121
  * {@link cloud}.
121
122
  */
122
123
  local?: AgentLocalOptions;
124
+ /**
125
+ * Managed-hosting declarations (`agentkit deploy` onto Cursor's
126
+ * agent-serve hosting). The manifest is the source of truth: deploy reads
127
+ * it and sends it with the deployment request. Ignored by local serving.
128
+ */
129
+ hosting?: AgentHostingOptions;
130
+ }
131
+ /**
132
+ * Managed-hosting block on {@link AgentConfig.hosting}.
133
+ */
134
+ export interface AgentHostingOptions {
135
+ /**
136
+ * Domains the deployed engine pod may reach (egress allowlist), e.g.
137
+ * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
138
+ * Lowercase hostnames with at least two labels and an alphabetic TLD;
139
+ * max 20. `agentkit deploy` sends these as `egressAllowedDomains`
140
+ * (unioned with any `--allow-domain` flags). Only valid on repo-backed
141
+ * deployments.
142
+ */
143
+ egressDomains?: string[];
144
+ /**
145
+ * Secret names this agent expects at runtime (declarative documentation;
146
+ * values are never authored in files). `agentkit deploy` warns when a
147
+ * declared name is not set on the deployment — set values with
148
+ * `agentkit secrets set <slug> NAME`.
149
+ */
150
+ secretNames?: string[];
123
151
  }
124
152
  /**
125
153
  * Local runtime options on {@link AgentConfig.local}.
@@ -410,6 +438,11 @@ export interface ActionCall {
410
438
  callId: string;
411
439
  toolName: string;
412
440
  args?: unknown;
441
+ /**
442
+ * When set, this tool call belongs to a nested subagent turn whose
443
+ * parent `task` tool call id is `parentCallId`.
444
+ */
445
+ parentCallId?: string;
413
446
  }
414
447
  /** Human decision for a parked {@link ToolConfig.needsApproval} tool call. */
415
448
  export type ApprovalDecision = "approve" | "deny";
@@ -468,28 +501,33 @@ export type SessionEventPayload = {
468
501
  data: {
469
502
  delta: string;
470
503
  text: string;
504
+ parentCallId?: string;
471
505
  };
472
506
  } | {
473
507
  type: "reasoning.completed";
474
508
  data: {
475
509
  durationMs?: number;
510
+ parentCallId?: string;
476
511
  };
477
512
  } | {
478
513
  type: "message.appended";
479
514
  data: {
480
515
  delta: string;
481
516
  text: string;
517
+ parentCallId?: string;
482
518
  };
483
519
  } | {
484
520
  type: "message.completed";
485
521
  data: {
486
522
  text: string;
487
523
  finishReason: "stop" | "tool_call";
524
+ parentCallId?: string;
488
525
  };
489
526
  } | {
490
527
  type: "actions.requested";
491
528
  data: {
492
529
  calls: ActionCall[];
530
+ parentCallId?: string;
493
531
  };
494
532
  } | {
495
533
  /**
@@ -502,6 +540,7 @@ export type SessionEventPayload = {
502
540
  callId: string;
503
541
  toolName: string;
504
542
  args?: unknown;
543
+ parentCallId?: string;
505
544
  };
506
545
  } | {
507
546
  type: "action.approval_resolved";
@@ -510,6 +549,7 @@ export type SessionEventPayload = {
510
549
  toolName: string;
511
550
  decision: ApprovalDecision;
512
551
  by?: string;
552
+ parentCallId?: string;
513
553
  };
514
554
  } | {
515
555
  type: "action.result";
@@ -518,6 +558,7 @@ export type SessionEventPayload = {
518
558
  toolName: string;
519
559
  output?: unknown;
520
560
  isError: boolean;
561
+ parentCallId?: string;
521
562
  };
522
563
  } | {
523
564
  type: "subagent.called";
@@ -1292,7 +1333,10 @@ export interface ResolvedAgent {
1292
1333
  name: string;
1293
1334
  description?: string;
1294
1335
  model?: ModelSetting;
1295
- /** Composed system prompt (instructions.md / instructions.ts / agent.ts). */
1336
+ /**
1337
+ * Composed system prompt: identity preamble from {@link name}, then
1338
+ * authored `instructions.md` / `.ts` / dir (or inline `agent.ts`).
1339
+ */
1296
1340
  instructions?: string;
1297
1341
  /** Execution runtime. Root agents default to `"local"`. */
1298
1342
  runtime: AgentRuntime;
@@ -1303,6 +1347,8 @@ export interface ResolvedAgent {
1303
1347
  * (`cwd` is absolute — relative paths resolved against the project root).
1304
1348
  */
1305
1349
  local?: AgentLocalOptions;
1350
+ /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
1351
+ hosting?: AgentHostingOptions;
1306
1352
  tools: DiscoveredTool[];
1307
1353
  skills: DiscoveredSkill[];
1308
1354
  connections: DiscoveredConnection[];
@@ -1326,6 +1372,8 @@ export interface AgentProject {
1326
1372
  abs: DiscoveredAB[];
1327
1373
  /** Optional `agent/ab.config.ts` (`defineABConfig`). */
1328
1374
  abConfig?: ABConfigFile;
1375
+ /** Optional `agent/storage.ts` (`defineStorage`). */
1376
+ storage?: StorageDefinition;
1329
1377
  diagnostics: Diagnostic[];
1330
1378
  }
1331
1379
  /** JSON-safe projection of one channel HTTP route on `GET /v1/info`. */
@@ -1349,6 +1397,11 @@ export interface AgentProjectInfo {
1349
1397
  local?: {
1350
1398
  cwd?: string;
1351
1399
  };
1400
+ /** Managed-hosting declarations when authored (egress allowlist, expected secrets). */
1401
+ hosting?: {
1402
+ egressDomains?: string[];
1403
+ secretNames?: string[];
1404
+ };
1352
1405
  /**
1353
1406
  * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
1354
1407
  * and MCP clients delegate to this agent through these tools.
@@ -1399,12 +1452,16 @@ export interface AgentProjectInfo {
1399
1452
  hooks: string[];
1400
1453
  /** Live A/B experiment names (`defineAB` under `agent/ab`). */
1401
1454
  abs: string[];
1402
- /** Playground fold / persistence meta from `agent/ab.config.ts`. */
1455
+ /** Playground fold / durable-sink meta from `agent/ab.config.ts`. */
1403
1456
  abConfig?: {
1404
1457
  maxPlaygroundSessions?: number;
1405
1458
  durableSamples: boolean;
1406
1459
  durableSnapshots: boolean;
1407
1460
  };
1461
+ /** Project storage sink from `agent/storage.ts`, when authored. */
1462
+ storage?: {
1463
+ name?: string;
1464
+ };
1408
1465
  diagnostics: Diagnostic[];
1409
1466
  }
1410
1467
  /**
@@ -1512,9 +1569,18 @@ export interface ServeOptions {
1512
1569
  * {@link authToken}. Authored `auth` arrays still win.
1513
1570
  */
1514
1571
  allowAnonymous?: boolean;
1572
+ /**
1573
+ * Allow {@link allowAnonymous} together with
1574
+ * `githubChannel({ cursorAccount })`. Without this opt-in, `serve` refuses
1575
+ * to start because every admitted anonymous caller could drive sessions
1576
+ * that hold the signed-in account's repo-scoped GitHub credential. Set it
1577
+ * only when the network boundary already authenticates callers (e.g. an
1578
+ * SSO/Okta proxy in front of the host).
1579
+ */
1580
+ allowAnonymousCursorGithub?: boolean;
1515
1581
  /**
1516
1582
  * Public base URL where this server is reachable from outside the host
1517
- * (e.g. `https://agent-serve.corp.anysphere.co`). Used to resolve peer
1583
+ * (e.g. `https://agents.example.com`). Used to resolve peer
1518
1584
  * connections (`defineConnection({ agent })`) for **cloud-runtime** turns:
1519
1585
  * a cloud VM cannot reach this host's loopback address, so without a
1520
1586
  * public URL peer tools are omitted from cloud turns (with a warning).