@cursor/july 0.1.102 → 0.1.104

package/src/internal/continuation-identity.ts

@@ -3,14 +3,16 @@
  * on a channel constructor stays `/v1` (engine pack minting) so existing
  * agents do not change: `githubChannel()` → `github.pr/v1`, `slackChannel()`
  * → `slack.thread/v1`, `originChannel()` → `origin.pr/v1`,
- * `deploymentsChannel()` → `deployments.none/v1`, `httpChannel()` →
+ * `deploymentsChannel()` → `deployments.none/v1`, `changeMonitorsChannel()`
+ * → `none/v1`, `issuesChannel()` → `none/v1`, `httpChannel()` →
  * `none/v1`.
  *
  * Opt the whole agent into the v2 control plane with
  * `defineAgent({ architecture: "v2" })`. That stamps `/v2` defaults from
  * the channel kind and declared events (`github.pr/v2`, `github.issue/v2`,
  * `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
- * `deployments.deployment/v2`, …) onto every channel that omitted a
+ * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
+ * `issues.issue/v2`, …) onto every channel that omitted a
  * selector. An explicit per-channel selector still overrides. JSONPath
  * and per-agent format strings are rejected.
  */
@@ -22,7 +24,22 @@ export type ConversationType =
   | "issue"
   | "thread"
   | "origin-pr"
-  | "deployment";
+  | "gitlab-mr"
+  | "bitbucket-pr"
+  | "deployment"
+  | "change-monitor-checkpoint"
+  | "factory-issue";
+
+export type ContinuationKind =
+  | "github"
+  | "slack"
+  | "origin"
+  | "gitlab"
+  | "bitbucket"
+  | "deployments"
+  | "change_monitors"
+  | "issues"
+  | "http";
 
 export const CONTINUATION_SELECTORS = [
   "github.pr/v1",
@@ -36,9 +53,15 @@ 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",
+  "change_monitors.checkpoint/v2",
+  "issues.issue/v2",
   "none/v1",
   "none/v2",
 ] as const;
@@ -52,7 +75,7 @@ export type ParsedContinuation = {
   selector: ContinuationSelector;
   version: 1 | 2;
   type: ConversationType | "none";
-  kind: "github" | "slack" | "origin" | "deployments" | "http";
+  kind: ContinuationKind;
 };
 
 export type ContinuationClaim = {
@@ -61,7 +84,9 @@ export type ContinuationClaim = {
     | { owner: string; repo: string; number: number }
     | { channelId: string; threadTs: string }
     | { fullName: string; number: number }
-    | { deploymentId: string };
+    | { deploymentId: string }
+    | { checkpointName: string }
+    | { issueName: string };
 };
 
 export type MailboxContinuation = {
@@ -70,7 +95,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 +129,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 +141,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",
@@ -124,6 +177,18 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
     events: ["deployment.created", "deployment.succeeded", "deployment.failed"],
     format: "deployments:{deploymentId}",
   },
+  {
+    type: "change-monitor-checkpoint",
+    kind: "change_monitors",
+    events: ["checkpoint.created"],
+    format: "change_monitors:{checkpointName}",
+  },
+  {
+    type: "factory-issue",
+    kind: "issues",
+    events: ["issue.created"],
+    format: "issues:{issueName}",
+  },
 ] as const;
 
 export class V2EngineError extends Error {
@@ -147,6 +212,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": {
@@ -154,13 +223,21 @@ const SELECTOR_FIELDS: {
     type: "deployment",
     kind: "deployments",
   },
+  "change_monitors.checkpoint/v2": {
+    version: 2,
+    type: "change-monitor-checkpoint",
+    kind: "change_monitors",
+  },
+  "issues.issue/v2": {
+    version: 2,
+    type: "factory-issue",
+    kind: "issues",
+  },
   "none/v1": { version: 1, type: "none", kind: "http" },
   "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);
 }
 
@@ -189,14 +266,66 @@ export function defaultContinuationSelector(
     case "slack":
       return "slack.thread/v2";
     case "origin":
-      return originV2Default(eventTypes);
+      return membershipOrNone(
+        eventTypes,
+        "origin-pr",
+        "origin.pr/v2",
+        "origin.none/v2"
+      );
+    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);
+      return membershipOrNone(
+        eventTypes,
+        "deployment",
+        "deployments.deployment/v2",
+        "deployments.none/v2"
+      );
+    case "change_monitors":
+      return membershipOrNone(
+        eventTypes,
+        "change-monitor-checkpoint",
+        "change_monitors.checkpoint/v2",
+        "none/v2"
+      );
+    case "issues":
+      return membershipOrNone(
+        eventTypes,
+        "factory-issue",
+        "issues.issue/v2",
+        "none/v2"
+      );
     default:
       return "none/v2";
   }
 }
 
+/** 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 ?? []);
@@ -210,24 +339,50 @@ function githubV2Default(eventTypes?: readonly string[]): ContinuationSelector {
   return "github.pr/v2";
 }
 
-function originV2Default(eventTypes?: readonly string[]): ContinuationSelector {
-  const events = eventTypes ?? [];
-  const prEvents = new Set(builtinForType("origin-pr")?.events ?? []);
-  if (events.some((event) => !prEvents.has(event))) {
-    return "origin.none/v2";
-  }
-  return "origin.pr/v2";
+const OMITTED_V2_TYPED_TYPE = {
+  github: "pr",
+  origin: "origin-pr",
+  deployments: "deployment",
+  change_monitors: "change-monitor-checkpoint",
+  issues: "factory-issue",
+} as const satisfies Partial<Record<string, ConversationType>>;
+
+/** Typed membership used when an omitted `/v2` selector becomes type `none`. */
+export function omittedV2TypedType(kind: string): ConversationType | undefined {
+  return OMITTED_V2_TYPED_TYPE[kind as keyof typeof OMITTED_V2_TYPED_TYPE];
 }
 
-function deploymentsV2Default(
+/**
+ * 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[]
-): ContinuationSelector {
+):
+  | { selector: ContinuationSelector; unexpected: readonly string[] }
+  | undefined {
   const events = eventTypes ?? [];
-  const deploymentEvents = new Set(builtinForType("deployment")?.events ?? []);
-  if (events.some((event) => !deploymentEvents.has(event))) {
-    return "deployments.none/v2";
+  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 typedType = omittedV2TypedType(kind);
+  const typed = typedType === undefined ? undefined : builtinForType(typedType);
+  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 "deployments.deployment/v2";
+  return { selector, unexpected };
 }
 
 export function parseContinuationSelector(
@@ -239,7 +394,7 @@ export function parseContinuationSelector(
   return { selector, ...SELECTOR_FIELDS[selector] };
 }
 
-export function resolveContinuation(
+function resolveContinuation(
   raw?: ContinuationIdentity,
   kind?: string
 ): ParsedContinuation {
@@ -273,17 +428,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;
@@ -291,6 +446,8 @@ export function formatConversationKey(
     channelId?: string;
     threadTs?: string;
     deploymentId?: string;
+    checkpointName?: string;
+    issueName?: string;
   }
 ): string {
   switch (type) {
@@ -300,10 +457,18 @@ 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":
       return `deployments:${fields.deploymentId}`;
+    case "change-monitor-checkpoint":
+      return `change_monitors:${fields.checkpointName}`;
+    case "factory-issue":
+      return `issues:${fields.issueName}`;
   }
 }
 
@@ -325,9 +490,27 @@ export function mintClaim(claim: ContinuationClaim): string {
       }
       return `cont:${formatConversationKey("deployment", resource)}`;
     }
+    case "change-monitor-checkpoint": {
+      const resource = claim.resource;
+      if (!("checkpointName" in resource)) {
+        throw new V2EngineError(
+          "v2: change-monitor-checkpoint claim requires checkpointName"
+        );
+      }
+      return `cont:${formatConversationKey("change-monitor-checkpoint", resource)}`;
+    }
+    case "factory-issue": {
+      const resource = claim.resource;
+      if (!("issueName" in resource)) {
+        throw new V2EngineError("v2: factory-issue claim requires issueName");
+      }
+      return `cont:${formatConversationKey("factory-issue", resource)}`;
+    }
     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 +524,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,8 +611,26 @@ 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);
+      return extractNamedResource("deployment", "deploymentId", payload);
+    case "change-monitor-checkpoint":
+      return extractNamedResource(
+        "change-monitor-checkpoint",
+        "checkpointName",
+        payload,
+        "checkpoint"
+      );
+    case "factory-issue":
+      return extractNamedResource(
+        "factory-issue",
+        "issueName",
+        payload,
+        "issue"
+      );
   }
 }
 
@@ -629,13 +837,108 @@ function originExtractRecord(
   return record;
 }
 
-function extractDeployment(payload: unknown): string | undefined {
+/**
+ * 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 extractNamedResource(
+  type: "deployment" | "change-monitor-checkpoint" | "factory-issue",
+  field: "deploymentId" | "checkpointName" | "issueName",
+  payload: unknown,
+  wrapper?: "checkpoint" | "issue"
+): string | undefined {
   const record = asRecord(payload);
-  const deploymentId = nonEmpty(record?.deploymentId);
-  if (deploymentId === undefined) {
+  const source = wrapper === undefined ? record : asRecord(record?.[wrapper]);
+  const value = nonEmpty(source?.[wrapper === undefined ? field : "name"]);
+  if (value === undefined) {
     return undefined;
   }
-  return `cont:${formatConversationKey("deployment", { deploymentId })}`;
+  return `cont:${formatConversationKey(type, { [field]: value })}`;
 }
 
 function githubFullName(payload: Record<string, unknown>): string | undefined {

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 {