@cursor/july 0.1.32 → 0.1.34

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

@@ -0,0 +1,10 @@
+export { convertWorkflow } from "./convert-workflow.js";
+export type {
+  ConvertAutomationMetadata,
+  ConvertedFile,
+  ConvertedMcpConnection,
+  ConvertMcpServer,
+  ConvertWorkflowInput,
+  ConvertWorkflowResult,
+  WorkflowJson,
+} from "./types.js";

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

@@ -0,0 +1,38 @@
+/** Filename slugs for generated project files. */
+
+/** Lowercase, dashes, alphanumerics only; `fallback` when nothing survives. */
+export function slugify(name: string, fallback: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug === "" ? fallback : slug;
+}
+
+/** Single-token PascalCase (Slack cursorAccount agentName). */
+export function pascalCase(name: string, fallback: string): string {
+  const words = name.split(/[^a-zA-Z0-9]+/).filter((word) => word !== "");
+  if (words.length === 0) {
+    return fallback;
+  }
+  return words.map((word) => word[0]?.toUpperCase() + word.slice(1)).join("");
+}
+
+/** Dedupes slugs with numeric suffixes: `linear`, `linear-2`, `linear-3`, … */
+export class SlugRegistry {
+  private readonly used = new Set<string>();
+
+  claim(base: string): string {
+    if (!this.used.has(base)) {
+      this.used.add(base);
+      return base;
+    }
+    for (let suffix = 2; ; suffix++) {
+      const candidate = `${base}-${suffix}`;
+      if (!this.used.has(candidate)) {
+        this.used.add(candidate);
+        return candidate;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,199 @@
+/**
+ * Types for `convertWorkflow` — the pure automation → agentkit project
+ * converter behind `agent-serve convert-automation`.
+ *
+ * The workflow arrives as generic proto3 JSON (lowerCamelCase field names,
+ * enum value names as strings) produced by the backend export endpoint
+ * (`Workflow.toJson()` over `schema/aiserver/v1/automations.proto`).
+ * `@anysphere/proto` is not a dependency of this package, so instead of
+ * `Workflow.fromJson` we model the subset of the JSON shape the converter
+ * reads as local structural types. Unknown fields are ignored by
+ * construction; unknown trigger/action variants surface as warnings.
+ */
+
+/** Automation metadata from the export endpoint (`AutomationExportResponse`). */
+export interface ConvertAutomationMetadata {
+  uuid: string;
+  name: string;
+  enabled: boolean;
+  /** DB scope enum name, e.g. "USER" | "TEAM" | "TEAM_EDITABLE_USER". */
+  scope: string;
+  webUrl: string;
+}
+
+/**
+ * MCP server entry from the export endpoint (`AutomationExportMcpServer`):
+ * name + transport references only. Non-stdio servers convert to
+ * Cursor-account connections resolved at runtime.
+ */
+export interface ConvertMcpServer {
+  id?: string;
+  name: string;
+  transportType: "http" | "sse" | "stdio";
+}
+
+export interface ConvertWorkflowInput {
+  automation: ConvertAutomationMetadata;
+  /** The Workflow as generic proto3 JSON. */
+  workflow: WorkflowJson;
+  /** MCP servers resolved by the export endpoint (not from workflow refs). */
+  mcpServers: ConvertMcpServer[];
+  /**
+   * Export timestamp supplied by the caller (ISO 8601). Passed in so the
+   * conversion stays fully deterministic.
+   */
+  exportedAt: string;
+}
+
+export interface ConvertedFile {
+  path: string;
+  contents: string;
+}
+
+export interface ConvertedMcpConnection {
+  /** Connection (file) name under `agent/mcp-connections/`. */
+  name: string;
+  /** Runtime-resolved Cursor-account connection, or a .todo.md stdio stub. */
+  kind: "cursorAccount" | "stdioStub";
+}
+
+export interface ConvertWorkflowResult {
+  files: ConvertedFile[];
+  warnings: string[];
+  setupSteps: string[];
+  mcpConnections: ConvertedMcpConnection[];
+}
+
+// ============================================================================
+// Workflow proto3 JSON shapes (subset the converter reads)
+// ============================================================================
+
+export interface WorkflowJson {
+  managedConfig?: Record<string, unknown>;
+  triggers?: TriggerJson[];
+  actions?: ActionJson[];
+  prompts?: PromptJson[];
+  model?: string;
+  gitConfig?: GitConfigJson;
+  agentOptions?: AgentOptionsJson;
+  memoryEnabled?: boolean;
+  disabledDefaultTools?: string[];
+}
+
+export interface GitConfigJson {
+  repo?: string;
+  branch?: string;
+  repos?: string[];
+}
+
+export interface AgentOptionsJson {
+  skipInstall?: boolean;
+  privateWorker?: { labels?: Array<{ key?: string; value?: string }> };
+  environmentPublicId?: string;
+}
+
+export interface PromptJson {
+  prompt?: string;
+  /** Enum name (e.g. "PROMPT_EFFORT_LEVEL_HARD") or number. */
+  effortLevel?: string | number;
+  model?: string;
+  suppressSlackReaction?: boolean;
+}
+
+/**
+ * A workflow trigger. Exactly one of the variant fields is set (proto oneof).
+ */
+export interface TriggerJson {
+  cron?: CronTriggerJson;
+  git?: GitTriggerJson;
+  slackTrigger?: SlackWatchTriggerJson;
+  linear?: Record<string, unknown>;
+  webhook?: Record<string, unknown>;
+  slackChannelCreated?: Record<string, unknown>;
+  pagerduty?: Record<string, unknown>;
+  sentry?: Record<string, unknown>;
+  microsoftTeamsTrigger?: Record<string, unknown>;
+  microsoftTeamsChannelCreated?: Record<string, unknown>;
+  slackReactionAdded?: SlackChannelsTriggerJson;
+  slackMention?: SlackChannelsTriggerJson;
+  slackAnyReactionAdded?: SlackChannelsTriggerJson;
+}
+
+export interface CronTriggerJson {
+  cron?: string;
+}
+
+/**
+ * Git trigger. Exactly one event variant is set; each carries `repos` and
+ * event-specific filter fields the converter only echoes into comments.
+ */
+export interface GitTriggerJson {
+  pullRequest?: GitEventJson;
+  push?: GitEventJson;
+  ciCompleted?: GitEventJson;
+  issueLabeled?: GitEventJson;
+  label?: GitEventJson & { pullRequests?: boolean; issues?: boolean };
+  issueComment?: GitEventJson;
+  pullRequestReviewComment?: GitEventJson;
+  pullRequestReview?: GitEventJson;
+  reviewThread?: GitEventJson;
+  workflowRun?: GitEventJson;
+  pullRequestReviewRequested?: GitEventJson;
+  issueAssigned?: GitEventJson;
+  userAllowlist?: string[];
+}
+
+export interface GitEventJson {
+  repo?: string;
+  repos?: string[];
+  orgs?: string[];
+  /** Only on push events: branch filter enforced by Cursor's backend. */
+  branch?: string;
+  /** Enum name, only on pullRequest events (e.g. "GIT_PULL_REQUEST_ACTION_COMMENTED"). */
+  prAction?: string | number;
+  [key: string]: unknown;
+}
+
+/** SlackTrigger (channel watch). */
+export interface SlackWatchTriggerJson {
+  channel?: string;
+  channels?: string[];
+  messageContains?: string;
+  messageContainsIsRegex?: boolean;
+  topLevelOnly?: boolean;
+  [key: string]: unknown;
+}
+
+/** Shared shape of SlackMention / SlackReactionAdded / SlackAnyReactionAdded. */
+export interface SlackChannelsTriggerJson {
+  channel?: string;
+  channels?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * A workflow action. Exactly one variant field is set (proto oneof). Only
+ * `mcp` carries data the converter reads; the rest map to
+ * "behaviors to verify" setup steps.
+ */
+export interface ActionJson {
+  gitPr?: Record<string, unknown>;
+  prComment?: Record<string, unknown>;
+  slack?: SlackActionJson;
+  mcp?: { server?: { id?: string; name?: string } };
+  manageCheckRun?: Record<string, unknown>;
+  requestReviewers?: Record<string, unknown>;
+  readSlack?: Record<string, unknown>;
+  approvePr?: Record<string, unknown>;
+  resolveReviewThreads?: Record<string, unknown>;
+  microsoftTeams?: Record<string, unknown>;
+  readMicrosoftTeams?: Record<string, unknown>;
+}
+
+export interface SlackActionJson {
+  channel?: string;
+  channels?: string[];
+  generalized?: boolean;
+  postAsThread?: boolean;
+  [key: string]: unknown;
+}

package/src/internal/cursor-relay-core.ts

@@ -151,6 +151,42 @@ export interface CursorRelayCoreOptions<TEvent extends { offset: string }> {
   fetchImpl?: typeof fetch;
   /** Test seam: override long-poll wait (default 25s). */
   pollWaitMs?: number;
+  /**
+   * Desired-revision generation for hosted engines. Sent as
+   * `x-agent-serve-generation` so the control plane can fence zombies after
+   * a redeploy. Defaults to `process.env.AGENT_SERVE_GENERATION` when set.
+   */
+  deploymentGeneration?: number;
+}
+
+/** Must match server-shared `AGENT_SERVE_GENERATION_HEADER`. */
+export const AGENT_SERVE_GENERATION_HEADER = "x-agent-serve-generation";
+
+/** Must match server-shared `AGENT_SERVE_GENERATION_ENV_VAR`. */
+export const AGENT_SERVE_GENERATION_ENV_VAR = "AGENT_SERVE_GENERATION";
+
+export function resolveAgentServeDeploymentGeneration(
+  explicit?: number
+): number | undefined {
+  if (
+    explicit !== undefined &&
+    Number.isSafeInteger(explicit) &&
+    explicit > 0
+  ) {
+    return explicit;
+  }
+  const raw = process.env[AGENT_SERVE_GENERATION_ENV_VAR]?.trim();
+  if (raw === undefined || raw.length === 0) {
+    return undefined;
+  }
+  if (!/^\d+$/.test(raw)) {
+    return undefined;
+  }
+  const parsed = Number(raw);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    return undefined;
+  }
+  return parsed;
 }
 
 export class CursorRelayCore<TEvent extends { offset: string }> {
@@ -160,6 +196,7 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
   private consumePromise: Promise<void> | undefined;
   private readonly offsetStore: RelayOffsetStore;
   private readonly fetchImpl: typeof fetch;
+  private readonly deploymentGeneration: number | undefined;
   private consumerId = "";
   /** undefined until the first registration, so a clean first success logs. */
   private lastRegistrationLog: string | undefined;
@@ -175,6 +212,9 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
   constructor(private readonly options: CursorRelayCoreOptions<TEvent>) {
     this.offsetStore = new RelayOffsetStore(options.stateDir);
     this.fetchImpl = options.fetchImpl ?? fetch;
+    this.deploymentGeneration = resolveAgentServeDeploymentGeneration(
+      options.deploymentGeneration
+    );
   }
 
   start(): void {
@@ -285,6 +325,13 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
         headers: {
           authorization: `Bearer ${this.options.apiKey}`,
           "content-type": "application/json",
+          ...(this.deploymentGeneration === undefined
+            ? {}
+            : {
+                [AGENT_SERVE_GENERATION_HEADER]: String(
+                  this.deploymentGeneration
+                ),
+              }),
         },
         body: JSON.stringify(adapter.buildDeregistrationBody(this.consumerId)),
         signal: controller.signal,
@@ -322,6 +369,13 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
       headers: {
         authorization: `Bearer ${this.options.apiKey}`,
         ...(body === undefined ? {} : { "content-type": "application/json" }),
+        ...(this.deploymentGeneration === undefined
+          ? {}
+          : {
+              [AGENT_SERVE_GENERATION_HEADER]: String(
+                this.deploymentGeneration
+              ),
+            }),
       },
       ...(body === undefined ? {} : { body: JSON.stringify(body) }),
       ...(this.abort === undefined ? {} : { signal: this.abort.signal }),
@@ -514,14 +568,19 @@ export class CursorRelayCore<TEvent extends { offset: string }> {
     response: Response,
     backoffMs: number
   ): Promise<number> {
-    const isAuthFailure = response.status === 401 || response.status === 403;
-    const sleepMs = isAuthFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs;
+    // 409 = generation fence (stale resident after redeploy). Same long
+    // backoff as auth: retrying every second cannot heal a wrong generation.
+    const isAuthOrFenceFailure =
+      response.status === 401 ||
+      response.status === 403 ||
+      response.status === 409;
+    const sleepMs = isAuthOrFenceFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs;
     const text = await response.text().catch(() => "");
     this.log(
       `poll failed: ${response.status} ${text.slice(0, 300)} (retrying in ${Math.round(sleepMs / 1000)}s)`
     );
     await this.sleep(sleepMs);
-    return isAuthFailure
+    return isAuthOrFenceFailure
       ? AUTH_FAILURE_BACKOFF_MS
       : Math.min(backoffMs * 2, MAX_BACKOFF_MS);
   }

package/src/internal/deploy-client.ts

@@ -209,6 +209,30 @@ export interface SecretInfo {
   createdAt: string;
 }
 
+/**
+ * `GET /internal/agent-serve/automations/:uuid/export` response
+ * (backend `agentServeAutomationExport.ts`). Name + transport references
+ * only — the backend never exports URLs or credential material.
+ */
+export interface AutomationExportMcpServer {
+  id?: string;
+  name: string;
+  transportType: "http" | "sse" | "stdio";
+}
+
+export interface AutomationExport {
+  automation: {
+    uuid: string;
+    name: string;
+    enabled: boolean;
+    scope: string;
+    webUrl: string;
+  };
+  /** The Workflow as generic proto3 JSON. */
+  workflow: Record<string, unknown>;
+  mcpServers: AutomationExportMcpServer[];
+}
+
 // All response schemas are `.passthrough()`: the backend keeps growing the
 // deployment payload (serviceAccountId, egressAllowedDomains, secret
 // metadata, ...) and unknown fields must flow through untouched — both so
@@ -333,6 +357,30 @@ const listSecretsResponseSchema = z
   })
   .passthrough();
 
+const automationExportSchema = z
+  .object({
+    automation: z
+      .object({
+        uuid: z.string(),
+        name: z.string(),
+        enabled: z.boolean(),
+        scope: z.string(),
+        webUrl: z.string(),
+      })
+      .passthrough(),
+    workflow: z.record(z.unknown()),
+    mcpServers: z.array(
+      z
+        .object({
+          id: z.string().optional(),
+          name: z.string(),
+          transportType: z.enum(["http", "sse", "stdio"]),
+        })
+        .passthrough()
+    ),
+  })
+  .passthrough();
+
 // ============================================================================
 // Client
 // ============================================================================
@@ -533,6 +581,36 @@ export class AgentServeDeployClient {
     return rotatePodCredentialResponseSchema.parse(raw).podCredentialMaskedKey;
   }
 
+  /**
+   * Read an Automation's exported workflow definition for
+   * `convert-automation`. Missing, no-access, and gate-off all surface as
+   * indistinguishable 404s on the backend, so they map to one message here
+   * (the wrong-host 404 hint from {@link mapErrorResponse} passes through).
+   */
+  async exportAutomation(args: { uuid: string }): Promise<AutomationExport> {
+    let raw: unknown;
+    try {
+      raw = await this.request({
+        method: "GET",
+        path: `/internal/agent-serve/automations/${encodeURIComponent(args.uuid)}/export`,
+        context: { verb: "export automation" },
+      });
+    } catch (error) {
+      if (
+        error instanceof DeployApiError &&
+        error.status === 404 &&
+        !error.message.includes("api.cursor.com")
+      ) {
+        throw new DeployApiError(
+          `Automation ${args.uuid} was not found or you don't have access to it (the agent_serve_mvp feature gate may also be off for your team).`,
+          404
+        );
+      }
+      throw error;
+    }
+    return automationExportSchema.parse(raw);
+  }
+
   /** Full URL of the stable engine alias for a deployment. */
   aliasUrl(engineAlias: string): string {
     return `${this.backendUrl}${engineAlias}`;

package/src/internal/discovery.ts

@@ -420,7 +420,6 @@ async function loadAgent(
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
-      serverTools: tools.filter((tool) => tool.execution === "server").length,
       agentTools: tools.filter((tool) => tool.execution === "agent").length,
       skills: skills.length,
       seedFiles: seedFiles.length,
@@ -428,7 +427,7 @@ async function loadAgent(
     });
   }
 
-  appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools, runtime);
+  appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools);
 
   return {
     name,
@@ -1192,30 +1191,19 @@ async function warnUnsupportedSubagentSlots(
 
 /**
  * Append enabled built-in tools after authored tools. Authored tools with
- * the same name win; built-ins are server tools, so cloud runtimes get a
- * warning instead of tools.
+ * the same name win.
  */
 function appendBuiltinTools(
   ctx: DiscoveryContext,
   agentDir: string,
   tools: DiscoveredTool[],
-  config: BuiltinToolsConfig | undefined,
-  runtime: AgentRuntime
+  config: BuiltinToolsConfig | undefined
 ): void {
   const builtin = builtinTools(config);
   if (builtin.length === 0) {
     return;
   }
   const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
-  if (runtime === "cloud") {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: agentPath,
-      message:
-        "builtinTools are in-process server tools and are not available on cloud agents; they are skipped.",
-    });
-    return;
-  }
   const authored = new Set(tools.map((tool) => tool.name));
   for (const tool of builtin) {
     if (authored.has(tool.name)) {
@@ -1234,7 +1222,6 @@ function warnCloudRuntimeLimitations(
   ctx: DiscoveryContext,
   agentDir: string,
   counts: {
-    serverTools: number;
     agentTools: number;
     skills: number;
     seedFiles: number;
@@ -1250,14 +1237,6 @@ function warnCloudRuntimeLimitations(
         'runtime: "cloud" usually needs a `cloud` block (e.g. repos / env). Without it the Cursor cloud API may reject create.',
     });
   }
-  if (counts.serverTools > 0) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, join(agentDir, "tools")),
-      message:
-        'In-process tools (execution: "server", the default) are not available on cloud agents. Use execution: "agent", MCP connections, or tools that already live in the cloud workspace.',
-    });
-  }
   if (counts.agentTools > 0) {
     ctx.diagnostics.push({
       severity: "warning",
@@ -1647,19 +1626,6 @@ async function appendArtifactTool(
     (await findModuleFile(agentDir, "artifacts")) ??
       join(agentDir, "artifacts.ts")
   );
-  // TODO(artifacts-cloud): on cloud runtimes, ship tag_artifact as an
-  // execution: "agent" script and have the host fold its action.result
-  // stream events into artifact records — agent-tool calls already surface
-  // durably in the session stream.
-  if (agent.runtime === "cloud") {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: artifactsPath,
-      message:
-        "tag_artifact is an in-process server tool (like builtinTools) and is not available on cloud agents; it is skipped.",
-    });
-    return;
-  }
   if (agent.tools.some((t) => t.name === TAG_ARTIFACT_TOOL_NAME)) {
     ctx.diagnostics.push({
       severity: "warning",

package/src/internal/init-project.ts

@@ -206,7 +206,7 @@ export default memoryHook();
   };
 }
 
-function isEexist(error: unknown): boolean {
+export function isEexist(error: unknown): boolean {
   return (
     error !== null &&
     typeof error === "object" &&