@cursor/july 0.1.15 → 0.1.17

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 (243) hide show
  1. package/README.md +9 -4
  2. package/dist/bin/agent-serve.js +60 -2
  3. package/dist/channels/slack/api.d.ts.map +1 -1
  4. package/dist/channels/slack/api.js +13 -3
  5. package/dist/channels/slack/auth.d.ts +7 -1
  6. package/dist/channels/slack/auth.d.ts.map +1 -1
  7. package/dist/channels/slack/auth.js +14 -0
  8. package/dist/channels/slack/blocks.d.ts +61 -0
  9. package/dist/channels/slack/blocks.d.ts.map +1 -0
  10. package/dist/channels/slack/blocks.js +90 -0
  11. package/dist/channels/slack/defaults.d.ts +2 -0
  12. package/dist/channels/slack/defaults.d.ts.map +1 -1
  13. package/dist/channels/slack/defaults.js +29 -3
  14. package/dist/channels/slack/dispatch.d.ts +3 -17
  15. package/dist/channels/slack/dispatch.d.ts.map +1 -1
  16. package/dist/channels/slack/index.d.ts +1 -0
  17. package/dist/channels/slack/index.d.ts.map +1 -1
  18. package/dist/channels/slack/index.js +1 -0
  19. package/dist/channels/slack/interactive.d.ts +39 -3
  20. package/dist/channels/slack/interactive.d.ts.map +1 -1
  21. package/dist/channels/slack/interactive.js +152 -7
  22. package/dist/channels/slack/manifest.d.ts +3 -0
  23. package/dist/channels/slack/manifest.d.ts.map +1 -1
  24. package/dist/channels/slack/manifest.js +3 -0
  25. package/dist/channels/slack/setup.d.ts +4 -1
  26. package/dist/channels/slack/setup.d.ts.map +1 -1
  27. package/dist/channels/slack/setup.js +16 -2
  28. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  29. package/dist/channels/slack/slack-channel.js +24 -3
  30. package/dist/channels/slack/types.d.ts +77 -0
  31. package/dist/channels/slack/types.d.ts.map +1 -1
  32. package/dist/connections.d.ts +4 -1
  33. package/dist/connections.d.ts.map +1 -1
  34. package/dist/connections.js +4 -1
  35. package/dist/docs/404.html +2 -2
  36. package/dist/docs/ab.html +3 -3
  37. package/dist/docs/assets/{app.DpdGZTLe.js → app.BbEXr2KO.js} +1 -1
  38. package/dist/docs/assets/chunks/@localSearchIndexroot.DCBsrfwP.js +1 -0
  39. package/dist/docs/assets/chunks/{VPLocalSearchBox.IB-0QqIT.js → VPLocalSearchBox.DBEi4HDp.js} +1 -1
  40. package/dist/docs/assets/chunks/{theme.-fYBoNtR.js → theme.DGfptcHw.js} +2 -2
  41. package/dist/docs/assets/{example-agents_index.md.BPXjUtRB.js → example-agents_index.md.D2PEVSXl.js} +2 -2
  42. package/dist/docs/assets/{example-agents_index.md.BPXjUtRB.lean.js → example-agents_index.md.D2PEVSXl.lean.js} +1 -1
  43. package/dist/docs/assets/example-agents_security-reviewer.md.BZSNycMf.js +19 -0
  44. package/dist/docs/assets/{example-agents_security-reviewer.md.CE9v-aKm.lean.js → example-agents_security-reviewer.md.BZSNycMf.lean.js} +1 -1
  45. package/dist/docs/assets/{guides_mcp-oauth.md.DqmEOQY1.js → guides_mcp-oauth.md.Dd8EgSem.js} +3 -2
  46. package/dist/docs/assets/{guides_mcp-oauth.md.DqmEOQY1.lean.js → guides_mcp-oauth.md.Dd8EgSem.lean.js} +1 -1
  47. package/dist/docs/assets/{guides_slack.md.FWale6Ip.js → guides_slack.md.D_xFKlnF.js} +1 -1
  48. package/dist/docs/assets/{reference_connections.md.CsSr3rDz.js → reference_connections.md.B9Q3TOve.js} +12 -5
  49. package/dist/docs/assets/{reference_connections.md.CsSr3rDz.lean.js → reference_connections.md.B9Q3TOve.lean.js} +1 -1
  50. package/dist/docs/building-with-agents.html +3 -3
  51. package/dist/docs/concepts.html +3 -3
  52. package/dist/docs/deployment.html +3 -3
  53. package/dist/docs/evals.html +3 -3
  54. package/dist/docs/example-agents/approval-buddy.html +3 -3
  55. package/dist/docs/example-agents/benny.html +3 -3
  56. package/dist/docs/example-agents/bugbot.html +3 -3
  57. package/dist/docs/example-agents/codebase-wiki.html +3 -3
  58. package/dist/docs/example-agents/codeowners-review.html +3 -3
  59. package/dist/docs/example-agents/concierge.html +3 -3
  60. package/dist/docs/example-agents/fsd.html +3 -3
  61. package/dist/docs/example-agents/index.html +5 -5
  62. package/dist/docs/example-agents/knowledge-base.html +3 -3
  63. package/dist/docs/example-agents/oncall.html +3 -3
  64. package/dist/docs/example-agents/security-reviewer.html +14 -14
  65. package/dist/docs/example-agents/slack-agent.html +3 -3
  66. package/dist/docs/example-agents/weather-agent.html +3 -3
  67. package/dist/docs/guides/agent-to-agent.html +3 -3
  68. package/dist/docs/guides/cloud-runtime.html +3 -3
  69. package/dist/docs/guides/github.html +3 -3
  70. package/dist/docs/guides/human-in-the-loop.html +3 -3
  71. package/dist/docs/guides/mcp-oauth.html +6 -5
  72. package/dist/docs/guides/slack.html +5 -5
  73. package/dist/docs/guides/webhooks.html +3 -3
  74. package/dist/docs/hashmap.json +1 -1
  75. package/dist/docs/hillclimbing.html +3 -3
  76. package/dist/docs/index.html +3 -3
  77. package/dist/docs/quickstart.html +3 -3
  78. package/dist/docs/reference/agent-config.html +3 -3
  79. package/dist/docs/reference/channels.html +3 -3
  80. package/dist/docs/reference/cli.html +3 -3
  81. package/dist/docs/reference/connections.html +14 -7
  82. package/dist/docs/reference/hooks.html +3 -3
  83. package/dist/docs/reference/http-api.html +3 -3
  84. package/dist/docs/reference/instructions.html +3 -3
  85. package/dist/docs/reference/playground.html +3 -3
  86. package/dist/docs/reference/project-layout.html +3 -3
  87. package/dist/docs/reference/prompt.html +3 -3
  88. package/dist/docs/reference/schedules.html +3 -3
  89. package/dist/docs/reference/sessions.html +3 -3
  90. package/dist/docs/reference/skills.html +3 -3
  91. package/dist/docs/reference/subagents.html +3 -3
  92. package/dist/docs/reference/tools.html +3 -3
  93. package/dist/docs/scaffolding-agents.html +3 -3
  94. package/dist/docs/storage.html +3 -3
  95. package/dist/docs/troubleshooting.html +3 -3
  96. package/dist/evals/assertions.d.ts +190 -0
  97. package/dist/evals/assertions.d.ts.map +1 -0
  98. package/dist/evals/assertions.js +461 -0
  99. package/dist/evals/expect.d.ts +95 -0
  100. package/dist/evals/expect.d.ts.map +1 -0
  101. package/dist/evals/expect.js +194 -0
  102. package/dist/evals/judge.d.ts +133 -0
  103. package/dist/evals/judge.d.ts.map +1 -0
  104. package/dist/evals/judge.js +228 -0
  105. package/dist/evals/loaders.d.ts +51 -0
  106. package/dist/evals/loaders.d.ts.map +1 -0
  107. package/dist/evals/loaders.js +124 -0
  108. package/dist/evals/matchers.d.ts +95 -0
  109. package/dist/evals/matchers.d.ts.map +1 -0
  110. package/dist/evals/matchers.js +145 -0
  111. package/dist/evals/reporters.d.ts +70 -0
  112. package/dist/evals/reporters.d.ts.map +1 -0
  113. package/dist/evals/reporters.js +221 -0
  114. package/dist/evals/results.d.ts +103 -0
  115. package/dist/evals/results.d.ts.map +1 -0
  116. package/dist/evals/results.js +28 -0
  117. package/dist/evals/run-facts.d.ts +77 -0
  118. package/dist/evals/run-facts.d.ts.map +1 -0
  119. package/dist/evals/run-facts.js +187 -0
  120. package/dist/evals.d.ts +136 -31
  121. package/dist/evals.d.ts.map +1 -1
  122. package/dist/evals.js +76 -12
  123. package/dist/index.d.ts +1 -1
  124. package/dist/index.d.ts.map +1 -1
  125. package/dist/index.js +1 -1
  126. package/dist/internal/cli-ax.d.ts +27 -0
  127. package/dist/internal/cli-ax.d.ts.map +1 -1
  128. package/dist/internal/cli-ax.js +90 -12
  129. package/dist/internal/cli-mcp.d.ts +8 -0
  130. package/dist/internal/cli-mcp.d.ts.map +1 -1
  131. package/dist/internal/cli-mcp.js +98 -0
  132. package/dist/internal/cli-slack.d.ts +29 -1
  133. package/dist/internal/cli-slack.d.ts.map +1 -1
  134. package/dist/internal/cli-slack.js +777 -12
  135. package/dist/internal/deploy-client.d.ts +7 -0
  136. package/dist/internal/deploy-client.d.ts.map +1 -1
  137. package/dist/internal/deploy-client.js +9 -0
  138. package/dist/internal/discovery.d.ts.map +1 -1
  139. package/dist/internal/discovery.js +29 -9
  140. package/dist/internal/distribution.d.ts.map +1 -1
  141. package/dist/internal/distribution.js +2 -0
  142. package/dist/internal/eval-judge-model.d.ts +59 -0
  143. package/dist/internal/eval-judge-model.d.ts.map +1 -0
  144. package/dist/internal/eval-judge-model.js +131 -0
  145. package/dist/internal/eval-run-store.d.ts.map +1 -1
  146. package/dist/internal/eval-run-store.js +12 -20
  147. package/dist/internal/eval-runner.d.ts +31 -25
  148. package/dist/internal/eval-runner.d.ts.map +1 -1
  149. package/dist/internal/eval-runner.js +332 -128
  150. package/dist/internal/evals-client.d.ts.map +1 -1
  151. package/dist/internal/evals-client.js +7 -3
  152. package/dist/internal/local-env.d.ts +8 -0
  153. package/dist/internal/local-env.d.ts.map +1 -0
  154. package/dist/internal/local-env.js +47 -0
  155. package/dist/internal/playground/static.d.ts +3 -0
  156. package/dist/internal/playground/static.d.ts.map +1 -1
  157. package/dist/internal/playground/static.js +3 -0
  158. package/dist/internal/run-client.d.ts +15 -0
  159. package/dist/internal/run-client.d.ts.map +1 -1
  160. package/dist/internal/run-client.js +3 -2
  161. package/dist/internal/sdk-runner.d.ts +36 -1
  162. package/dist/internal/sdk-runner.d.ts.map +1 -1
  163. package/dist/internal/sdk-runner.js +65 -25
  164. package/dist/internal/server.d.ts.map +1 -1
  165. package/dist/internal/server.js +10 -1
  166. package/dist/internal/session-engine.d.ts +18 -5
  167. package/dist/internal/session-engine.d.ts.map +1 -1
  168. package/dist/internal/session-engine.js +72 -19
  169. package/dist/internal/slack-provision-client.d.ts +130 -0
  170. package/dist/internal/slack-provision-client.d.ts.map +1 -0
  171. package/dist/internal/slack-provision-client.js +284 -0
  172. package/dist/playground/assets/cursor-icons-16-f_W_ogc-.woff2 +0 -0
  173. package/dist/playground/assets/index-CidizGZv.css +1 -0
  174. package/dist/playground/assets/index-DNqirsrK.js +85 -0
  175. package/dist/playground/index.html +2 -2
  176. package/dist/types.d.ts +70 -4
  177. package/dist/types.d.ts.map +1 -1
  178. package/dist/types.js +26 -0
  179. package/docs/example-agents/index.md +1 -1
  180. package/docs/example-agents/security-reviewer.md +23 -21
  181. package/docs/guides/mcp-oauth.md +10 -5
  182. package/docs/guides/slack.md +3 -2
  183. package/docs/reference/connections.md +28 -18
  184. package/package.json +20 -2
  185. package/skills/create-agent/SKILL.md +15 -7
  186. package/skills/debug/SKILL.md +3 -1
  187. package/skills/mcp-auth/SKILL.md +1 -1
  188. package/skills/setup-slack/SKILL.md +173 -11
  189. package/src/bin/agent-serve.ts +63 -2
  190. package/src/channels/slack/api.ts +16 -3
  191. package/src/channels/slack/auth.ts +16 -1
  192. package/src/channels/slack/blocks.ts +139 -0
  193. package/src/channels/slack/defaults.ts +32 -4
  194. package/src/channels/slack/dispatch.ts +3 -18
  195. package/src/channels/slack/index.ts +1 -0
  196. package/src/channels/slack/interactive.ts +183 -19
  197. package/src/channels/slack/manifest.ts +3 -0
  198. package/src/channels/slack/setup.ts +16 -2
  199. package/src/channels/slack/slack-channel.ts +37 -6
  200. package/src/channels/slack/types.ts +89 -0
  201. package/src/connections.ts +4 -1
  202. package/src/evals/assertions.ts +704 -0
  203. package/src/evals/expect.ts +272 -0
  204. package/src/evals/judge.ts +346 -0
  205. package/src/evals/loaders.ts +113 -0
  206. package/src/evals/matchers.ts +246 -0
  207. package/src/evals/reporters.ts +274 -0
  208. package/src/evals/results.ts +132 -0
  209. package/src/evals/run-facts.ts +274 -0
  210. package/src/evals.ts +249 -42
  211. package/src/index.ts +2 -0
  212. package/src/internal/cli-ax.ts +134 -15
  213. package/src/internal/cli-mcp.ts +118 -5
  214. package/src/internal/cli-slack.ts +993 -15
  215. package/src/internal/deploy-client.ts +10 -0
  216. package/src/internal/discovery.ts +31 -5
  217. package/src/internal/distribution.ts +2 -0
  218. package/src/internal/eval-judge-model.ts +148 -0
  219. package/src/internal/eval-run-store.ts +10 -14
  220. package/src/internal/eval-runner.ts +466 -215
  221. package/src/internal/evals-client.ts +14 -2
  222. package/src/internal/local-env.ts +53 -0
  223. package/src/internal/playground/static.ts +3 -0
  224. package/src/internal/run-client.ts +17 -1
  225. package/src/internal/sdk-runner.ts +103 -22
  226. package/src/internal/server.ts +10 -0
  227. package/src/internal/session-engine.ts +89 -21
  228. package/src/internal/slack-provision-client.ts +438 -0
  229. package/src/types.ts +92 -4
  230. package/dist/channels/slack/post-update-delivery.d.ts +0 -85
  231. package/dist/channels/slack/post-update-delivery.d.ts.map +0 -1
  232. package/dist/docs/assets/chunks/@localSearchIndexroot.D2d8CfFS.js +0 -1
  233. package/dist/docs/assets/example-agents_security-reviewer.md.CE9v-aKm.js +0 -19
  234. package/dist/internal/json-dir-store.d.ts +0 -32
  235. package/dist/internal/json-dir-store.d.ts.map +0 -1
  236. package/dist/internal/persistence-coordinator.d.ts +0 -127
  237. package/dist/internal/persistence-coordinator.d.ts.map +0 -1
  238. package/dist/persistence.d.ts +0 -184
  239. package/dist/persistence.d.ts.map +0 -1
  240. package/dist/playground/assets/cursor-icons-16-CQ50JpfO.woff2 +0 -0
  241. package/dist/playground/assets/index-BVMOoiek.js +0 -86
  242. package/dist/playground/assets/index-DYmP4b--.css +0 -1
  243. /package/dist/docs/assets/{guides_slack.md.FWale6Ip.lean.js → guides_slack.md.D_xFKlnF.lean.js} +0 -0
@@ -0,0 +1,438 @@
1
+ /**
2
+ * Thin client for the Agent Serve Slack provisioning API
3
+ * (`/internal/agent-serve/slack` on the Cursor backend — "Add to Slack").
4
+ * Pure request/response + error mapping — no console I/O, no polling
5
+ * loops; rendering lives in `cli-slack.ts`.
6
+ *
7
+ * Auth is the user API key sent directly as the bearer (the routes are
8
+ * `wrapUserApiRoute` on the backend); there is no token exchange here.
9
+ * The endpoints are gated on the `agent_serve_slack_provisioning` Statsig
10
+ * gate and 404 when it is off — the error mapping says so instead of
11
+ * "not found". Expected provisioning failures carry a stable JSON `code`
12
+ * (`not_connected`, `insufficient_scopes`, `app_conflict`,
13
+ * `app_cap_reached`, `ratelimited`, `invalid_app_id`, …) which flows
14
+ * through on {@link SlackProvisionApiError.code} so the CLI can branch.
15
+ */
16
+
17
+ import { z } from "zod";
18
+
19
+ export type SlackAppEnv = "dev" | "prod";
20
+
21
+ /** One manager-connected Slack workspace from `GET /status`. */
22
+ export interface SlackConnectedWorkspace {
23
+ slackTeamId: string;
24
+ slackUserId: string;
25
+ connectedAt: string;
26
+ }
27
+
28
+ /** One provisioned managed Slack app from `GET /status` (no token material). */
29
+ export interface SlackManagedAppInfo {
30
+ slackAppId: string;
31
+ slackTeamId: string;
32
+ slug: string;
33
+ env: string;
34
+ installStatus: string;
35
+ createdAt: string;
36
+ updatedAt: string;
37
+ }
38
+
39
+ export interface SlackProvisionStatus {
40
+ workspaces: SlackConnectedWorkspace[];
41
+ apps: SlackManagedAppInfo[];
42
+ }
43
+
44
+ export type SlackAppIconContentType = "image/png" | "image/jpeg" | "image/gif";
45
+
46
+ /** Icon source for `setAppIcon`: an https image URL or a base64 file. */
47
+ export type SlackAppIconInput =
48
+ | { url: string }
49
+ | { base64: string; contentType: SlackAppIconContentType };
50
+
51
+ /**
52
+ * Outcome of `POST /apps`. Credentials are returned exactly once and never
53
+ * persisted server-side — the caller owns storing them. `appToken` can be
54
+ * absent when Slack's install response omitted the app-level token.
55
+ * `oauthAuthorizeUrl` is only minted on a fresh app create, so an update
56
+ * that lands in admin approval omits it.
57
+ */
58
+ export type SlackAppProvisionResult =
59
+ | {
60
+ status: "installed";
61
+ appId: string;
62
+ botToken: string;
63
+ appToken?: string;
64
+ /** Present when the provision requested an icon (best-effort outcome). */
65
+ iconStatus?: "set" | "failed";
66
+ }
67
+ | {
68
+ status: "pending_admin_approval";
69
+ appId: string;
70
+ oauthAuthorizeUrl?: string;
71
+ iconStatus?: "set" | "failed";
72
+ };
73
+
74
+ export class SlackProvisionApiError extends Error {
75
+ readonly status: number;
76
+ /** Stable backend error code (`not_connected`, `ratelimited`, …). */
77
+ readonly code?: string;
78
+ /** Seconds to wait before retrying (from 429 responses). */
79
+ readonly retryAfterSeconds?: number;
80
+ /** Drifted manifest paths (from `manifest_drift` 409 bodies). */
81
+ readonly changedPaths?: string[];
82
+
83
+ constructor(
84
+ message: string,
85
+ options: {
86
+ status: number;
87
+ code?: string;
88
+ retryAfterSeconds?: number;
89
+ changedPaths?: string[];
90
+ }
91
+ ) {
92
+ super(message);
93
+ this.name = "SlackProvisionApiError";
94
+ this.status = options.status;
95
+ this.code = options.code;
96
+ this.retryAfterSeconds = options.retryAfterSeconds;
97
+ this.changedPaths = options.changedPaths;
98
+ }
99
+ }
100
+
101
+ // ============================================================================
102
+ // Response shapes (backend agentServeSlackEndpoints route bodies).
103
+ // Interfaces are hand-written (the package compiles with
104
+ // --isolatedDeclarations, so exported types cannot be z.infer of an
105
+ // unannotated schema); the zod schemas below stay module-internal.
106
+ // ============================================================================
107
+
108
+ // All response schemas are `.passthrough()` so unknown fields from a newer
109
+ // backend flow through untouched instead of breaking the parse.
110
+ const statusResponseSchema = z
111
+ .object({
112
+ workspaces: z.array(
113
+ z
114
+ .object({
115
+ slackTeamId: z.string(),
116
+ slackUserId: z.string(),
117
+ connectedAt: z.string(),
118
+ })
119
+ .passthrough()
120
+ ),
121
+ apps: z.array(
122
+ z
123
+ .object({
124
+ slackAppId: z.string(),
125
+ slackTeamId: z.string(),
126
+ slug: z.string(),
127
+ env: z.string(),
128
+ installStatus: z.string(),
129
+ createdAt: z.string(),
130
+ updatedAt: z.string(),
131
+ })
132
+ .passthrough()
133
+ ),
134
+ })
135
+ .passthrough();
136
+
137
+ const connectResponseSchema = z
138
+ .object({
139
+ url: z.string().min(1),
140
+ })
141
+ .passthrough();
142
+
143
+ const provisionResponseSchema = z.discriminatedUnion("status", [
144
+ z
145
+ .object({
146
+ status: z.literal("installed"),
147
+ appId: z.string(),
148
+ botToken: z.string(),
149
+ appToken: z.string().optional(),
150
+ iconStatus: z.enum(["set", "failed"]).optional(),
151
+ })
152
+ .passthrough(),
153
+ z
154
+ .object({
155
+ status: z.literal("pending_admin_approval"),
156
+ appId: z.string(),
157
+ oauthAuthorizeUrl: z.string().optional(),
158
+ iconStatus: z.enum(["set", "failed"]).optional(),
159
+ })
160
+ .passthrough(),
161
+ ]);
162
+
163
+ const deleteResponseSchema = z
164
+ .object({
165
+ deleted: z.boolean(),
166
+ })
167
+ .passthrough();
168
+
169
+ const setIconResponseSchema = z
170
+ .object({
171
+ ok: z.boolean(),
172
+ })
173
+ .passthrough();
174
+
175
+ // ============================================================================
176
+ // Client
177
+ // ============================================================================
178
+
179
+ export interface AgentServeSlackClientOptions {
180
+ backendUrl: string;
181
+ apiKey: string;
182
+ /** Test seam; defaults to global fetch. */
183
+ fetchImpl?: typeof fetch;
184
+ }
185
+
186
+ export class AgentServeSlackClient {
187
+ private readonly backendUrl: string;
188
+ private readonly apiKey: string;
189
+ private readonly fetchImpl: typeof fetch;
190
+
191
+ constructor(options: AgentServeSlackClientOptions) {
192
+ this.backendUrl = options.backendUrl.endsWith("/")
193
+ ? options.backendUrl.slice(0, -1)
194
+ : options.backendUrl;
195
+ this.apiKey = options.apiKey;
196
+ this.fetchImpl = options.fetchImpl ?? fetch;
197
+ }
198
+
199
+ /** Manager-connected workspaces + the managed-app inventory. */
200
+ async status(teamId: number): Promise<SlackProvisionStatus> {
201
+ const raw = await this.request({
202
+ method: "GET",
203
+ path: `/internal/agent-serve/slack/status?teamId=${teamId}`,
204
+ context: { verb: "read Slack provisioning status" },
205
+ });
206
+ return statusResponseSchema.parse(raw);
207
+ }
208
+
209
+ /**
210
+ * Mint the browser consent URL for the Slack manager grant. After the
211
+ * user approves it, the workspace shows up in {@link status}.
212
+ */
213
+ async connect(teamId: number): Promise<string> {
214
+ const raw = await this.request({
215
+ method: "POST",
216
+ path: "/internal/agent-serve/slack/connect",
217
+ body: { teamId },
218
+ context: { verb: "start the Slack workspace connect" },
219
+ });
220
+ return connectResponseSchema.parse(raw).url;
221
+ }
222
+
223
+ /**
224
+ * Provision (create or update) and install one managed Slack app for
225
+ * (slackTeamId, slug, env). Expected failures throw
226
+ * {@link SlackProvisionApiError} with a stable `code`.
227
+ */
228
+ async provisionApp(args: {
229
+ teamId: number;
230
+ slackTeamId: string;
231
+ slug: string;
232
+ env: SlackAppEnv;
233
+ /** Full Slack app manifest JSON string. */
234
+ manifest: string;
235
+ /** Icon URL, applied best-effort by the backend after the install. */
236
+ icon?: { url: string };
237
+ /** Overwrite manifest edits made in Slack (skips the drift check). */
238
+ force?: boolean;
239
+ }): Promise<SlackAppProvisionResult> {
240
+ const raw = await this.request({
241
+ method: "POST",
242
+ path: "/internal/agent-serve/slack/apps",
243
+ body: {
244
+ teamId: args.teamId,
245
+ slackTeamId: args.slackTeamId,
246
+ slug: args.slug,
247
+ env: args.env,
248
+ manifest: args.manifest,
249
+ icon: args.icon,
250
+ force: args.force,
251
+ },
252
+ context: { verb: "provision the Slack app" },
253
+ });
254
+ return provisionResponseSchema.parse(raw);
255
+ }
256
+
257
+ /** Delete the Slack app and its inventory row. */
258
+ async deleteApp(args: { teamId: number; slackAppId: string }): Promise<void> {
259
+ const raw = await this.request({
260
+ method: "DELETE",
261
+ path: `/internal/agent-serve/slack/apps/${encodeURIComponent(args.slackAppId)}?teamId=${args.teamId}`,
262
+ context: { verb: "delete the Slack app" },
263
+ });
264
+ deleteResponseSchema.parse(raw);
265
+ }
266
+
267
+ /** Set the app's icon: an https image URL or a base64 png/jpeg/gif ≤512KB. */
268
+ async setAppIcon(args: {
269
+ teamId: number;
270
+ slackAppId: string;
271
+ icon: SlackAppIconInput;
272
+ }): Promise<void> {
273
+ const raw = await this.request({
274
+ method: "POST",
275
+ path: `/internal/agent-serve/slack/apps/${encodeURIComponent(args.slackAppId)}/icon`,
276
+ body: { teamId: args.teamId, icon: args.icon },
277
+ context: { verb: "set the Slack app icon" },
278
+ });
279
+ setIconResponseSchema.parse(raw);
280
+ }
281
+
282
+ private async request(args: {
283
+ method: "GET" | "POST" | "DELETE";
284
+ path: string;
285
+ body?: unknown;
286
+ context: { verb: string };
287
+ }): Promise<unknown> {
288
+ const headers: Record<string, string> = {
289
+ accept: "application/json",
290
+ authorization: `Bearer ${this.apiKey}`,
291
+ };
292
+ if (args.body !== undefined) {
293
+ headers["content-type"] = "application/json";
294
+ }
295
+ let response: Response;
296
+ try {
297
+ response = await this.fetchImpl(`${this.backendUrl}${args.path}`, {
298
+ method: args.method,
299
+ headers,
300
+ body: args.body === undefined ? undefined : JSON.stringify(args.body),
301
+ signal: AbortSignal.timeout(60_000),
302
+ });
303
+ } catch (error) {
304
+ throw new SlackProvisionApiError(
305
+ `Could not reach the Cursor backend at ${this.backendUrl}: ${
306
+ error instanceof Error ? error.message : String(error)
307
+ }`,
308
+ { status: 0 }
309
+ );
310
+ }
311
+ const text = await response.text();
312
+ if (!response.ok) {
313
+ throw mapErrorResponse(response, text, args.context);
314
+ }
315
+ try {
316
+ return JSON.parse(text) as unknown;
317
+ } catch {
318
+ throw new SlackProvisionApiError(
319
+ `The Cursor backend returned a non-JSON response to ${args.context.verb}.`,
320
+ { status: response.status }
321
+ );
322
+ }
323
+ }
324
+ }
325
+
326
+ // ============================================================================
327
+ // Error mapping (HTTP → actionable human messages, stable codes kept)
328
+ // ============================================================================
329
+
330
+ function parseErrorBody(bodyText: string): {
331
+ error?: string;
332
+ code?: string;
333
+ retryAfterSeconds?: number;
334
+ changedPaths?: string[];
335
+ } {
336
+ let parsed: {
337
+ error?: unknown;
338
+ code?: unknown;
339
+ retryAfterSeconds?: unknown;
340
+ changedPaths?: unknown;
341
+ };
342
+ try {
343
+ parsed = JSON.parse(bodyText) as typeof parsed;
344
+ } catch {
345
+ return {};
346
+ }
347
+ return {
348
+ error:
349
+ typeof parsed.error === "string" && parsed.error !== ""
350
+ ? parsed.error
351
+ : undefined,
352
+ code:
353
+ typeof parsed.code === "string" && parsed.code !== ""
354
+ ? parsed.code
355
+ : undefined,
356
+ retryAfterSeconds:
357
+ typeof parsed.retryAfterSeconds === "number"
358
+ ? parsed.retryAfterSeconds
359
+ : undefined,
360
+ changedPaths:
361
+ Array.isArray(parsed.changedPaths) &&
362
+ parsed.changedPaths.every(
363
+ (path): path is string => typeof path === "string"
364
+ )
365
+ ? parsed.changedPaths
366
+ : undefined,
367
+ };
368
+ }
369
+
370
+ function mapErrorResponse(
371
+ response: Response,
372
+ bodyText: string,
373
+ context: { verb: string }
374
+ ): SlackProvisionApiError {
375
+ const body = parseErrorBody(bodyText);
376
+ const serverError = body.error;
377
+ switch (response.status) {
378
+ case 401:
379
+ return new SlackProvisionApiError(
380
+ "The Cursor API key was rejected. Run `agentkit login` again or update CURSOR_API_KEY.",
381
+ { status: 401 }
382
+ );
383
+ case 403:
384
+ return new SlackProvisionApiError(
385
+ `${serverError ?? "Not authorized"} — Slack provisioning needs team-admin permission and the cloud-agent entitlement on that team.`,
386
+ { status: 403 }
387
+ );
388
+ case 404: {
389
+ // Fastify's route-not-found envelope means we hit the wrong host
390
+ // (api2 vs api.cursor.com), not a closed gate.
391
+ if (/Route \S+ not found/i.test(bodyText)) {
392
+ return new SlackProvisionApiError(
393
+ `Agent Serve Slack API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
394
+ { status: 404 }
395
+ );
396
+ }
397
+ // The gate-off body is exactly {error: "Not found"}; anything else
398
+ // (e.g. "App not found" on delete) is a real not-found to surface.
399
+ if (serverError !== undefined && serverError !== "Not found") {
400
+ return new SlackProvisionApiError(serverError, {
401
+ status: 404,
402
+ code: body.code,
403
+ });
404
+ }
405
+ return new SlackProvisionApiError(
406
+ `Not found — Cursor's "Add to Slack" provisioning (the agent_serve_slack_provisioning feature gate) is not enabled for this account yet.`,
407
+ { status: 404 }
408
+ );
409
+ }
410
+ case 429: {
411
+ const retryAfterHeader = response.headers.get("retry-after");
412
+ const retryAfterSeconds =
413
+ retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader)
414
+ ? Number(retryAfterHeader)
415
+ : body.retryAfterSeconds;
416
+ return new SlackProvisionApiError(
417
+ `${serverError ?? "Rate limited"}${
418
+ retryAfterSeconds === undefined
419
+ ? ""
420
+ : ` — retry in ${retryAfterSeconds}s`
421
+ }`,
422
+ { status: 429, code: body.code ?? "ratelimited", retryAfterSeconds }
423
+ );
424
+ }
425
+ default:
426
+ return new SlackProvisionApiError(
427
+ serverError ??
428
+ `The ${context.verb} request failed (${response.status}): ${
429
+ bodyText.slice(0, 300) || "(empty body)"
430
+ }`,
431
+ {
432
+ status: response.status,
433
+ code: body.code,
434
+ changedPaths: body.changedPaths,
435
+ }
436
+ );
437
+ }
438
+ }
package/src/types.ts CHANGED
@@ -269,6 +269,38 @@ export interface AgentLocalOptions {
269
269
  * ambient `AGENTS.md` / `.cursor` rules.
270
270
  */
271
271
  cwd?: string;
272
+ /**
273
+ * One harness cwd shared by every session, for agents that work inside an
274
+ * existing checkout. Absolute, or relative to the agent project root.
275
+ * Takes precedence over {@link cwd}; a per-send
276
+ * {@link SendMessageOptions.workspaceDir} still wins over both.
277
+ *
278
+ * The SDK keys its local executor — Cursor rules, skills, MCP, the ignore
279
+ * mappings — on the harness cwd, so a shared directory resolves the
280
+ * workspace once per serve process instead of once per session. With
281
+ * `cwd`'s `<cwd>/<sessionId>` layout that cache never hits, and on a large
282
+ * repo each session pays the full scan again.
283
+ *
284
+ * Sessions are no longer isolated from each other on disk: they share a
285
+ * working tree, and a file one turn writes is visible to the next. Agent
286
+ * scaffold (`AGENTS.md`, skills, tool scripts) is kept out of the shared
287
+ * directory and delivered inline instead, so pointing this at a repo does
288
+ * not write agentkit files into it — but `workspaceFiles` still lands in
289
+ * the harness cwd, as it does for a per-send override.
290
+ */
291
+ workspaceDir?: string;
292
+ /**
293
+ * Run the harness inside Cursor's local sandbox (`sandboxOptions.enabled`
294
+ * on the SDK). Off by default, matching the SDK: shell then auto-approves
295
+ * and inherits the serve process environment — including any credentials
296
+ * the host holds.
297
+ *
298
+ * Turn this on for agents whose turns read untrusted input (webhook
299
+ * payloads, PR diffs, inbound chat). It is a real tool boundary rather
300
+ * than a prompt-level one, so it still holds when the model is steered
301
+ * into ignoring its instructions.
302
+ */
303
+ sandbox?: boolean;
272
304
  }
273
305
 
274
306
  export type AgentConfigDefinition = AgentConfig & BrandedDefinition<"agent">;
@@ -585,9 +617,9 @@ export type ConnectionTransport =
585
617
  /** Expose the Cursor account's MCP connectors (backend-executed). */
586
618
  cursorAccount: true;
587
619
  /**
588
- * Restrict to these connector names (as they appear in the Cursor
589
- * account's MCP config, e.g. `["Linear", "Notion"]`). Omit to expose
590
- * every connected HTTP/SSE server on the account.
620
+ * Restrict to these connector names after discovery normalization.
621
+ * Authored configs may also pass `"*"` / `["*"]` (see
622
+ * {@link ConnectionConfig}); those normalize to `undefined` (= all).
591
623
  */
592
624
  servers?: string[];
593
625
  };
@@ -606,6 +638,38 @@ export function isCursorAccountTransport(
606
638
  return "cursorAccount" in transport && transport.cursorAccount === true;
607
639
  }
608
640
 
641
+ /**
642
+ * Normalize an authored Cursor account `servers` filter.
643
+ *
644
+ * `undefined`, `"*"`, and `["*"]` (after trim) all mean every connected
645
+ * HTTP/SSE server on the account. Returns a concrete allowlist, or
646
+ * `undefined` for all. Does not validate emptiness, blank entries, or a
647
+ * mixed `"*"` + names list — discovery owns those diagnostics.
648
+ */
649
+ export function normalizeCursorAccountServers(
650
+ servers: string[] | "*" | undefined
651
+ ): string[] | undefined {
652
+ if (servers === undefined || servers === "*") {
653
+ return undefined;
654
+ }
655
+ const trimmed = servers.map((server) => server.trim());
656
+ if (trimmed.length === 1 && trimmed[0] === "*") {
657
+ return undefined;
658
+ }
659
+ return [...servers];
660
+ }
661
+
662
+ /** True when an authored allowlist mixes `"*"` with other connector names. */
663
+ export function cursorAccountServersHasMixedWildcard(
664
+ servers: string[] | "*" | undefined
665
+ ): boolean {
666
+ if (servers === undefined || servers === "*") {
667
+ return false;
668
+ }
669
+ const trimmed = servers.map((server) => server.trim());
670
+ return trimmed.includes("*") && trimmed.some((server) => server !== "*");
671
+ }
672
+
609
673
  /**
610
674
  * True for transports that stay symbolic at discovery time and are resolved
611
675
  * by the serve host once it is listening (peers and the Cursor account
@@ -620,7 +684,29 @@ export function isSymbolicConnectionTransport(
620
684
  );
621
685
  }
622
686
 
623
- export type ConnectionConfig = ConnectionTransport & {
687
+ /**
688
+ * Authored MCP connection config (`defineConnection(...)`).
689
+ *
690
+ * For Cursor account connections, `servers` may be omitted, `"*"`, or
691
+ * `["*"]` to forward every connected HTTP/SSE connector; a concrete
692
+ * `string[]` allowlists by connector name. Discovery normalizes the
693
+ * wildcard forms to an unfiltered {@link ConnectionTransport}.
694
+ */
695
+ export type ConnectionConfig = (
696
+ | Exclude<ConnectionTransport, { cursorAccount: true }>
697
+ | {
698
+ cursorAccount: true;
699
+ /**
700
+ * Which account connectors to expose.
701
+ *
702
+ * - Omit, pass `"*"`, or pass `["*"]` to forward **every** connected
703
+ * HTTP/SSE server on the account (no per-connector allowlist).
704
+ * - Pass connector names as they appear in the Cursor account's MCP
705
+ * config (e.g. `["Linear", "Notion"]`) to restrict the set.
706
+ */
707
+ servers?: string[] | "*";
708
+ }
709
+ ) & {
624
710
  /** Documentation only; shown in `info` output. */
625
711
  description?: string;
626
712
  /**
@@ -1876,6 +1962,8 @@ export interface RunnerTurnRequest {
1876
1962
  sdkAgentId?: string;
1877
1963
  /** Absolute path of the session's materialized workspace. */
1878
1964
  workspaceDir: string;
1965
+ /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
1966
+ sandbox?: boolean;
1879
1967
  /** Absolute path for runner-owned durable state (conversation store). */
1880
1968
  runnerStateDir: string;
1881
1969
  prompt: string;
@@ -1,85 +0,0 @@
1
- /**
2
- * Live-reply delivery strategies for the Slack default handlers.
3
- *
4
- * A single strategy owns how an in-progress reply is opened, updated,
5
- * finalized, and cleaned up so the handlers in `defaults.ts` don't fork on the
6
- * delivery mode at every event:
7
- *
8
- * - `stream`: Slack chat.startStream / appendStream / stopStream.
9
- * - `post-update`: a chat.postMessage skeleton edited with chat.update. This is
10
- * the only path that preserves Cursor-account identity pinning (which only
11
- * covers postMessage).
12
- *
13
- * `buildDefaultEvents` selects one via {@link selectLiveDeliveryStrategy} up
14
- * front and calls into it. All calls keep the same soft-fail / log behavior as
15
- * the inlined logic they replaced.
16
- */
17
- import type { ChannelEventContext } from "../../types.js";
18
- import type { SlackLog } from "./log.js";
19
- import type { SlackBotToken, SlackChannelState } from "./types.js";
20
- type SlackChannel = ChannelEventContext<SlackChannelState>;
21
- export interface LiveDeliveryDeps {
22
- botToken: SlackBotToken | undefined;
23
- getLog: () => SlackLog;
24
- }
25
- /**
26
- * How the default handlers deliver an in-progress reply. Methods write live
27
- * delivery state (`streamTs`, `streamChannelId`, `lastPostedText`,
28
- * `lastPostUpdateAtMs`, `streamingUnavailable`) on `channel.state` directly.
29
- */
30
- export interface LiveDeliveryStrategy {
31
- /** True when tool-call thinking steps can be appended to the live message. */
32
- readonly inlineToolSteps: boolean;
33
- /** Open the live message (skeleton post / stream start). */
34
- start(args: {
35
- channel: SlackChannel;
36
- channelId: string;
37
- threadTs: string;
38
- sessionId: string;
39
- }): Promise<void>;
40
- /** Push the latest cumulative text to the live message (throttled). */
41
- append(args: {
42
- channel: SlackChannel;
43
- channelId: string;
44
- streamTs: string;
45
- text: string;
46
- sessionId: string;
47
- }): Promise<void>;
48
- /**
49
- * Flush the final reply text. `delivered` is false only when the caller must
50
- * post the full reply as a fresh message (finalize failed on partial text).
51
- */
52
- finalize(args: {
53
- channel: SlackChannel;
54
- channelId: string;
55
- streamTs: string;
56
- text: string;
57
- sessionId: string;
58
- }): Promise<{
59
- delivered: boolean;
60
- }>;
61
- /** Close the live message when the turn produced no final text. */
62
- finalizeEmpty(args: {
63
- channel: SlackChannel;
64
- channelId: string;
65
- streamTs: string;
66
- }): Promise<void>;
67
- /** Best-effort remove a live message left open after the turn ended. */
68
- cleanupOrphan(args: {
69
- channel: SlackChannel;
70
- }): Promise<void>;
71
- /** Deliver the error text into the live message; `delivered` gates a fallback post. */
72
- fail(args: {
73
- channel: SlackChannel;
74
- channelId: string;
75
- streamTs: string;
76
- errorText: string;
77
- sessionId: string;
78
- }): Promise<{
79
- delivered: boolean;
80
- }>;
81
- }
82
- /** Pick the live-reply delivery strategy for a `buildDefaultEvents` instance. */
83
- export declare function selectLiveDeliveryStrategy(deps: LiveDeliveryDeps, usePostUpdate: boolean): LiveDeliveryStrategy;
84
- export {};
85
- //# sourceMappingURL=post-update-delivery.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"post-update-delivery.d.ts","sourceRoot":"","sources":["../../../src/channels/slack/post-update-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAW1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE,KAAK,YAAY,GAAG,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,MAAM,QAAQ,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,4DAA4D;IAC5D,KAAK,CAAC,IAAI,EAAE;QACV,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,uEAAuE;IACvE,MAAM,CAAC,IAAI,EAAE;QACX,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE;QACb,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpC,mEAAmE;IACnE,aAAa,CAAC,IAAI,EAAE;QAClB,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,wEAAwE;IACxE,aAAa,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,uFAAuF;IACvF,IAAI,CAAC,IAAI,EAAE;QACT,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrC;AA6RD,iFAAiF;AACjF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,gBAAgB,EACtB,aAAa,EAAE,OAAO,GACrB,oBAAoB,CAItB"}