@cursor/july 0.1.102 → 0.1.103

package/src/internal/continuation-identity.ts

@@ -22,8 +22,19 @@ export type ConversationType =
   | "issue"
   | "thread"
   | "origin-pr"
+  | "gitlab-mr"
+  | "bitbucket-pr"
   | "deployment";
 
+export type ContinuationKind =
+  | "github"
+  | "slack"
+  | "origin"
+  | "gitlab"
+  | "bitbucket"
+  | "deployments"
+  | "http";
+
 export const CONTINUATION_SELECTORS = [
   "github.pr/v1",
   "github.pr/v2",
@@ -36,6 +47,10 @@ export const CONTINUATION_SELECTORS = [
   "origin.pr/v1",
   "origin.pr/v2",
   "origin.none/v2",
+  "gitlab.mr/v2",
+  "gitlab.none/v2",
+  "bitbucket.pr/v2",
+  "bitbucket.none/v2",
   "deployments.none/v1",
   "deployments.none/v2",
   "deployments.deployment/v2",
@@ -52,7 +67,7 @@ export type ParsedContinuation = {
   selector: ContinuationSelector;
   version: 1 | 2;
   type: ConversationType | "none";
-  kind: "github" | "slack" | "origin" | "deployments" | "http";
+  kind: ContinuationKind;
 };
 
 export type ContinuationClaim = {
@@ -70,7 +85,7 @@ export type MailboxContinuation = {
 
 export type ContinuationBuiltin = {
   type: ConversationType;
-  kind: "github" | "slack" | "origin" | "deployments";
+  kind: Exclude<ContinuationKind, "http">;
   events: readonly string[];
   format: string;
 };
@@ -104,6 +119,9 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
   {
     type: "origin-pr",
     kind: "origin",
+    // Public webhook deliveries carry `pullRequest.number` + repository
+    // (`owner.slug` / `name`); keep in lockstep with the control plane's
+    // `conversation/origin.ts`.
     events: [
       "pull_request.created",
       "pull_request.published",
@@ -113,9 +131,34 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
       "pull_request.merged",
       "pull_request.comment.created",
       "pull_request.review.submitted",
+      "pull_request.metadata.updated",
     ],
     format: "origin-pr:{fullName}#{number}",
   },
+  {
+    type: "gitlab-mr",
+    kind: "gitlab",
+    // GitLab `object_kind`s that carry a merge request: `note` only when
+    // `noteable_type` is MergeRequest, `pipeline` only with `merge_request`.
+    events: ["merge_request", "note", "pipeline"],
+    format: "gitlab-mr:{fullName}!{number}",
+  },
+  {
+    type: "bitbucket-pr",
+    kind: "bitbucket",
+    // Cloud vocabulary; Data Center keys are normalized before the stamp.
+    events: [
+      "pullrequest:created",
+      "pullrequest:updated",
+      "pullrequest:approved",
+      "pullrequest:unapproved",
+      "pullrequest:changes_request_created",
+      "pullrequest:fulfilled",
+      "pullrequest:rejected",
+      "pullrequest:comment_created",
+    ],
+    format: "bitbucket-pr:{fullName}#{number}",
+  },
   {
     type: "deployment",
     kind: "deployments",
@@ -147,6 +190,10 @@ const SELECTOR_FIELDS: {
   "origin.pr/v1": { version: 1, type: "origin-pr", kind: "origin" },
   "origin.pr/v2": { version: 2, type: "origin-pr", kind: "origin" },
   "origin.none/v2": { version: 2, type: "none", kind: "origin" },
+  "gitlab.mr/v2": { version: 2, type: "gitlab-mr", kind: "gitlab" },
+  "gitlab.none/v2": { version: 2, type: "none", kind: "gitlab" },
+  "bitbucket.pr/v2": { version: 2, type: "bitbucket-pr", kind: "bitbucket" },
+  "bitbucket.none/v2": { version: 2, type: "none", kind: "bitbucket" },
   "deployments.none/v1": { version: 1, type: "none", kind: "deployments" },
   "deployments.none/v2": { version: 2, type: "none", kind: "deployments" },
   "deployments.deployment/v2": {
@@ -158,9 +205,7 @@ const SELECTOR_FIELDS: {
   "none/v2": { version: 2, type: "none", kind: "http" },
 };
 
-export function isContinuationSelector(
-  value: string
-): value is ContinuationSelector {
+function isContinuationSelector(value: string): value is ContinuationSelector {
   return Object.hasOwn(SELECTOR_FIELDS, value);
 }
 
@@ -190,6 +235,20 @@ export function defaultContinuationSelector(
       return "slack.thread/v2";
     case "origin":
       return originV2Default(eventTypes);
+    case "gitlab":
+      return membershipOrNone(
+        eventTypes,
+        "gitlab-mr",
+        "gitlab.mr/v2",
+        "gitlab.none/v2"
+      );
+    case "bitbucket":
+      return membershipOrNone(
+        eventTypes,
+        "bitbucket-pr",
+        "bitbucket.pr/v2",
+        "bitbucket.none/v2"
+      );
     case "deployments":
       return deploymentsV2Default(eventTypes);
     default:
@@ -197,6 +256,20 @@ export function defaultContinuationSelector(
   }
 }
 
+/** Typed selector when every declared event is in the type's membership. */
+function membershipOrNone(
+  eventTypes: readonly string[] | undefined,
+  type: ConversationType,
+  typed: ContinuationSelector,
+  none: ContinuationSelector
+): ContinuationSelector {
+  const allowed = new Set(builtinForType(type)?.events ?? []);
+  if ((eventTypes ?? []).some((event) => !allowed.has(event))) {
+    return none;
+  }
+  return typed;
+}
+
 function githubV2Default(eventTypes?: readonly string[]): ContinuationSelector {
   const events = eventTypes ?? [];
   const issueEvents = new Set(builtinForType("issue")?.events ?? []);
@@ -219,6 +292,45 @@ function originV2Default(eventTypes?: readonly string[]): ContinuationSelector {
   return "origin.pr/v2";
 }
 
+/**
+ * Omitted `/v2` default became type `none` because a declared event sits
+ * outside the kind's typed membership. Validate warns; handshake stays
+ * silent on omitted selectors (type `none` is always admitted).
+ */
+export function omittedV2MembershipDowngrade(
+  kind: string,
+  eventTypes?: readonly string[]
+):
+  | { selector: ContinuationSelector; unexpected: readonly string[] }
+  | undefined {
+  const events = eventTypes ?? [];
+  if (events.length === 0) {
+    return undefined;
+  }
+  const selector = defaultContinuationSelector(kind, "v2", events);
+  const parsed = parseContinuationSelector(selector);
+  if (parsed === undefined || parsed.type !== "none") {
+    return undefined;
+  }
+  const typed =
+    kind === "github"
+      ? builtinForType("pr")
+      : kind === "origin"
+        ? builtinForType("origin-pr")
+        : kind === "deployments"
+          ? builtinForType("deployment")
+          : undefined;
+  if (typed === undefined) {
+    return undefined;
+  }
+  const allowed = new Set(typed.events);
+  const unexpected = events.filter((event) => !allowed.has(event));
+  if (unexpected.length === 0) {
+    return undefined;
+  }
+  return { selector, unexpected };
+}
+
 function deploymentsV2Default(
   eventTypes?: readonly string[]
 ): ContinuationSelector {
@@ -239,7 +351,7 @@ export function parseContinuationSelector(
   return { selector, ...SELECTOR_FIELDS[selector] };
 }
 
-export function resolveContinuation(
+function resolveContinuation(
   raw?: ContinuationIdentity,
   kind?: string
 ): ParsedContinuation {
@@ -273,17 +385,17 @@ export function isV2DurableContinuationKey(key: string): boolean {
   return key.startsWith("cont:") || key.startsWith("evt:");
 }
 
-export function newEvtKey(): string {
+function newEvtKey(): string {
   return `evt:${randomBytes(16).toString("hex")}`;
 }
 
-export function builtinForType(
+function builtinForType(
   type: ConversationType
 ): ContinuationBuiltin | undefined {
   return BUILTINS.find((builtin) => builtin.type === type);
 }
 
-export function formatConversationKey(
+function formatConversationKey(
   type: ConversationType,
   fields: {
     fullName?: string;
@@ -300,6 +412,10 @@ export function formatConversationKey(
       return `github-issue:${fields.fullName}#${fields.number}`;
     case "origin-pr":
       return `origin-pr:${fields.fullName}#${fields.number}`;
+    case "gitlab-mr":
+      return `gitlab-mr:${fields.fullName}!${fields.number}`;
+    case "bitbucket-pr":
+      return `bitbucket-pr:${fields.fullName}#${fields.number}`;
     case "thread":
       return `${fields.channelId}:${fields.threadTs}`;
     case "deployment":
@@ -327,7 +443,9 @@ export function mintClaim(claim: ContinuationClaim): string {
     }
     case "pr":
     case "issue":
-    case "origin-pr": {
+    case "origin-pr":
+    case "gitlab-mr":
+    case "bitbucket-pr": {
       const resource = claim.resource;
       const fullName =
         "fullName" in resource
@@ -341,8 +459,15 @@ export function mintClaim(claim: ContinuationClaim): string {
           `v2: ${claim.type} claim requires repository and number`
         );
       }
+      // GitLab paths and Bitbucket project keys arrive in API-native casing;
+      // the webhook extractors lowercase them, so the claim must too or the
+      // two mint different keys for the same MR / PR.
+      const caseFolded =
+        claim.type === "gitlab-mr" || claim.type === "bitbucket-pr"
+          ? fullName.toLowerCase()
+          : fullName;
       return `cont:${formatConversationKey(claim.type, {
-        fullName,
+        fullName: caseFolded,
         number,
       })}`;
     }
@@ -421,6 +546,10 @@ export function extractContinuation(
       return extractSlack(payload);
     case "origin-pr":
       return extractOrigin(payload);
+    case "gitlab-mr":
+      return extractGitlab(eventName, payload);
+    case "bitbucket-pr":
+      return extractBitbucket(payload);
     case "deployment":
       return extractDeployment(payload);
   }
@@ -629,6 +758,95 @@ function originExtractRecord(
   return record;
 }
 
+/**
+ * GitLab merge request identity: `project.path_with_namespace` (nested
+ * groups keep their slashes; lowercased like the scope key) plus the MR
+ * `iid`. `merge_request` reads `object_attributes.iid`; `note` binds only
+ * MR notes (`noteable_type: "MergeRequest"`); `pipeline` binds only when
+ * the payload carries a `merge_request`.
+ */
+function extractGitlab(
+  eventName: string,
+  payload: unknown
+): string | undefined {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return undefined;
+  }
+  const fullName = nonEmpty(
+    asRecord(record.project)?.path_with_namespace
+  )?.toLowerCase();
+  if (fullName === undefined) {
+    return undefined;
+  }
+  let number: number | undefined;
+  switch (eventName) {
+    case "merge_request":
+      number = positiveInt(asRecord(record.object_attributes)?.iid);
+      break;
+    case "note":
+      if (
+        asRecord(record.object_attributes)?.noteable_type !== "MergeRequest"
+      ) {
+        return undefined;
+      }
+      number = positiveInt(asRecord(record.merge_request)?.iid);
+      break;
+    case "pipeline":
+      number = positiveInt(asRecord(record.merge_request)?.iid);
+      break;
+    default:
+      return undefined;
+  }
+  if (number === undefined) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey("gitlab-mr", { fullName, number })}`;
+}
+
+/**
+ * Bitbucket pull request identity from either dialect. Cloud payloads carry
+ * `repository.full_name` + `pullrequest.id`; Data Center payloads carry
+ * `pullRequest.id` and the repo under `pullRequest.toRef.repository`
+ * (`project.key/slug`). Lowercased so a Cloud/DC pair for one logical PR
+ * shares a key.
+ */
+function extractBitbucket(payload: unknown): string | undefined {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return undefined;
+  }
+  const pullRequest =
+    asRecord(record.pullrequest) ?? asRecord(record.pullRequest);
+  const number = positiveInt(pullRequest?.id);
+  const fullName = bitbucketFullName(
+    asRecord(record.repository) ??
+      asRecord(asRecord(pullRequest?.toRef)?.repository)
+  );
+  if (number === undefined || fullName === undefined) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey("bitbucket-pr", { fullName, number })}`;
+}
+
+function bitbucketFullName(
+  repository: Record<string, unknown> | undefined
+): string | undefined {
+  if (repository === undefined) {
+    return undefined;
+  }
+  const cloud = nonEmpty(repository.full_name);
+  if (cloud !== undefined) {
+    return cloud.toLowerCase();
+  }
+  const projectKey = nonEmpty(asRecord(repository.project)?.key);
+  const slug = nonEmpty(repository.slug);
+  if (projectKey === undefined || slug === undefined) {
+    return undefined;
+  }
+  return `${projectKey}/${slug}`.toLowerCase();
+}
+
 function extractDeployment(payload: unknown): string | undefined {
   const record = asRecord(payload);
   const deploymentId = nonEmpty(record?.deploymentId);

package/src/internal/conversation-mirror.ts

@@ -395,9 +395,10 @@ export function selectConversationMirror(input: {
     sink: cursorHostedFiles({
       resolveStoreSourceId: () =>
         hosting.resolveStoreIds().frameworkStoreSourceId,
-      // Full chain (env → key file → stored login): frozen engines listen
-      // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
-      // is constructed.
+      // Full chain (env → key file → stored login), resolved lazily: frozen
+      // engines listen unsigned and only gain a credential at task time,
+      // after this sink is constructed. Hosted deliveries have consumed the
+      // bind file into CURSOR_API_KEY by then, so this resolves from env.
       resolveApiKey: () => resolveApiKeySync()?.apiKey,
     }),
     agentName: input.project.name,

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

@@ -1,6 +1,6 @@
 /**
  * Types for `convertWorkflow` — the pure automation → agentsdk project
- * converter behind `agent-serve convert-automation`.
+ * converter behind `agent-sdk convert-automation`.
  *
  * The workflow arrives as generic proto3 JSON (lowerCamelCase field names,
  * enum value names as strings) produced by the backend export endpoint

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

@@ -28,6 +28,7 @@ import type {
 } from "../../types.js";
 import { isCursorAccountTransport } from "../../types.js";
 import { probeConnectorAuthUrls } from "../cursor-account-mcp-auth.js";
+import { describeError } from "../describe-error.js";
 import { LOG_PREFIX } from "../distribution.js";
 import { handleStatelessMcpRequest } from "../mcp-endpoint.js";
 import { isLoopbackAddress } from "../net.js";
@@ -560,10 +561,6 @@ function trimTrailingSlash(url: string): string {
   return url.endsWith("/") ? url.slice(0, -1) : url;
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export interface CursorAccountMcpWarningServer {
   serverIdentifier: string;
   status: string;

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

@@ -17,6 +17,8 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import type { McpToolAnnotations } from "../../types.js";
+import { describeError } from "../describe-error.js";
+import { CLI_COMMAND_NAME as CLI } from "../distribution.js";
 import { boundedToolAnnotations } from "../mcp-host.js";
 import {
   CURSOR_SESSION_EXCHANGE_PATH,
@@ -300,9 +302,10 @@ export interface CursorBackendClientOptions {
   backendUrl: string;
   apiKey: string;
   /**
-   * Re-read the key on each authenticated call. Hosted freeze listens
-   * unsigned and the binder drops the key after restore; a constructor-frozen
-   * key would miss that bind.
+   * Re-resolve the key on each authenticated call. Hosted freeze listens
+   * unsigned and only gains a credential at task time (hosted deliveries
+   * consume the bind file into `CURSOR_API_KEY` before authored work); a
+   * constructor-frozen key would miss that bind.
    */
   getApiKey?: () => string;
   logger?: (line: string) => void;
@@ -607,7 +610,7 @@ export class CursorBackendClient {
         }
         throw new CursorBackendError(
           error.status === 401
-            ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+            ? `The Cursor API key was rejected. Run \`${CLI} login\` again or update CURSOR_API_KEY.`
             : `Cursor API key exchange failed (${error.status}).`,
           error.status
         );
@@ -623,7 +626,7 @@ export class CursorBackendClient {
 
 /**
  * Mint a named user API key from a short-lived login session token. Used
- * exactly once per `agent-serve login`; the session token is then discarded.
+ * exactly once per `agent-sdk login`; the session token is then discarded.
  */
 export async function createUserApiKeyWithSessionToken(args: {
   backendUrl: string;
@@ -867,7 +870,7 @@ function describeGithubTokenHttpFailure(
   if (status === 401) {
     return `The Cursor API key was rejected${
       detail === undefined ? "" : `: ${detail}`
-    }. Run \`agent-serve login\` again or update CURSOR_API_KEY.`;
+    }. Run \`${CLI} login\` again or update CURSOR_API_KEY.`;
   }
   if (detail !== undefined) {
     return detail;
@@ -899,10 +902,6 @@ function retryAfterMsFromResponse(response: Response): number | undefined {
   return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 /** Release undici/fetch connection slots on responses we will not parse. */
 async function drainResponseBody(response: Response): Promise<void> {
   try {

package/src/internal/cursor/bound-secret-file.ts

@@ -0,0 +1,108 @@
+/**
+ * Destroying a hosted v2 task-bind secret file after its value is in
+ * `process.env`.
+ *
+ * The bind files under `/run/cursor/secrets/` are an IPC channel, not a
+ * credential store: the control plane cannot set another process's
+ * environment, so it drops the value on tmpfs and July copies it into
+ * `process.env` before anything authored runs. Once that copy succeeds the
+ * on-disk value is pure liability — authored agent code runs in this pod and
+ * can read any world-readable path.
+ *
+ * Unlink is preferred. It is not always available: pod-daemon writes the
+ * files as root, and removing a directory entry needs write permission on
+ * `/run/cursor/secrets`, which is root-owned. Making that directory writable
+ * by the guest is not the fix — untrusted guest code could then plant a
+ * symlink that the next root-side bind write would follow. The binder instead
+ * relaxes the two secret files themselves so the guest can truncate them, and
+ * this module falls back to a zero-length overwrite. Both readers treat an
+ * empty bind file as unsigned.
+ */
+
+import {
+  closeSync,
+  fsyncSync,
+  ftruncateSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+} from "node:fs";
+
+/**
+ * What happened to a bind file. Only `readable` is a failure: the secret
+ * survived the consume and callers must not run authored code.
+ */
+export type BoundSecretFileDisposal =
+  /** Nothing recoverable was there — missing, empty, or unreadable already. */
+  | { state: "absent" }
+  /** Directory entry removed. */
+  | { state: "unlinked" }
+  /** Truncated to zero length and fsynced; an empty file remains. */
+  | { state: "wiped" }
+  /** Still recoverable by a later `readFile`. */
+  | { state: "readable"; reason: string };
+
+/**
+ * Whether a later `readFile` of this path could still recover a secret.
+ * A read failure counts as unrecoverable: this process just read the file
+ * during hydrate, so losing access to it means the content is gone.
+ */
+export function boundSecretFileIsReadable(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").trim() !== "";
+  } catch {
+    return false;
+  }
+}
+
+function errorReason(error: unknown): string {
+  const code = (error as { code?: unknown } | undefined)?.code;
+  return typeof code === "string" ? code : "unknown";
+}
+
+/**
+ * Remove a bind file's contents from disk, preferring unlink over an empty
+ * leftover. Callers must have already copied the value into `process.env`:
+ * this is destructive and there is no second bind until the control plane
+ * rewrites the file before the next hosted request.
+ */
+export function destroyBoundSecretFile(path: string): BoundSecretFileDisposal {
+  if (!boundSecretFileIsReadable(path)) {
+    // Nothing recoverable, so nothing to fail over. Still try to clear the
+    // empty leftover: whether that succeeds does not change the disposal,
+    // because there is no secret here either way.
+    try {
+      unlinkSync(path);
+    } catch {
+      // Already gone, or a directory the guest cannot write. Both are fine.
+    }
+    return { state: "absent" };
+  }
+  let unlinkReason: string | undefined;
+  try {
+    unlinkSync(path);
+    if (!boundSecretFileIsReadable(path)) {
+      return { state: "unlinked" };
+    }
+    unlinkReason = "recreated";
+  } catch (error) {
+    unlinkReason = errorReason(error);
+  }
+  try {
+    const fd = openSync(path, "r+");
+    try {
+      ftruncateSync(fd, 0);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (error) {
+    return {
+      state: "readable",
+      reason: `unlink ${unlinkReason}, truncate ${errorReason(error)}`,
+    };
+  }
+  return boundSecretFileIsReadable(path)
+    ? { state: "readable", reason: `unlink ${unlinkReason}, truncate no-op` }
+    : { state: "wiped" };
+}