@cursor/july 0.1.2 → 0.1.4

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 (232) hide show
  1. package/AGENTS.md +16 -5
  2. package/README.md +8 -9
  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 +416 -155
  6. package/dist/channels/slack/log.d.ts +1 -1
  7. package/dist/channels/slack/log.d.ts.map +1 -1
  8. package/dist/channels/slack/log.js +4 -5
  9. package/dist/channels/slack/setup.js +1 -1
  10. package/dist/channels/slack/socket-mode.d.ts.map +1 -1
  11. package/dist/channels/slack/socket-mode.js +10 -9
  12. package/dist/docs/404.html +2 -2
  13. package/dist/docs/ab.html +3 -3
  14. package/dist/docs/assets/{app.Oje4vhlk.js → app.DF-Yx4OP.js} +1 -1
  15. package/dist/docs/assets/chunks/@localSearchIndexroot.0XrheBv2.js +1 -0
  16. package/dist/docs/assets/chunks/{VPLocalSearchBox.H5XZ2zCB.js → VPLocalSearchBox.DSeJSudL.js} +1 -1
  17. package/dist/docs/assets/chunks/{theme.CTR_TuaE.js → theme.DZVLTXOC.js} +2 -2
  18. package/dist/docs/assets/{index.md.m81y7TY7.js → index.md.Cylk70gg.js} +1 -1
  19. package/dist/docs/assets/{quickstart.md.CfU8_uTC.js → quickstart.md.BU6Iwi_9.js} +18 -6
  20. package/dist/docs/assets/{reference_cli.md.DA730zCu.js → reference_cli.md.Bv6pOxcF.js} +11 -6
  21. package/dist/docs/assets/{reference_cli.md.DA730zCu.lean.js → reference_cli.md.Bv6pOxcF.lean.js} +1 -1
  22. package/dist/docs/building-with-agents.html +3 -3
  23. package/dist/docs/concepts.html +3 -3
  24. package/dist/docs/deployment.html +3 -3
  25. package/dist/docs/evals.html +3 -3
  26. package/dist/docs/guides/agent-to-agent.html +3 -3
  27. package/dist/docs/guides/cloud-runtime.html +3 -3
  28. package/dist/docs/guides/github.html +3 -3
  29. package/dist/docs/guides/human-in-the-loop.html +3 -3
  30. package/dist/docs/guides/slack.html +3 -3
  31. package/dist/docs/guides/webhooks.html +3 -3
  32. package/dist/docs/hashmap.json +1 -1
  33. package/dist/docs/hillclimbing.html +3 -3
  34. package/dist/docs/index.html +5 -5
  35. package/dist/docs/quickstart.html +22 -10
  36. package/dist/docs/reference/agent-config.html +3 -3
  37. package/dist/docs/reference/channels.html +3 -3
  38. package/dist/docs/reference/cli.html +14 -9
  39. package/dist/docs/reference/connections.html +3 -3
  40. package/dist/docs/reference/hooks.html +3 -3
  41. package/dist/docs/reference/http-api.html +3 -3
  42. package/dist/docs/reference/instructions.html +3 -3
  43. package/dist/docs/reference/playground.html +3 -3
  44. package/dist/docs/reference/project-layout.html +3 -3
  45. package/dist/docs/reference/schedules.html +3 -3
  46. package/dist/docs/reference/sessions.html +3 -3
  47. package/dist/docs/reference/skills.html +3 -3
  48. package/dist/docs/reference/subagents.html +3 -3
  49. package/dist/docs/reference/tools.html +3 -3
  50. package/dist/docs/scaffolding-agents.html +3 -3
  51. package/dist/docs/storage.html +3 -3
  52. package/dist/docs/troubleshooting.html +3 -3
  53. package/dist/internal/ab-collector.js +3 -3
  54. package/dist/internal/ab-fold.js +1 -1
  55. package/dist/internal/chat-client.d.ts +29 -3
  56. package/dist/internal/chat-client.d.ts.map +1 -1
  57. package/dist/internal/chat-client.js +180 -27
  58. package/dist/internal/cli-ax.d.ts +83 -2
  59. package/dist/internal/cli-ax.d.ts.map +1 -1
  60. package/dist/internal/cli-ax.js +626 -52
  61. package/dist/internal/cli-cursor.d.ts.map +1 -1
  62. package/dist/internal/cli-cursor.js +8 -36
  63. package/dist/internal/cli-deploy.d.ts +59 -3
  64. package/dist/internal/cli-deploy.d.ts.map +1 -1
  65. package/dist/internal/cli-deploy.js +316 -38
  66. package/dist/internal/cli-github.js +13 -13
  67. package/dist/internal/cursor/account-mcp.js +3 -3
  68. package/dist/internal/cursor/backend-client.js +1 -1
  69. package/dist/internal/cursor/credentials.d.ts +14 -3
  70. package/dist/internal/cursor/credentials.d.ts.map +1 -1
  71. package/dist/internal/cursor/credentials.js +21 -6
  72. package/dist/internal/cursor/github-credentials.js +3 -3
  73. package/dist/internal/cursor-event-relay.js +1 -1
  74. package/dist/internal/cursor-relay-core.d.ts +1 -1
  75. package/dist/internal/cursor-relay-core.d.ts.map +1 -1
  76. package/dist/internal/cursor-relay-core.js +2 -1
  77. package/dist/internal/cursor-slack-relay.js +1 -1
  78. package/dist/internal/deploy-client.d.ts +9 -1
  79. package/dist/internal/deploy-client.d.ts.map +1 -1
  80. package/dist/internal/deploy-client.js +23 -3
  81. package/dist/internal/deploy-source.d.ts +35 -0
  82. package/dist/internal/deploy-source.d.ts.map +1 -0
  83. package/dist/internal/deploy-source.js +118 -0
  84. package/dist/internal/discovery.d.ts +11 -0
  85. package/dist/internal/discovery.d.ts.map +1 -1
  86. package/dist/internal/discovery.js +43 -14
  87. package/dist/internal/distribution.d.ts +7 -0
  88. package/dist/internal/distribution.d.ts.map +1 -1
  89. package/dist/internal/distribution.js +7 -0
  90. package/dist/internal/docs-site.js +3 -3
  91. package/dist/internal/eval-run-store.d.ts.map +1 -1
  92. package/dist/internal/eval-run-store.js +10 -9
  93. package/dist/internal/eval-runner.d.ts +2 -0
  94. package/dist/internal/eval-runner.d.ts.map +1 -1
  95. package/dist/internal/eval-runner.js +2 -0
  96. package/dist/internal/event-mapper.d.ts +54 -1
  97. package/dist/internal/event-mapper.d.ts.map +1 -1
  98. package/dist/internal/event-mapper.js +151 -41
  99. package/dist/internal/github-fanout.js +2 -2
  100. package/dist/internal/host-platforms.js +5 -5
  101. package/dist/internal/init-project.d.ts +88 -1
  102. package/dist/internal/init-project.d.ts.map +1 -1
  103. package/dist/internal/init-project.js +221 -31
  104. package/dist/internal/install-cursor-skills.d.ts +64 -0
  105. package/dist/internal/install-cursor-skills.d.ts.map +1 -0
  106. package/dist/internal/install-cursor-skills.js +274 -0
  107. package/dist/internal/logs-client.d.ts +60 -0
  108. package/dist/internal/logs-client.d.ts.map +1 -0
  109. package/dist/internal/logs-client.js +311 -0
  110. package/dist/internal/mcp-endpoint.d.ts.map +1 -1
  111. package/dist/internal/mcp-endpoint.js +1 -1
  112. package/dist/internal/open-browser.d.ts +5 -0
  113. package/dist/internal/open-browser.d.ts.map +1 -0
  114. package/dist/internal/open-browser.js +34 -0
  115. package/dist/internal/playground/toolchain.d.ts.map +1 -1
  116. package/dist/internal/playground/toolchain.js +19 -14
  117. package/dist/internal/playground-proxy.d.ts +69 -0
  118. package/dist/internal/playground-proxy.d.ts.map +1 -0
  119. package/dist/internal/playground-proxy.js +468 -0
  120. package/dist/internal/prompt-context.d.ts +35 -0
  121. package/dist/internal/prompt-context.d.ts.map +1 -0
  122. package/dist/internal/prompt-context.js +71 -0
  123. package/dist/internal/reminder-runner.d.ts.map +1 -1
  124. package/dist/internal/reminder-runner.js +11 -11
  125. package/dist/internal/request-headers.d.ts +11 -0
  126. package/dist/internal/request-headers.d.ts.map +1 -0
  127. package/dist/internal/request-headers.js +14 -0
  128. package/dist/internal/resolve-prod-target.d.ts +44 -0
  129. package/dist/internal/resolve-prod-target.d.ts.map +1 -0
  130. package/dist/internal/resolve-prod-target.js +134 -0
  131. package/dist/internal/resolved-connections.js +5 -5
  132. package/dist/internal/run-client.d.ts +2 -2
  133. package/dist/internal/run-client.d.ts.map +1 -1
  134. package/dist/internal/run-client.js +38 -23
  135. package/dist/internal/schedule-runner.js +1 -1
  136. package/dist/internal/server.d.ts.map +1 -1
  137. package/dist/internal/server.js +23 -17
  138. package/dist/internal/session-engine.d.ts +1 -1
  139. package/dist/internal/session-engine.d.ts.map +1 -1
  140. package/dist/internal/session-engine.js +34 -19
  141. package/dist/internal/sessions-client.d.ts +34 -0
  142. package/dist/internal/sessions-client.d.ts.map +1 -0
  143. package/dist/internal/sessions-client.js +193 -0
  144. package/dist/internal/storage-coordinator.js +6 -6
  145. package/dist/internal/stream-progress.d.ts.map +1 -1
  146. package/dist/internal/stream-progress.js +31 -3
  147. package/dist/internal/terminal-style.d.ts +22 -0
  148. package/dist/internal/terminal-style.d.ts.map +1 -0
  149. package/dist/internal/terminal-style.js +49 -0
  150. package/dist/internal/trajectory.d.ts +10 -5
  151. package/dist/internal/trajectory.d.ts.map +1 -1
  152. package/dist/internal/trajectory.js +82 -10
  153. package/dist/internal/update-check.d.ts +93 -0
  154. package/dist/internal/update-check.d.ts.map +1 -0
  155. package/dist/internal/update-check.js +431 -0
  156. package/dist/internal/workspace.d.ts +11 -0
  157. package/dist/internal/workspace.d.ts.map +1 -1
  158. package/dist/internal/workspace.js +38 -4
  159. package/dist/playground/assets/index-Ct_Usdm8.css +1 -0
  160. package/dist/playground/assets/index-Dsyb-Vaj.js +319 -0
  161. package/dist/playground/index.html +2 -2
  162. package/dist/types.d.ts +29 -2
  163. package/dist/types.d.ts.map +1 -1
  164. package/docs/README.md +0 -1
  165. package/docs/quickstart.md +22 -7
  166. package/docs/reference/cli.md +51 -3
  167. package/package.json +4 -1
  168. package/skills/ab/SKILL.md +8 -8
  169. package/skills/create-agent/SKILL.md +28 -22
  170. package/skills/debug/SKILL.md +11 -11
  171. package/skills/evals/SKILL.md +16 -16
  172. package/skills/framework-map/SKILL.md +6 -6
  173. package/skills/github/SKILL.md +13 -13
  174. package/skills/hillclimb/SKILL.md +10 -10
  175. package/skills/setup-slack/SKILL.md +14 -14
  176. package/src/bin/agent-serve.ts +451 -191
  177. package/src/channels/slack/log.ts +5 -5
  178. package/src/channels/slack/setup.ts +1 -1
  179. package/src/channels/slack/socket-mode.ts +11 -9
  180. package/src/internal/ab-collector.ts +3 -3
  181. package/src/internal/ab-fold.ts +1 -1
  182. package/src/internal/chat-client.ts +252 -37
  183. package/src/internal/cli-ax.ts +761 -72
  184. package/src/internal/cli-cursor.ts +14 -42
  185. package/src/internal/cli-deploy.ts +428 -49
  186. package/src/internal/cli-github.ts +13 -15
  187. package/src/internal/cursor/account-mcp.ts +3 -3
  188. package/src/internal/cursor/backend-client.ts +1 -1
  189. package/src/internal/cursor/credentials.ts +26 -7
  190. package/src/internal/cursor/github-credentials.ts +3 -3
  191. package/src/internal/cursor-event-relay.ts +1 -1
  192. package/src/internal/cursor-relay-core.ts +4 -2
  193. package/src/internal/cursor-slack-relay.ts +1 -1
  194. package/src/internal/deploy-client.ts +45 -4
  195. package/src/internal/deploy-source.ts +133 -0
  196. package/src/internal/discovery.ts +53 -16
  197. package/src/internal/distribution.ts +8 -0
  198. package/src/internal/docs-site.ts +3 -3
  199. package/src/internal/eval-run-store.ts +10 -11
  200. package/src/internal/eval-runner.ts +5 -0
  201. package/src/internal/event-mapper.ts +222 -42
  202. package/src/internal/github-fanout.ts +2 -2
  203. package/src/internal/host-platforms.ts +5 -5
  204. package/src/internal/init-project.ts +333 -51
  205. package/src/internal/install-cursor-skills.ts +327 -0
  206. package/src/internal/logs-client.ts +442 -0
  207. package/src/internal/mcp-endpoint.ts +1 -3
  208. package/src/internal/open-browser.ts +41 -0
  209. package/src/internal/playground/toolchain.ts +18 -16
  210. package/src/internal/playground-proxy.ts +576 -0
  211. package/src/internal/prompt-context.ts +95 -0
  212. package/src/internal/reminder-runner.ts +11 -17
  213. package/src/internal/request-headers.ts +23 -0
  214. package/src/internal/resolve-prod-target.ts +182 -0
  215. package/src/internal/resolved-connections.ts +5 -5
  216. package/src/internal/run-client.ts +39 -36
  217. package/src/internal/schedule-runner.ts +1 -1
  218. package/src/internal/server.ts +25 -16
  219. package/src/internal/session-engine.ts +35 -18
  220. package/src/internal/sessions-client.ts +216 -0
  221. package/src/internal/storage-coordinator.ts +6 -6
  222. package/src/internal/stream-progress.ts +36 -2
  223. package/src/internal/terminal-style.ts +74 -0
  224. package/src/internal/trajectory.ts +91 -13
  225. package/src/internal/update-check.ts +552 -0
  226. package/src/internal/workspace.ts +42 -4
  227. package/src/types.ts +45 -7
  228. package/dist/docs/assets/chunks/@localSearchIndexroot.zwQ9RCQ7.js +0 -1
  229. package/dist/playground/assets/index-B1Qc9h2u.css +0 -1
  230. package/dist/playground/assets/index-CpDYCj8W.js +0 -79
  231. /package/dist/docs/assets/{index.md.m81y7TY7.lean.js → index.md.Cylk70gg.lean.js} +0 -0
  232. /package/dist/docs/assets/{quickstart.md.CfU8_uTC.lean.js → quickstart.md.BU6Iwi_9.lean.js} +0 -0
@@ -143,7 +143,7 @@ export class ReminderRunner {
143
143
  }
144
144
  if (restored > 0 || disarmedOrphan > 0) {
145
145
  this.logger(
146
- `[agent-serve] reminders: restored ${restored} armed reminder(s)` +
146
+ `[agentkit] reminders: restored ${restored} armed reminder(s)` +
147
147
  (disarmedOrphan > 0
148
148
  ? `; disarmed ${disarmedOrphan} without live handlers`
149
149
  : "")
@@ -174,14 +174,12 @@ export class ReminderRunner {
174
174
  }
175
175
  } catch (error) {
176
176
  const message = error instanceof Error ? error.message : String(error);
177
- this.logger(
178
- `[agent-serve] reminders: storage hydrate failed: ${message}`
179
- );
177
+ this.logger(`[agentkit] reminders: storage hydrate failed: ${message}`);
180
178
  return;
181
179
  }
182
180
  if (hydrated > 0) {
183
181
  this.logger(
184
- `[agent-serve] reminders: hydrated ${hydrated} reminder(s) from storage`
182
+ `[agentkit] reminders: hydrated ${hydrated} reminder(s) from storage`
185
183
  );
186
184
  }
187
185
  }
@@ -366,7 +364,7 @@ export class ReminderRunner {
366
364
  const timer = setTimeout(() => {
367
365
  void this.fire(record.id).catch(async (error) => {
368
366
  this.logger(
369
- `[agent-serve] reminder "${record.id}" fire failed: ${
367
+ `[agentkit] reminder "${record.id}" fire failed: ${
370
368
  error instanceof Error ? error.message : String(error)
371
369
  }`
372
370
  );
@@ -384,7 +382,7 @@ export class ReminderRunner {
384
382
  await this.afterFire(current, "skip");
385
383
  } catch (rescheduleError) {
386
384
  this.logger(
387
- `[agent-serve] reminder "${record.id}" reschedule after failure failed: ${
385
+ `[agentkit] reminder "${record.id}" reschedule after failure failed: ${
388
386
  rescheduleError instanceof Error
389
387
  ? rescheduleError.message
390
388
  : String(rescheduleError)
@@ -447,7 +445,7 @@ export class ReminderRunner {
447
445
  }
448
446
  } catch (error) {
449
447
  this.logger(
450
- `[agent-serve] reminder "${id}" until() failed: ${
448
+ `[agentkit] reminder "${id}" until() failed: ${
451
449
  error instanceof Error ? error.message : String(error)
452
450
  }`
453
451
  );
@@ -460,7 +458,7 @@ export class ReminderRunner {
460
458
  if (record.busyPolicy === "skipIfBusy") {
461
459
  await this.afterFire(record, "skip");
462
460
  this.logger(
463
- `[agent-serve] reminder "${id}" (${record.purpose}) skipped: session busy`
461
+ `[agentkit] reminder "${id}" (${record.purpose}) skipped: session busy`
464
462
  );
465
463
  return { outcome: "fired", reason: "skipped_busy" };
466
464
  }
@@ -488,7 +486,7 @@ export class ReminderRunner {
488
486
  if (latest !== undefined && latest.status === "armed") {
489
487
  await this.disarm(latest, "run_stop");
490
488
  this.logger(
491
- `[agent-serve] reminder "${id}" (${record.purpose}) disarmed: run_stop`
489
+ `[agentkit] reminder "${id}" (${record.purpose}) disarmed: run_stop`
492
490
  );
493
491
  return { outcome: "fired", reason: "run_stop" };
494
492
  }
@@ -503,15 +501,11 @@ export class ReminderRunner {
503
501
 
504
502
  if (result.action === "skip") {
505
503
  await this.afterFire(latest, "skip", result.reschedule);
506
- this.logger(
507
- `[agent-serve] reminder "${id}" (${record.purpose}) skipped`
508
- );
504
+ this.logger(`[agentkit] reminder "${id}" (${record.purpose}) skipped`);
509
505
  return { outcome: "fired", reason: "skipped" };
510
506
  }
511
507
  await this.afterFire(latest, "delivered", result.reschedule);
512
- this.logger(
513
- `[agent-serve] reminder "${id}" (${record.purpose}) delivered`
514
- );
508
+ this.logger(`[agentkit] reminder "${id}" (${record.purpose}) delivered`);
515
509
  return { outcome: "fired", reason: "delivered" };
516
510
  } finally {
517
511
  this.firing.delete(id);
@@ -613,7 +607,7 @@ export class ReminderRunner {
613
607
  return { action: "delivered" };
614
608
  } catch (retryError) {
615
609
  this.logger(
616
- `[agent-serve] reminder "${record.id}" followup failed after wait: ${
610
+ `[agentkit] reminder "${record.id}" followup failed after wait: ${
617
611
  retryError instanceof Error
618
612
  ? retryError.message
619
613
  : String(retryError)
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Merge Authorization bearer + arbitrary request headers for agent HTTP
3
+ * clients (local `--bearer-token`, hosted `engineAccess.headers`, etc.).
4
+ */
5
+
6
+ export interface RequestAuth {
7
+ bearerToken?: string;
8
+ /** Extra headers (e.g. X-Anyrun-Port-Token from engineAccess). */
9
+ headers?: Record<string, string>;
10
+ }
11
+
12
+ export function mergeRequestHeaders(
13
+ auth: RequestAuth | undefined
14
+ ): Record<string, string> {
15
+ const out: Record<string, string> = {};
16
+ if (auth?.headers !== undefined) {
17
+ Object.assign(out, auth.headers);
18
+ }
19
+ if (auth?.bearerToken !== undefined) {
20
+ out.authorization = `Bearer ${auth.bearerToken}`;
21
+ }
22
+ return out;
23
+ }
@@ -0,0 +1,182 @@
1
+ /**
2
+ * Resolve a hosted (managed) agent-serve deployment into a base URL +
3
+ * request headers for chat/run/call/eval `--prod`.
4
+ *
5
+ * Uses short-lived `engineAccess` from the deployment status route
6
+ * (Cursor API key on the management API; `X-Anyrun-Port-Token` on the
7
+ * engine). Alias tokens are out of scope here.
8
+ */
9
+
10
+ import { basename, resolve } from "node:path";
11
+ import { resolveDeployAuth } from "./cli-deploy.js";
12
+ import {
13
+ DeployApiError,
14
+ type DeploymentDetail,
15
+ slugFromDirectoryName,
16
+ validateDeploymentSlug,
17
+ } from "./deploy-client.js";
18
+ import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
19
+ import { stderrPalette } from "./terminal-style.js";
20
+
21
+ /**
22
+ * Interactive CLI keep-alive for hosted engines. Without these, a hibernated
23
+ * Anyrun pod returns 417 `pod_hibernated` and never wakes. Matches the
24
+ * cloud-agent interactive keep-alive shape (lower ≤ upper, seconds).
25
+ */
26
+ export const PROD_ENGINE_WAKE_HEADERS: Readonly<Record<string, string>> = {
27
+ "x-anyrun-hibernation-lower-bound-s": "1800",
28
+ "x-anyrun-hibernation-upper-bound-s": "3600",
29
+ };
30
+
31
+ export interface ResolveProdTargetOptions {
32
+ dir: string;
33
+ cwd?: string;
34
+ /** Explicit deployment slug; otherwise derived from `--dir` basename. */
35
+ slug?: string;
36
+ team?: string;
37
+ apiKey?: string;
38
+ fetchImpl?: typeof fetch;
39
+ err?: (text: string) => void;
40
+ /** Test seam for reachability-retry backoff. */
41
+ sleep?: (ms: number) => Promise<void>;
42
+ }
43
+
44
+ export interface ResolvedProdTarget {
45
+ agentUrl: string;
46
+ headers: Record<string, string>;
47
+ slug: string;
48
+ expiresAt: string;
49
+ }
50
+
51
+ /**
52
+ * Look up a running deployment and return its engineAccess URL/headers.
53
+ * Throws {@link Error} with a CLI-ready message on failure.
54
+ */
55
+ export async function resolveProdTarget(
56
+ options: ResolveProdTargetOptions
57
+ ): Promise<ResolvedProdTarget> {
58
+ const err =
59
+ options.err ?? ((text: string) => void process.stderr.write(text));
60
+ const slug = resolveProdSlug(options);
61
+ const auth = await resolveDeployAuth({
62
+ team: options.team,
63
+ apiKey: options.apiKey,
64
+ fetchImpl: options.fetchImpl,
65
+ err,
66
+ });
67
+ if (typeof auth === "number") {
68
+ throw new Error(
69
+ `Could not resolve Cursor credentials/team for --prod (see above).`
70
+ );
71
+ }
72
+
73
+ // A hibernated engine can briefly omit engineAccess while getPod fails
74
+ // during wake. Retry a few times before surfacing "not reachable yet".
75
+ const maxReachabilityAttempts = 5;
76
+ const sleep = options.sleep ?? sleepMs;
77
+ let detail: DeploymentDetail | undefined;
78
+ for (let attempt = 0; attempt < maxReachabilityAttempts; attempt++) {
79
+ try {
80
+ detail = await auth.client.getDeployment({
81
+ teamId: auth.teamId,
82
+ slug,
83
+ });
84
+ } catch (error) {
85
+ if (error instanceof DeployApiError) {
86
+ throw new Error(
87
+ `Deployment "${slug}" (team ${auth.teamId}): ${error.message}`
88
+ );
89
+ }
90
+ throw error;
91
+ }
92
+
93
+ // `degraded` still serves the previous ACTIVE engine; allow runtime access
94
+ // when the control plane minted engineAccess for it.
95
+ const statusOk =
96
+ detail.status === "running" || detail.status === "degraded";
97
+ if (!statusOk) {
98
+ const lastError =
99
+ detail.lastError === null || detail.lastError === undefined
100
+ ? ""
101
+ : ` ${sanitizeCustomerFacingDetail(detail.lastError)}`;
102
+ throw new Error(
103
+ `Deployment "${slug}" is ${detail.status}, not running.${lastError}\n` +
104
+ `Deploy or wait: \`${CLI} deploy --slug ${slug}\` / \`${CLI} deployment ${slug}\``
105
+ );
106
+ }
107
+ if (detail.engineAccess !== null && detail.engineAccess !== undefined) {
108
+ break;
109
+ }
110
+ if (attempt + 1 < maxReachabilityAttempts) {
111
+ if (attempt === 0) {
112
+ err(
113
+ `${stderrPalette().dim(
114
+ `Deployment "${slug}" is waking; waiting for engine access…`
115
+ )}\n`
116
+ );
117
+ }
118
+ await sleep(1000 * (attempt + 1));
119
+ }
120
+ }
121
+
122
+ if (detail === undefined) {
123
+ throw new Error(`Deployment "${slug}" lookup failed.`);
124
+ }
125
+ const access = detail.engineAccess;
126
+ if (access === null || access === undefined) {
127
+ throw new Error(
128
+ `Deployment "${slug}" is ${detail.status} but is not reachable yet. ` +
129
+ `Try \`${CLI} deployment ${slug}\` or redeploy.`
130
+ );
131
+ }
132
+
133
+ err(`${stderrPalette().dim(`Using hosted deployment "${slug}".`)}\n`);
134
+
135
+ return {
136
+ agentUrl: access.url.replace(/\/$/, ""),
137
+ headers: {
138
+ ...access.headers,
139
+ ...PROD_ENGINE_WAKE_HEADERS,
140
+ },
141
+ slug,
142
+ expiresAt: access.expiresAt,
143
+ };
144
+ }
145
+
146
+ /** Strip obvious hosting internals from customer-facing error fragments. */
147
+ function sanitizeCustomerFacingDetail(message: string): string {
148
+ return message
149
+ .replace(/https?:\/\/\S+/gi, "[url]")
150
+ .replace(/\bpod-[a-z0-9]+\b/gi, "[runtime]")
151
+ .replace(/\banyrun\b/gi, "runtime")
152
+ .replace(/\bcursorvm\.com\b/gi, "host");
153
+ }
154
+
155
+ function sleepMs(ms: number): Promise<void> {
156
+ return new Promise((resolve) => {
157
+ setTimeout(resolve, ms);
158
+ });
159
+ }
160
+
161
+ /** Resolve the deployment slug the same way `deploy` does for a single dir. */
162
+ export function resolveProdSlug(options: {
163
+ dir: string;
164
+ cwd?: string;
165
+ slug?: string;
166
+ }): string {
167
+ if (options.slug !== undefined && options.slug !== "") {
168
+ const slugError = validateDeploymentSlug(options.slug);
169
+ if (slugError !== undefined) {
170
+ throw new Error(slugError);
171
+ }
172
+ return options.slug;
173
+ }
174
+ const dir = resolve(options.cwd ?? process.cwd(), options.dir);
175
+ const derived = slugFromDirectoryName(basename(dir));
176
+ if (derived === undefined) {
177
+ throw new Error(
178
+ `Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.`
179
+ );
180
+ }
181
+ return derived;
182
+ }
@@ -42,7 +42,7 @@ export function validateMountConnectionsConfig(args: {
42
42
  return;
43
43
  }
44
44
  throw new Error(
45
- `[agent-serve] agent "${label}" has Cursor account MCP connections with \`servers\` filters (${filteredRefs
45
+ `[agentkit] agent "${label}" has Cursor account MCP connections with \`servers\` filters (${filteredRefs
46
46
  .map((ref) => ref.name)
47
47
  .join(
48
48
  ", "
@@ -67,7 +67,7 @@ export function assertCloudCanHonorAccountServersFilters(args: {
67
67
  return;
68
68
  }
69
69
  throw new Error(
70
- `[agent-serve] cloud turn cannot honor Cursor account \`servers\` filters (${blocked
70
+ `[agentkit] cloud turn cannot honor Cursor account \`servers\` filters (${blocked
71
71
  .map((connection) => connection.name)
72
72
  .join(
73
73
  ", "
@@ -82,7 +82,7 @@ export function assertAccountConnectionsNotAnonymous(args: {
82
82
  }): void {
83
83
  if (args.allowAnonymous === true && args.hasAccountConnections) {
84
84
  throw new Error(
85
- "[agent-serve] --allow-anonymous cannot be used with Cursor account MCP connections (defineConnection({ cursorAccount: true })); use --bearer-token or remove the account MCP connections."
85
+ "[agentkit] --allow-anonymous cannot be used with Cursor account MCP connections (defineConnection({ cursorAccount: true })); use --bearer-token or remove the account MCP connections."
86
86
  );
87
87
  }
88
88
  }
@@ -113,7 +113,7 @@ export function resolveMountConnections(args: {
113
113
  resolved.push(...peers);
114
114
  if (cloudCapable && args.publicUrl === undefined) {
115
115
  args.logger(
116
- `[agent-serve] warning: agent "${label}" has peer MCP connections (${peers
116
+ `[agentkit] warning: agent "${label}" has peer MCP connections (${peers
117
117
  .map((peer) => peer.name)
118
118
  .join(
119
119
  ", "
@@ -136,7 +136,7 @@ export function resolveMountConnections(args: {
136
136
  args.accountBridge.logPreflight(args.accountRefs);
137
137
  if (cloudCapable && args.publicUrl === undefined) {
138
138
  args.logger(
139
- `[agent-serve] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`
139
+ `[agentkit] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`
140
140
  );
141
141
  }
142
142
  }
@@ -7,6 +7,7 @@
7
7
  */
8
8
 
9
9
  import type { SessionEvent, SessionPurpose } from "../types.js";
10
+ import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
10
11
  import { buildTrajectory, type Trajectory } from "./trajectory.js";
11
12
 
12
13
  /** Thrown when a turn stream exceeds `timeoutMs`; carries the session id. */
@@ -19,9 +20,8 @@ export class RunSessionTimeoutError extends Error {
19
20
  this.name = "RunSessionTimeoutError";
20
21
  }
21
22
  }
22
- export interface RunClientOptions {
23
+ export interface RunClientOptions extends RequestAuth {
23
24
  baseUrl: string;
24
- bearerToken?: string;
25
25
  /** Abort a hung turn. */
26
26
  timeoutMs?: number;
27
27
  /** Called for each stream event as it arrives (for CLI progress). */
@@ -72,6 +72,11 @@ export async function runSession(
72
72
  const allEvents: SessionEvent[] = [];
73
73
  let nextEventIndex = 0;
74
74
 
75
+ const auth: RequestAuth = {
76
+ bearerToken: options.bearerToken,
77
+ headers: options.headers,
78
+ };
79
+
75
80
  for (const message of options.messages) {
76
81
  const turn = await runOneTurn({
77
82
  baseUrl,
@@ -79,18 +84,13 @@ export async function runSession(
79
84
  sessionId,
80
85
  continuationToken,
81
86
  startIndex: sessionId === undefined ? 0 : nextEventIndex,
82
- bearerToken: options.bearerToken,
87
+ auth,
83
88
  timeoutMs: options.timeoutMs,
84
89
  onEvent: options.onEvent,
85
- ...(sessionId === undefined && options.purpose !== undefined
86
- ? { purpose: options.purpose }
87
- : {}),
88
- ...(sessionId === undefined && options.workspaceDir !== undefined
89
- ? { workspaceDir: options.workspaceDir }
90
- : {}),
91
- ...(sessionId === undefined && options.workspaceFiles !== undefined
92
- ? { workspaceFiles: options.workspaceFiles }
93
- : {}),
90
+ purpose: sessionId === undefined ? options.purpose : undefined,
91
+ workspaceDir: sessionId === undefined ? options.workspaceDir : undefined,
92
+ workspaceFiles:
93
+ sessionId === undefined ? options.workspaceFiles : undefined,
94
94
  });
95
95
  sessionId = turn.sessionId;
96
96
  continuationToken = turn.continuationToken;
@@ -128,7 +128,7 @@ interface OneTurnArgs {
128
128
  workspaceDir?: string;
129
129
  workspaceFiles?: Record<string, string>;
130
130
  startIndex: number;
131
- bearerToken?: string;
131
+ auth?: RequestAuth;
132
132
  timeoutMs?: number;
133
133
  onEvent?: (event: SessionEvent) => void;
134
134
  }
@@ -145,20 +145,21 @@ async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
145
145
  let continuationToken = args.continuationToken;
146
146
 
147
147
  if (sessionId === undefined) {
148
+ const body: Record<string, unknown> = { message: args.message };
149
+ if (args.purpose !== undefined) {
150
+ body.purpose = args.purpose;
151
+ }
152
+ if (args.workspaceDir !== undefined) {
153
+ body.workspaceDir = args.workspaceDir;
154
+ }
155
+ if (args.workspaceFiles !== undefined) {
156
+ body.workspaceFiles = args.workspaceFiles;
157
+ }
148
158
  const created = await postJson(
149
159
  args.baseUrl,
150
160
  "/v1/session",
151
- {
152
- message: args.message,
153
- ...(args.purpose === undefined ? {} : { purpose: args.purpose }),
154
- ...(args.workspaceDir === undefined
155
- ? {}
156
- : { workspaceDir: args.workspaceDir }),
157
- ...(args.workspaceFiles === undefined
158
- ? {}
159
- : { workspaceFiles: args.workspaceFiles }),
160
- },
161
- args.bearerToken
161
+ body,
162
+ args.auth
162
163
  );
163
164
  if (created.status >= 400 || created.body.ok === false) {
164
165
  throw new Error(
@@ -172,7 +173,7 @@ async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
172
173
  args.baseUrl,
173
174
  `/v1/session/${sessionId}`,
174
175
  { message: args.message, continuationToken },
175
- args.bearerToken
176
+ args.auth
176
177
  );
177
178
  if (resp.status >= 400 || resp.body.ok === false) {
178
179
  throw new Error(
@@ -190,7 +191,7 @@ async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
190
191
  baseUrl: args.baseUrl,
191
192
  sessionId,
192
193
  startIndex: args.startIndex,
193
- bearerToken: args.bearerToken,
194
+ auth: args.auth,
194
195
  timeoutMs: args.timeoutMs,
195
196
  onEvent: args.onEvent,
196
197
  });
@@ -209,7 +210,7 @@ async function collectStream(args: {
209
210
  baseUrl: string;
210
211
  sessionId: string;
211
212
  startIndex: number;
212
- bearerToken?: string;
213
+ auth?: RequestAuth;
213
214
  timeoutMs?: number;
214
215
  onEvent?: (event: SessionEvent) => void;
215
216
  }): Promise<SessionEvent[]> {
@@ -223,7 +224,7 @@ async function collectStream(args: {
223
224
  const resp = await fetch(
224
225
  `${args.baseUrl}/v1/session/${args.sessionId}/stream?startIndex=${args.startIndex}`,
225
226
  {
226
- headers: authHeaders(args.bearerToken),
227
+ headers: mergeRequestHeaders(args.auth),
227
228
  signal: controller.signal,
228
229
  }
229
230
  );
@@ -283,23 +284,17 @@ async function collectStream(args: {
283
284
  }
284
285
  }
285
286
 
286
- function authHeaders(bearerToken: string | undefined): Record<string, string> {
287
- return bearerToken === undefined
288
- ? {}
289
- : { authorization: `Bearer ${bearerToken}` };
290
- }
291
-
292
287
  async function postJson(
293
288
  baseUrl: string,
294
289
  path: string,
295
290
  body: unknown,
296
- bearerToken?: string
291
+ auth?: RequestAuth
297
292
  ): Promise<{ status: number; body: Record<string, unknown> }> {
298
293
  const resp = await fetch(`${baseUrl}${path}`, {
299
294
  method: "POST",
300
295
  headers: {
301
296
  "content-type": "application/json",
302
- ...authHeaders(bearerToken),
297
+ ...mergeRequestHeaders(auth),
303
298
  },
304
299
  body: JSON.stringify(body),
305
300
  });
@@ -312,6 +307,14 @@ async function postJson(
312
307
  parsed = { message: text };
313
308
  }
314
309
  }
310
+ const anyrunReason = resp.headers.get("x-anyrun-failure-reason");
311
+ if (
312
+ anyrunReason !== null &&
313
+ anyrunReason !== "" &&
314
+ (parsed.message === undefined || parsed.message === "")
315
+ ) {
316
+ parsed.message = anyrunReason;
317
+ }
315
318
  return { status: resp.status, body: parsed };
316
319
  }
317
320
 
@@ -90,7 +90,7 @@ export class ScheduleRunner {
90
90
  if (schedule.cron.matches(now)) {
91
91
  void this.dispatch(schedule.name).catch((error) => {
92
92
  this.logger(
93
- `[agent-serve] schedule "${schedule.name}" dispatch failed: ${
93
+ `[agentkit] schedule "${schedule.name}" dispatch failed: ${
94
94
  error instanceof Error ? error.message : String(error)
95
95
  }`
96
96
  );
@@ -50,6 +50,7 @@ import {
50
50
  import { CursorBackendClient } from "./cursor/backend-client.js";
51
51
  import {
52
52
  cursorBackendUrl,
53
+ cursorExternalApiUrl,
53
54
  type ResolvedApiKey,
54
55
  resolveApiKey,
55
56
  SIGN_IN_HINT,
@@ -227,13 +228,18 @@ export async function startServer(
227
228
  );
228
229
  }
229
230
  if (options.allowAnonymous === true) {
230
- throw new Error(
231
- "githubChannel({ cursorAccount: true }) cannot be served with --allow-anonymous because admitted callers could use the signed-in account's GitHub access."
231
+ if (options.allowAnonymousCursorGithub !== true) {
232
+ throw new Error(
233
+ "githubChannel({ cursorAccount: true }) cannot be served with --allow-anonymous because admitted callers could use the signed-in account's GitHub access. If every admitted caller is trusted (e.g. behind an SSO proxy), opt in with --allow-anonymous-cursor-github."
234
+ );
235
+ }
236
+ logger(
237
+ "[agentkit] warning: --allow-anonymous-cursor-github — every admitted HTTP caller can drive sessions holding the signed-in account's repo-scoped GitHub credential; serve this only behind a trusted boundary (e.g. an SSO proxy)"
232
238
  );
233
239
  }
234
240
  if (cursorGithubConfig.scope.permissions === "contents-write") {
235
241
  logger(
236
- '[agent-serve] warning: Cursor GitHub credentials include contents:write — the host holds a push-capable token shared with model-driven tools and untrusted webhook content; prefer permissions: "pr-write" unless this agent must push code'
242
+ '[agentkit] warning: Cursor GitHub credentials include contents:write — the host holds a push-capable token shared with model-driven tools and untrusted webhook content; prefer permissions: "pr-write" unless this agent must push code'
237
243
  );
238
244
  }
239
245
  const provider = new CursorGithubCredentialProvider({
@@ -275,7 +281,7 @@ export async function startServer(
275
281
  }
276
282
  if (options.allowAnonymous === true) {
277
283
  logger(
278
- "[agent-serve] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
284
+ "[agentkit] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
279
285
  );
280
286
  }
281
287
  const runner =
@@ -424,7 +430,7 @@ export async function startServer(
424
430
  await definition.onStart(startArgs);
425
431
  } catch (error) {
426
432
  logger(
427
- `[agent-serve] channel "${channel.id}" onStart failed: ${
433
+ `[agentkit] channel "${channel.id}" onStart failed: ${
428
434
  error instanceof Error
429
435
  ? (error.stack ?? error.message)
430
436
  : String(error)
@@ -738,7 +744,7 @@ export async function startServer(
738
744
  await stop();
739
745
  } catch (error) {
740
746
  logger(
741
- `[agent-serve] channel onStop failed: ${
747
+ `[agentkit] channel onStop failed: ${
742
748
  error instanceof Error
743
749
  ? (error.stack ?? error.message)
744
750
  : String(error)
@@ -1325,12 +1331,15 @@ function requireCursorEventsAuth(
1325
1331
  const apiKey = (config.apiKey ?? accountKey?.apiKey ?? "").trim();
1326
1332
  if (apiKey === "") {
1327
1333
  throw new Error(
1328
- `[agent-serve] --cursor-events (serve({ cursorEvents })) requires a signed-in Cursor account: the SCM event stream is read as the host's user. ${SIGN_IN_HINT}`
1334
+ `[agentkit] --cursor-events (serve({ cursorEvents })) requires a signed-in Cursor account: the SCM event stream is read as the host's user. ${SIGN_IN_HINT}`
1329
1335
  );
1330
1336
  }
1331
1337
  return {
1332
1338
  apiKey,
1333
- baseUrl: config.baseUrl ?? accountKey?.backendUrl ?? cursorBackendUrl(),
1339
+ // `/v0/scm-events/*` lives on the external API (api.cursor.com), not
1340
+ // api2. Prefer that default over the account key's backendUrl, which
1341
+ // follows cursorBackendUrl() (api2) when CURSOR_API_KEY is set.
1342
+ baseUrl: config.baseUrl ?? cursorExternalApiUrl(),
1334
1343
  };
1335
1344
  }
1336
1345
 
@@ -1358,7 +1367,7 @@ function startCursorEventRelay(input: {
1358
1367
  );
1359
1368
  if (repos.length === 0) {
1360
1369
  logger(
1361
- "[agent-serve] cursor-events: no repos configured (pass --repo owner/name); relay disabled"
1370
+ "[agentkit] cursor-events: no repos configured (pass --repo owner/name); relay disabled"
1362
1371
  );
1363
1372
  return undefined;
1364
1373
  }
@@ -1366,7 +1375,7 @@ function startCursorEventRelay(input: {
1366
1375
  const events = [...new Set(githubTargets.flatMap((target) => target.events))];
1367
1376
  if (events.length === 0) {
1368
1377
  logger(
1369
- "[agent-serve] cursor-events: no mounted agent declares a github channel; relay disabled"
1378
+ "[agentkit] cursor-events: no mounted agent declares a github channel; relay disabled"
1370
1379
  );
1371
1380
  return undefined;
1372
1381
  }
@@ -1410,13 +1419,13 @@ function startCursorEventRelay(input: {
1410
1419
  .map((target) => `${target.slug || "default"}:${target.status}`)
1411
1420
  .join(", ");
1412
1421
  logger(
1413
- `[agent-serve] cursor-events: dispatched ${formatCursorScmEventLog(event)}${outcomes === "" ? "" : ` → ${outcomes}`}`
1422
+ `[agentkit] cursor-events: dispatched ${formatCursorScmEventLog(event)}${outcomes === "" ? "" : ` → ${outcomes}`}`
1414
1423
  );
1415
1424
  },
1416
1425
  });
1417
1426
  relay.start();
1418
1427
  logger(
1419
- `[agent-serve] cursor-events: relaying ${events.length} event kind(s) for ${repos.join(", ")} from ${auth.baseUrl}`
1428
+ `[agentkit] cursor-events: relaying ${events.length} event kind(s) for ${repos.join(", ")} from ${auth.baseUrl}`
1420
1429
  );
1421
1430
  return relay;
1422
1431
  }
@@ -1602,7 +1611,7 @@ async function startCursorSlackRelay(input: {
1602
1611
  channelId: target.channelId,
1603
1612
  });
1604
1613
  logger(
1605
- `[agent-serve] cursor-slack: dispatching ${formatCursorSlackEventLog(envelope)} → ${target.runtime.slug || "default"}`
1614
+ `[agentkit] cursor-slack: dispatching ${formatCursorSlackEventLog(envelope)} → ${target.runtime.slug || "default"}`
1606
1615
  );
1607
1616
  await dispatchCursorSlackEnvelope({
1608
1617
  runtime: target.accountRuntime,
@@ -1630,7 +1639,7 @@ async function startCursorSlackRelay(input: {
1630
1639
 
1631
1640
  relay.start();
1632
1641
  logger(
1633
- `[agent-serve] cursor-slack: relaying Slack for ${targets
1642
+ `[agentkit] cursor-slack: relaying Slack for ${targets
1634
1643
  .map(
1635
1644
  (target) => `${target.agentName} (${target.runtime.slug || "default"})`
1636
1645
  )
@@ -1726,7 +1735,7 @@ async function handleRequest(
1726
1735
  response = errorResponse(403, "forbidden", error.message);
1727
1736
  } else {
1728
1737
  logger(
1729
- `[agent-serve] request failed: ${
1738
+ `[agentkit] request failed: ${
1730
1739
  error instanceof Error
1731
1740
  ? (error.stack ?? error.message)
1732
1741
  : String(error)
@@ -1740,7 +1749,7 @@ async function handleRequest(
1740
1749
  await writeFetchResponse(response, res, method);
1741
1750
  } catch (error) {
1742
1751
  logger(
1743
- `[agent-serve] response write failed: ${
1752
+ `[agentkit] response write failed: ${
1744
1753
  error instanceof Error ? error.message : String(error)
1745
1754
  }`
1746
1755
  );