@cursor/july 0.1.109 → 0.1.111

package/src/internal/convert-automation/convert-workflow.ts

@@ -124,7 +124,7 @@ export function convertWorkflow(
 
   emitMcpConnections(automation, mcpServers, out);
   const hasSlackAction = (workflow.actions ?? []).some(
-    (action) => action.slack !== undefined || action.readSlack !== undefined
+    action => action.slack !== undefined || action.readSlack !== undefined
   );
   const hasSlackConnection =
     hasSlackAction && emitSlackAccountConnection(automation, out);
@@ -386,7 +386,7 @@ function emitGithubChannel(
   for (const trigger of triggers) {
     const git = trigger.git as GitTriggerJson;
     userAllowlist.push(
-      ...(git.userAllowlist ?? []).filter((user) => user !== "")
+      ...(git.userAllowlist ?? []).filter(user => user !== "")
     );
     for (const [eventKey, events] of Object.entries(GIT_EVENT_WEBHOOKS)) {
       const event = git[eventKey as keyof GitTriggerJson];
@@ -546,7 +546,7 @@ function emitGithubChannel(
         webhookEvents.push("pull_request");
         prConditions.push(
           ...labelActions.map(
-            (action) => `(pr.action === ${JSON.stringify(action)})`
+            action => `(pr.action === ${JSON.stringify(action)})`
           )
         );
       }
@@ -566,7 +566,7 @@ function emitGithubChannel(
 
   const uniqueEvents = dedupe(webhookEvents);
   const uniqueRepos = dedupe(
-    dedupe(repos.filter((repo) => repo !== "")).flatMap((repo) => {
+    dedupe(repos.filter(repo => repo !== "")).flatMap(repo => {
       const normalized = normalizeRepoIdentifier(repo, out);
       return normalized === undefined ? [] : [normalized];
     })
@@ -595,17 +595,15 @@ function emitGithubChannel(
   if (uniqueRepos.length > 0) {
     configLines.push("  cursorAccount: {");
     configLines.push(
-      `    repos: [${uniqueRepos.map((repo) => JSON.stringify(repo)).join(", ")}],`
+      `    repos: [${uniqueRepos.map(repo => JSON.stringify(repo)).join(", ")}],`
     );
     configLines.push("  },");
   }
   configLines.push(
-    `  webhookEvents: [${uniqueEvents.map((event) => JSON.stringify(event)).join(", ")}],`
+    `  webhookEvents: [${uniqueEvents.map(event => JSON.stringify(event)).join(", ")}],`
   );
 
-  const uniqueAllowlist = dedupe(
-    userAllowlist.map((user) => user.toLowerCase())
-  );
+  const uniqueAllowlist = dedupe(userAllowlist.map(user => user.toLowerCase()));
   if (triggers.length > 1 && uniqueAllowlist.length > 0) {
     out.warnings.push(
       `user_allowlist applies per trigger in the backend; the export unions every trigger's allowlist across all hooks in ${path} — tighten per hook if the triggers differed.`
@@ -663,7 +661,7 @@ function emitGithubChannel(
     "",
     `// Exported from Cursor automation "${commentSafe(automation.name)}" git trigger(s).`,
     "// Original trigger config:",
-    ...jsonComment(triggers.map((trigger) => trigger.git)),
+    ...jsonComment(triggers.map(trigger => trigger.git)),
     "//",
     "// The hooks below reproduce the triggers' mechanical filters. Cursor's",
     "// backend also enforced any bespoke conditions (comment matching, CI",
@@ -751,7 +749,7 @@ function renderGithubHooks(args: {
         "    }"
       );
     }
-    const refs = args.pushBranches.map((branch) =>
+    const refs = args.pushBranches.map(branch =>
       JSON.stringify(`refs/heads/${branch}`)
     );
     lines.push(
@@ -804,7 +802,7 @@ function renderGithubHooks(args: {
     const condition =
       args.issueActions.length === 1
         ? `issue.action === ${JSON.stringify(args.issueActions[0])}`
-        : `[${args.issueActions.map((action) => JSON.stringify(action)).join(", ")}].includes(issue.action)`;
+        : `[${args.issueActions.map(action => JSON.stringify(action)).join(", ")}].includes(issue.action)`;
     lines.push("  onIssue: (ctx, issue) => {");
     if (hasAllowlist) {
       allowlistUsed = true;
@@ -867,7 +865,7 @@ function renderGithubHooks(args: {
     ? [
         "// user_allowlist from the original trigger(s), lowercased — GitHub",
         "// logins are case-insensitive and the backend compared them that way.",
-        `const ALLOWED_USERS = [${args.userAllowlist.map((user) => JSON.stringify(user)).join(", ")}];`,
+        `const ALLOWED_USERS = [${args.userAllowlist.map(user => JSON.stringify(user)).join(", ")}];`,
         "",
       ]
     : [];
@@ -883,7 +881,7 @@ function repoLabel(eventObject: Record<string, unknown>): string {
             (repo): repo is string => typeof repo === "string"
           )
         : []),
-    ].filter((repo) => repo !== "")
+    ].filter(repo => repo !== "")
   );
   return repos.length > 0 ? ` (${repos.join(", ")})` : "";
 }
@@ -925,7 +923,7 @@ function normalizeRepoIdentifier(
     );
     return undefined;
   }
-  const segments = url.pathname.split("/").filter((s) => s !== "");
+  const segments = url.pathname.split("/").filter(s => s !== "");
   if (segments.length < 2) {
     out.warnings.push(
       `Repo URL ${JSON.stringify(raw)} has no owner/repo path — excluded from the GitHub channel's cursorAccount repos.`
@@ -958,9 +956,9 @@ function emitSlackChannel(
   const slug = slugs.claim("slack");
   const path = `agent/channels/${slug}.ts`;
 
-  const watches = triggers.filter((t) => t.slackTrigger !== undefined);
+  const watches = triggers.filter(t => t.slackTrigger !== undefined);
   const unsupported = triggers.filter(
-    (t) =>
+    t =>
       t.slackReactionAdded !== undefined ||
       t.slackAnyReactionAdded !== undefined ||
       t.slackChannelCreated !== undefined
@@ -1016,10 +1014,10 @@ function emitSlackChannel(
   let body: string[];
   if (socketMode) {
     const allow = dedupe(
-      watches.flatMap((watch) => slackChannelList(watch.slackTrigger))
+      watches.flatMap(watch => slackChannelList(watch.slackTrigger))
     );
     const anyThreadReplies = watches.some(
-      (watch) =>
+      watch =>
         (watch.slackTrigger as SlackWatchTriggerJson).topLevelOnly === false
     );
     // "Authenticated Cursor users" watches require a linked Cursor account
@@ -1029,14 +1027,14 @@ function emitSlackChannel(
     // pick a side: keep bots when any watch allowed everyone (alert /
     // scorebot watches depend on them), and say so loudly.
     const blocksUnauthenticated = watches.some(
-      (watch) =>
+      watch =>
         (watch.slackTrigger as SlackWatchTriggerJson)
           .blockUnauthenticatedSlackUsers === true
     );
     const includeBotPosts =
       watches.length > 0 &&
       watches.some(
-        (watch) =>
+        watch =>
           (watch.slackTrigger as SlackWatchTriggerJson)
             .blockUnauthenticatedSlackUsers !== true
       );
@@ -1052,7 +1050,7 @@ function emitSlackChannel(
       engagement.push("  engagement: {");
       engagement.push("    channelPosts: {");
       engagement.push(
-        `      allow: [${allow.map((channel) => JSON.stringify(channel)).join(", ")}],`
+        `      allow: [${allow.map(channel => JSON.stringify(channel)).join(", ")}],`
       );
       if (anyThreadReplies) {
         engagement.push('      posts: "all",');
@@ -1111,7 +1109,7 @@ function slackChannelList(
 }
 
 // ============================================================================
-// Boilerplate webhook channels (Linear / PagerDuty / Sentry / Teams / webhook)
+// Boilerplate webhook channels (Linear / PagerDuty / Sentry / Teams / email / webhook)
 // ============================================================================
 
 type BoilerplateKind = {
@@ -1120,6 +1118,7 @@ type BoilerplateKind = {
     | "pagerduty"
     | "sentry"
     | "webhook"
+    | "emailReceived"
     | "microsoftTeamsTrigger"
     | "microsoftTeamsChannelCreated";
   slug: string;
@@ -1131,6 +1130,7 @@ const BOILERPLATE_KINDS: BoilerplateKind[] = [
   { key: "pagerduty", slug: "pagerduty", label: "PagerDuty" },
   { key: "sentry", slug: "sentry", label: "Sentry" },
   { key: "webhook", slug: "webhook", label: "webhook" },
+  { key: "emailReceived", slug: "email", label: "email received" },
   {
     key: "microsoftTeamsTrigger",
     slug: "teams",
@@ -1144,7 +1144,7 @@ const BOILERPLATE_KINDS: BoilerplateKind[] = [
 ];
 
 function boilerplateKind(trigger: TriggerJson): BoilerplateKind | undefined {
-  return BOILERPLATE_KINDS.find((kind) => trigger[kind.key] !== undefined);
+  return BOILERPLATE_KINDS.find(kind => trigger[kind.key] !== undefined);
 }
 
 function emitBoilerplateChannel(
@@ -1280,7 +1280,7 @@ function emitSlackAccountConnection(
   out: ConvertOutput
 ): boolean {
   const path = "agent/mcp-connections/slack.ts";
-  if (out.files.some((file) => file.path === path)) {
+  if (out.files.some(file => file.path === path)) {
     return true;
   }
   const lines = [
@@ -1297,7 +1297,7 @@ function emitSlackAccountConnection(
     "",
   ];
   out.files.push({ path, contents: lines.join("\n") });
-  if (!out.mcpConnections.some((connection) => connection.name === "slack")) {
+  if (!out.mcpConnections.some(connection => connection.name === "slack")) {
     out.mcpConnections.push({ name: "slack", kind: "cursorAccount" });
   }
   return true;
@@ -1417,7 +1417,7 @@ function jsonComment(value: unknown): string[] {
     .replace(/\u2028/g, "\\u2028")
     .replace(/\u2029/g, "\\u2029")
     .split("\n")
-    .map((line) => `//   ${line}`);
+    .map(line => `//   ${line}`);
 }
 
 function dedupe(values: string[]): string[] {

package/src/internal/convert-automation/types.ts

@@ -117,6 +117,7 @@ export interface TriggerJson {
   slackReactionAdded?: SlackChannelsTriggerJson;
   slackMention?: SlackChannelsTriggerJson;
   slackAnyReactionAdded?: SlackChannelsTriggerJson;
+  emailReceived?: EmailReceivedTriggerJson;
 }
 
 export interface CronTriggerJson {
@@ -164,6 +165,14 @@ export interface SlackWatchTriggerJson {
   [key: string]: unknown;
 }
 
+/** EmailReceivedTrigger (Grok Bot inbox). */
+export interface EmailReceivedTriggerJson {
+  inboxEmail?: string;
+  fromAddresses?: string[];
+  requireAuthPass?: boolean;
+  [key: string]: unknown;
+}
+
 /** Shared shape of SlackMention / SlackReactionAdded / SlackAnyReactionAdded. */
 export interface SlackChannelsTriggerJson {
   channel?: string;

package/src/internal/cursor/account-mcp.ts

@@ -45,6 +45,7 @@ import {
   terminalHyperlink,
 } from "../terminal-style.js";
 import type {
+  AccountMcpCallResult,
   AccountMcpServer,
   CursorBackendClient,
 } from "./backend-client.js";
@@ -132,7 +133,7 @@ export function resolveCursorAccountConnections(args: {
       ? undefined
       : trimTrailingSlash(args.publicUrl);
   const headers = { authorization: `Bearer ${args.bridgeSecret}` };
-  return args.refs.map((ref) => ({
+  return args.refs.map(ref => ({
     name: ref.name,
     localUrl: `${serverBase}${args.basePath}${cursorAccountMcpPath(ref.name)}`,
     ...(publicBase === undefined
@@ -236,10 +237,19 @@ export class CursorAccountMcpBridge {
    * Handle one streamable-HTTP MCP request for the connection described by
    * `ref` (stateless: fresh server per POST, like the per-agent endpoint).
    */
-  handle(request: Request, ref: CursorAccountConnectionRef): Promise<Response> {
+  handle(
+    request: Request,
+    ref: CursorAccountConnectionRef,
+    decorate?: (
+      sessionId: string,
+      result: AccountMcpCallResult
+    ) => AccountMcpCallResult
+  ): Promise<Response> {
+    const sessionId =
+      new URL(request.url).searchParams.get("agentkitSessionId") ?? "";
     return handleStatelessMcpRequest({
       request,
-      buildServer: () => this.buildServer(ref),
+      buildServer: () => this.buildServer(ref, sessionId, decorate),
       label: "cursor account bridge",
       logger: this.logger,
     });
@@ -261,7 +271,7 @@ export class CursorAccountMcpBridge {
       ref.servers !== undefined && ref.servers.length > 0
         ? [...ref.servers]
         : (await this.client.getAvailableMcpServers()).map(
-            (server) => server.serverIdentifier ?? server.name
+            server => server.serverIdentifier ?? server.name
           );
     const urls = await probeConnectorAuthUrls({
       client: this.client,
@@ -276,7 +286,7 @@ export class CursorAccountMcpBridge {
   }
 
   logPreflight(refs: CursorAccountConnectionRef[]): Promise<void> {
-    return Promise.all(refs.map((ref) => this.runPreflight(ref))).then(
+    return Promise.all(refs.map(ref => this.runPreflight(ref))).then(
       () => undefined
     );
   }
@@ -286,8 +296,8 @@ export class CursorAccountMcpBridge {
       const catalog = await this.getCatalog(ref);
       const errorDetails = new Map<string, string>();
       const needsAuthNames = catalog.servers
-        .filter((server) => server.status === "needsAuth")
-        .map((server) => server.serverIdentifier);
+        .filter(server => server.status === "needsAuth")
+        .map(server => server.serverIdentifier);
       const [authUrls] = await Promise.all([
         probeConnectorAuthUrls({
           client: this.client,
@@ -295,8 +305,8 @@ export class CursorAccountMcpBridge {
         }),
         Promise.all(
           catalog.servers
-            .filter((server) => server.status === "error")
-            .map(async (server) => {
+            .filter(server => server.status === "error")
+            .map(async server => {
               const detail = await diagnoseConnectorError(
                 this.client,
                 server.serverIdentifier
@@ -309,13 +319,13 @@ export class CursorAccountMcpBridge {
       ]);
 
       const unhealthy = catalog.servers.some(
-        (server) => server.status === "needsAuth" || server.status === "error"
+        server => server.status === "needsAuth" || server.status === "error"
       );
       if (catalog.servers.length === 0 || unhealthy) {
         this.logger(
           formatCursorAccountMcpWarningBox({
             connectionName: ref.name,
-            servers: catalog.servers.map((server) => ({
+            servers: catalog.servers.map(server => ({
               serverIdentifier: server.serverIdentifier,
               status: server.status,
               toolCount: server.tools.length,
@@ -329,7 +339,7 @@ export class CursorAccountMcpBridge {
       }
 
       const summary = catalog.servers
-        .map((server) =>
+        .map(server =>
           formatServerStatusSummary(
             server,
             errorDetails.get(server.serverIdentifier)
@@ -346,7 +356,14 @@ export class CursorAccountMcpBridge {
     }
   }
 
-  private buildServer(ref: CursorAccountConnectionRef): Server {
+  private buildServer(
+    ref: CursorAccountConnectionRef,
+    sessionId: string,
+    decorate?: (
+      sessionId: string,
+      result: AccountMcpCallResult
+    ) => AccountMcpCallResult
+  ): Server {
     const server = new Server(
       { name: `cursor-account:${ref.name}`, version: "0.1.0" },
       {
@@ -359,7 +376,7 @@ export class CursorAccountMcpBridge {
     server.setRequestHandler(ListToolsRequestSchema, async () => {
       const catalog = await this.getCatalog(ref);
       return {
-        tools: catalog.tools.map((tool) => ({
+        tools: catalog.tools.map(tool => ({
           name: tool.exposedName,
           description: tool.description,
           inputSchema: tool.inputSchema,
@@ -375,25 +392,25 @@ export class CursorAccountMcpBridge {
       };
     });
 
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async request => {
       const tool = await this.findTool(ref, request.params.name);
       if (tool === undefined) {
         const catalog = await this.getCatalog(ref);
         const unhealthy = catalog.servers.filter(
-          (server) => server.status !== "connected"
+          server => server.status !== "connected"
         );
         const statusHint =
           unhealthy.length === 0
             ? ""
             : ` Unhealthy connectors: ${unhealthy
-                .map((server) => `${server.serverIdentifier}=${server.status}`)
+                .map(server => `${server.serverIdentifier}=${server.status}`)
                 .join(", ")}.`;
         return {
           content: [
             {
               type: "text",
               text: `Unknown tool "${request.params.name}". Available: ${
-                catalog.tools.map((t) => t.exposedName).join(", ") || "(none)"
+                catalog.tools.map(t => t.exposedName).join(", ") || "(none)"
               }.${statusHint}`,
             },
           ],
@@ -401,17 +418,17 @@ export class CursorAccountMcpBridge {
         };
       }
       try {
-        const result = await this.client.executeAccountMcpTool({
+        const executed = await this.client.executeAccountMcpTool({
           serverIdentifier: tool.serverIdentifier,
           toolName: tool.backendName,
           args: request.params.arguments ?? {},
         });
+        const decorated =
+          decorate === undefined ? executed : decorate(sessionId, executed);
         return {
-          content: result.content,
-          ...(result.isError ? { isError: true } : {}),
-          ...(result.structuredContent === undefined
-            ? {}
-            : { structuredContent: result.structuredContent }),
+          content: decorated.content,
+          isError: decorated.isError === true ? true : undefined,
+          structuredContent: decorated.structuredContent,
         };
       } catch (error) {
         return {
@@ -471,7 +488,7 @@ export class CursorAccountMcpBridge {
     const fresh: CatalogEntry = {
       promise: this.client
         .listAccountMcpTools(ref.servers ?? [])
-        .then((servers) => {
+        .then(servers => {
           const catalog = buildCatalog(servers);
           fresh.freshAtMs = Date.now();
           return catalog;
@@ -643,13 +660,13 @@ function warningCopy(args: {
   hyperlinks: boolean;
 }): { title: string; intro: string[]; actions: string[] } {
   const empty = args.servers.length === 0;
-  const hasAuth = args.servers.some((server) => server.status === "needsAuth");
-  const hasError = args.servers.some((server) => server.status === "error");
+  const hasAuth = args.servers.some(server => server.status === "needsAuth");
+  const hasError = args.servers.some(server => server.status === "error");
   const nameWidth = Math.max(
     0,
-    ...args.servers.map((server) => server.serverIdentifier.length)
+    ...args.servers.map(server => server.serverIdentifier.length)
   );
-  const statusRows = args.servers.map((server) =>
+  const statusRows = args.servers.map(server =>
     formatWarningStatusRow(server, nameWidth, args.hyperlinks)
   );
   const links = [
@@ -736,8 +753,8 @@ export async function diagnoseConnectorError(
       .filter(
         (part): part is { type: "text"; text: string } => part.type === "text"
       )
-      .map((part) => part.text.trim())
-      .filter((part) => part.length > 0)
+      .map(part => part.text.trim())
+      .filter(part => part.length > 0)
       .join(" ");
     if (result.isError) {
       return text.length > 0

package/src/internal/cursor/backend-client.ts

@@ -82,14 +82,24 @@ const githubTokenResponseSchema: z.ZodType<CursorGithubToken> = z.object({
   expiresAt: z.string().datetime(),
 });
 
-/** SCMs whose git fetches ride the backend's `/v0/scm-events/<provider>-git-proxy` routes. */
-export type CursorScmCloneProvider = "gitlab" | "bitbucket";
+/**
+ * SCMs whose git fetches ride the backend's `/v0/scm-events/<provider>-git-proxy`
+ * routes. `github` is for GitHub Enterprise Server hosts an engine's egress
+ * cannot reach; github.com clones mint a token and go direct.
+ */
+export type CursorScmCloneProvider = "github" | "gitlab" | "bitbucket";
+
+const SCM_CLONE_PROVIDER_LABELS: Record<CursorScmCloneProvider, string> = {
+  github: "GitHub",
+  gitlab: "GitLab",
+  bitbucket: "Bitbucket",
+};
 
 /**
- * Proxied clone target for a GitLab / Bitbucket repository. The backend
- * never hands out the provider credential: git fetches go to `remoteUrl`
- * on the backend with the caller's own Cursor API key as a bearer token,
- * and the backend adds the tenant credential per request.
+ * Proxied clone target for a GitHub (GHES) / GitLab / Bitbucket repository.
+ * The backend never hands out the provider credential: git fetches go to
+ * `remoteUrl` on the backend with the caller's own Cursor API key as a
+ * bearer token, and the backend adds the tenant credential per request.
  */
 export interface CursorScmCloneTarget {
   /** Absolute `<backend>/v0/scm-events/<provider>-git-proxy/<repo>.git`. */
@@ -385,10 +395,10 @@ export class CursorBackendClient {
       LIST_TIMEOUT_MS
     );
     const parsed = listSandMcpToolsResponseSchema.parse(raw);
-    return (parsed.servers ?? []).map((server) => ({
+    return (parsed.servers ?? []).map(server => ({
       serverIdentifier: server.serverIdentifier,
       status: server.status,
-      tools: (server.tools ?? []).map((tool) => {
+      tools: (server.tools ?? []).map(tool => {
         const outputSchema = parseOutputSchemaJson(tool.outputSchemaJson);
         const annotations = parseAnnotationsJson(tool.annotationsJson);
         return {
@@ -439,8 +449,8 @@ export class CursorBackendClient {
     });
     const parsed = getAvailableMcpServersResponseSchema.parse(raw);
     return (parsed.servers ?? [])
-      .filter((server) => server.id !== undefined && server.id > 0)
-      .map((server) => ({
+      .filter(server => server.id !== undefined && server.id > 0)
+      .map(server => ({
         id: server.id!,
         name: server.name ?? "",
         isTeamServer: server.isTeamServer === true,
@@ -469,7 +479,7 @@ export class CursorBackendClient {
       LIST_TIMEOUT_MS
     );
     const parsed = checkHttpMcpStatusResponseSchema.parse(raw);
-    return (parsed.statuses ?? []).map((status) => ({
+    return (parsed.statuses ?? []).map(status => ({
       id: status.id ?? 0,
       requiresAuth: status.requiresAuth === true,
       authUrl: status.authUrl,
@@ -522,16 +532,17 @@ export class CursorBackendClient {
   }
 
   /**
-   * Resolve the proxied clone target for a GitLab / Bitbucket repository
-   * (`owner/name`; GitLab `path_with_namespace`). Same authorization as the
-   * provider proxy this host already calls; the returned remote lives on
-   * the backend and takes this client's API key, never a provider token.
+   * Resolve the proxied clone target for a GitHub (GHES) / GitLab /
+   * Bitbucket repository (`owner/name`; GitLab `path_with_namespace`). Same
+   * authorization as the provider proxy this host already calls; the
+   * returned remote lives on the backend and takes this client's API key,
+   * never a provider token.
    */
   async getScmCloneTarget(
     provider: CursorScmCloneProvider,
     repo: string
   ): Promise<CursorScmCloneTarget> {
-    const label = provider === "gitlab" ? "GitLab" : "Bitbucket";
+    const label = SCM_CLONE_PROVIDER_LABELS[provider];
     let response: Response;
     try {
       response = await this.fetchImpl(
@@ -790,7 +801,7 @@ export async function revokeMintedUserApiKey(args: {
   );
   const masked = maskApiKey(args.apiKey);
   const match = (listed.apiKeys ?? []).find(
-    (key) => key.name === args.keyName && key.maskedKey === masked
+    key => key.name === args.keyName && key.maskedKey === masked
   );
   if (match === undefined) {
     // CreateUserApiKey writes the primary while ListUserApiKeys may read a

package/src/internal/cursor/credentials.ts

@@ -566,7 +566,7 @@ function isAborted(signal?: AbortSignal): boolean {
 }
 
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     if (signal?.aborted === true) {
       resolve();
       return;

package/src/internal/cursor/hosted-store-secrets.ts

@@ -15,11 +15,24 @@ export const DEFAULT_AGENT_SERVE_STORE_SOURCE_ID_FILE =
 export const DEFAULT_AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE =
   "/run/cursor/secrets/AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
 
+export const DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE =
+  "/run/cursor/secrets/AGENT_SERVE_STORE_PROTOCOL";
+
+/**
+ * Pin value selecting the factory store API (`/internal/agentsdk/store`)
+ * over `/v0/agent-serve-files`. Any other value — including a newer pin this
+ * runtime does not know — falls back to `/v0`, so the pin fails safe in both
+ * directions.
+ */
+export const AGENT_SERVE_FACTORY_FLUSH_PROTOCOL = "factory-flush-v1";
+
 const STORE_SOURCE_ID_ENV = "AGENT_SERVE_STORE_SOURCE_ID";
 const FRAMEWORK_STORE_SOURCE_ID_ENV = "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
 const STORE_SOURCE_ID_FILE_ENV = "AGENT_SERVE_STORE_SOURCE_ID_FILE";
 const FRAMEWORK_STORE_SOURCE_ID_FILE_ENV =
   "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_FILE";
+const STORE_PROTOCOL_ENV = "AGENT_SERVE_STORE_PROTOCOL";
+const STORE_PROTOCOL_FILE_ENV = "AGENT_SERVE_STORE_PROTOCOL_FILE";
 
 function readTrimmedFile(path: string): string | undefined {
   try {
@@ -71,6 +84,27 @@ export function resolveFrameworkStoreSourceIdSync(
   );
 }
 
+/**
+ * Store protocol pin: env, then task-bind file. The control plane binds
+ * `factory-flush-v1` on every hosted v2 pod. Absence or an unknown value
+ * still means `/v0/agent-serve-files`. Resolved lazily per operation like
+ * the store ids, so a pod bound after serve start takes effect without a
+ * restart.
+ */
+export function resolveStoreProtocolSync(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const fromEnv = env[STORE_PROTOCOL_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") {
+    return fromEnv;
+  }
+  return readBoundSecretFile(
+    STORE_PROTOCOL_FILE_ENV,
+    DEFAULT_AGENT_SERVE_STORE_PROTOCOL_FILE,
+    env
+  );
+}
+
 export type CursorManagedV2StoreIds = {
   deploymentStoreSourceId: string;
   frameworkStoreSourceId: string;