@cursor/july 0.1.101 → 0.1.103

package/src/internal/testing/scm-continuation-fixtures.ts

@@ -0,0 +1,286 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/july` into the control plane.
+ */
+
+export interface ScmContinuationFixture {
+  name: string;
+  kind: "gitlab" | "bitbucket";
+  /** Conversation type the channel's `<kind>.<type>/v2` selector names. */
+  type: "gitlab-mr" | "bitbucket-pr";
+  /**
+   * Mailbox event name. Bitbucket Data Center deliveries arrive with their
+   * Cloud-normalized key (`pr:opened` → `pullrequest:created`) next to the
+   * raw DC payload.
+   */
+  eventType: string;
+  payload: Record<string, unknown>;
+  /** `cont:` key, or `undefined` when the delivery stamps `evt:`. */
+  expectedKey: string | undefined;
+}
+
+export interface ScmDefaultSelectorFixture {
+  kind: "gitlab" | "bitbucket";
+  eventTypes: readonly string[];
+  expected: string;
+}
+
+const GITLAB_PROJECT = {
+  id: 1234,
+  name: "api",
+  path_with_namespace: "Acme/platform/api",
+  web_url: "https://gitlab.com/Acme/platform/api",
+  default_branch: "main",
+};
+
+const GITLAB_MERGE_REQUEST = {
+  id: 9001,
+  iid: 42,
+  title: "Add widgets",
+  state: "opened",
+  source_branch: "feature/widgets",
+  target_branch: "main",
+  url: "https://gitlab.com/Acme/platform/api/-/merge_requests/42",
+  last_commit: { id: "0123456789abcdef0123456789abcdef01234567" },
+};
+
+const BITBUCKET_CLOUD_REPOSITORY = {
+  type: "repository",
+  full_name: "acme/widgets",
+  name: "widgets",
+  uuid: "{5f2d1d5e-6d66-4f5b-9d3e-1b6e5b1c2f3a}",
+  workspace: { slug: "acme", uuid: "{a4f1c5d0-1111-4a2b-8c3d-9e0f1a2b3c4d}" },
+  links: { html: { href: "https://bitbucket.org/acme/widgets" } },
+};
+
+const BITBUCKET_DC_REPOSITORY = {
+  slug: "widgets",
+  id: 17,
+  name: "widgets",
+  project: { key: "ACME", id: 3, name: "Acme" },
+};
+
+export const SCM_CONTINUATION_FIXTURES: readonly ScmContinuationFixture[] = [
+  {
+    name: "gitlab merge_request open",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: { ...GITLAB_MERGE_REQUEST, action: "open" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab merge_request update (new commits)",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "merge_request",
+    payload: {
+      object_kind: "merge_request",
+      event_type: "merge_request",
+      user: { id: 7, username: "alice", name: "Alice" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        ...GITLAB_MERGE_REQUEST,
+        action: "update",
+        oldrev: "fedcba9876543210fedcba9876543210fedcba98",
+      },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 501,
+        note: "Looks good",
+        noteable_type: "MergeRequest",
+        noteable_id: 9001,
+      },
+      merge_request: GITLAB_MERGE_REQUEST,
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab note on issue",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "note",
+    payload: {
+      object_kind: "note",
+      event_type: "note",
+      user: { id: 8, username: "bob", name: "Bob" },
+      project: GITLAB_PROJECT,
+      object_attributes: {
+        id: 502,
+        note: "Tracking",
+        noteable_type: "Issue",
+        noteable_id: 300,
+      },
+      issue: { id: 300, iid: 9, title: "Bug" },
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab pipeline attached to a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 77, status: "success", sha: "0123456789ab" },
+      merge_request: { iid: 42, id: 9001, title: "Add widgets" },
+    },
+    expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+  },
+  {
+    name: "gitlab pipeline without a merge request",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "pipeline",
+    payload: {
+      object_kind: "pipeline",
+      project: GITLAB_PROJECT,
+      object_attributes: { id: 78, status: "success", sha: "0123456789ab" },
+      merge_request: null,
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "gitlab push",
+    kind: "gitlab",
+    type: "gitlab-mr",
+    eventType: "push",
+    payload: {
+      object_kind: "push",
+      event_name: "push",
+      ref: "refs/heads/main",
+      project: GITLAB_PROJECT,
+      commits: [],
+    },
+    expectedKey: undefined,
+  },
+  {
+    name: "bitbucket cloud pullrequest:created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      pullrequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        source: {
+          branch: { name: "feature/widgets" },
+          commit: { hash: "0123456789ab" },
+        },
+        destination: { branch: { name: "main" }, commit: { hash: "fedcba98" } },
+        links: {
+          html: { href: "https://bitbucket.org/acme/widgets/pull-requests/7" },
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket data center pr:opened (normalized to pullrequest:created)",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:created",
+    payload: {
+      eventKey: "pr:opened",
+      date: "2026-09-01T12:00:00+0000",
+      actor: { name: "alice", displayName: "Alice", id: 1 },
+      pullRequest: {
+        id: 7,
+        title: "Add widgets",
+        state: "OPEN",
+        open: true,
+        fromRef: {
+          id: "refs/heads/feature/widgets",
+          displayId: "feature/widgets",
+          latestCommit: "0123456789ab",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+        toRef: {
+          id: "refs/heads/main",
+          displayId: "main",
+          latestCommit: "fedcba98",
+          repository: BITBUCKET_DC_REPOSITORY,
+        },
+      },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud pullrequest:comment_created",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "pullrequest:comment_created",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Bob", uuid: "{u-2}" },
+      pullrequest: { id: 7, title: "Add widgets", state: "OPEN" },
+      comment: { id: 11, content: { raw: "Looks good" } },
+    },
+    expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+  },
+  {
+    name: "bitbucket cloud repo:push",
+    kind: "bitbucket",
+    type: "bitbucket-pr",
+    eventType: "repo:push",
+    payload: {
+      repository: BITBUCKET_CLOUD_REPOSITORY,
+      actor: { display_name: "Alice", uuid: "{u-1}" },
+      push: { changes: [] },
+    },
+    expectedKey: undefined,
+  },
+];
+
+export const SCM_DEFAULT_SELECTOR_FIXTURES: readonly ScmDefaultSelectorFixture[] =
+  [
+    { kind: "gitlab", eventTypes: ["merge_request"], expected: "gitlab.mr/v2" },
+    {
+      kind: "gitlab",
+      eventTypes: ["merge_request", "note"],
+      expected: "gitlab.mr/v2",
+    },
+    {
+      kind: "gitlab",
+      eventTypes: ["merge_request", "push"],
+      expected: "gitlab.none/v2",
+    },
+    {
+      kind: "bitbucket",
+      eventTypes: ["pullrequest:created", "pullrequest:updated"],
+      expected: "bitbucket.pr/v2",
+    },
+    {
+      kind: "bitbucket",
+      eventTypes: ["pullrequest:created", "repo:push"],
+      expected: "bitbucket.none/v2",
+    },
+  ];

package/src/internal/tool-catalog.ts

@@ -23,13 +23,16 @@ import type {
  * presentation concern is not worth the authoring surface).
  */
 const WELL_KNOWN_TOOL_TITLES: Readonly<Record<string, string>> = {
-  diff: "Show change diffs",
-  glob: "Find files by pattern",
-  grep: "Search file contents",
-  ls: "List a directory",
-  read: "Read a file",
+  Delete: "Delete a file",
+  Diff: "Show change diffs",
+  Glob: "Find files by pattern",
+  Grep: "Search file contents",
+  LS: "List a directory",
+  Read: "Read a file",
+  StrReplace: "Replace text in a file",
+  Write: "Write a file",
+  script: "Run a TypeScript program",
   search: "Search with a typed query",
-  write: "Write a file",
 };
 
 function catalogTitle(tool: DiscoveredTool): string | undefined {

package/src/internal/turn-cost.ts

@@ -28,6 +28,45 @@ export function modelSettingId(model: ModelSetting): string {
   return typeof model === "string" ? model : model.id;
 }
 
+/**
+ * This estimate-cost client treats OpenAI-compat usage as **provider-gross**
+ * (local playground: `prompt_tokens` includes `cachedPromptTokens`). Catalog
+ * `costForBaseTier` assumes Anthropic / billing-style disjoint nets and ADDs
+ * `cacheRead × cachedRate` on top of `input × inputRate`, so we send
+ * `input − cache` for Grok / xAI / GPT / o-series.
+ *
+ * Non-OpenAI-compat models are left alone. `input < cache` is only a
+ * defensive clamp (avoid a negative uncached count), not a detector for
+ * billed / openaiProxy-shaped tokens. Cloud catalog fallback with already-
+ * netted OpenAI-compat usage is out of scope here.
+ */
+export function isOpenAiCompatGrossCacheModel(model: ModelSetting): boolean {
+  const id = modelSettingId(model).toLowerCase();
+  return (
+    id.includes("grok") ||
+    id.includes("xai") ||
+    id.includes("gpt") ||
+    /(^|[-_/])o[1-9]/.test(id)
+  );
+}
+
+export function toCatalogDisjointUsage(
+  usage: TurnUsage,
+  model?: ModelSetting
+): TurnUsage {
+  if (model === undefined || !isOpenAiCompatGrossCacheModel(model)) {
+    return usage;
+  }
+  const cachedTokens = usage.cacheReadTokens + usage.cacheWriteTokens;
+  if (cachedTokens === 0 || usage.inputTokens < cachedTokens) {
+    return usage;
+  }
+  return {
+    ...usage,
+    inputTokens: usage.inputTokens - cachedTokens,
+  };
+}
+
 export function roundCostUsd(usd: number): number {
   return Math.round(usd * 1e6) / 1e6;
 }
@@ -67,6 +106,10 @@ export async function estimateTurnCostFromApi(
     return undefined;
   }
   const model = modelSettingId(input.model);
+  const catalogUsage =
+    input.usage === undefined
+      ? undefined
+      : toCatalogDisjointUsage(input.usage, input.model);
   const response = await fetch(
     `${cursorExternalApiUrl()}/v1/models/estimate-cost`,
     {
@@ -77,10 +120,10 @@ export async function estimateTurnCostFromApi(
       },
       body: JSON.stringify({
         model,
-        inputTokens: input.usage?.inputTokens,
-        outputTokens: input.usage?.outputTokens,
-        cacheReadTokens: input.usage?.cacheReadTokens,
-        cacheWriteTokens: input.usage?.cacheWriteTokens,
+        inputTokens: catalogUsage?.inputTokens,
+        outputTokens: catalogUsage?.outputTokens,
+        cacheReadTokens: catalogUsage?.cacheReadTokens,
+        cacheWriteTokens: catalogUsage?.cacheWriteTokens,
         agentId: input.agentId,
         conversationId: input.conversationId,
         runId: input.runId,

package/src/internal/v2-hosting.ts

@@ -0,0 +1,38 @@
+import type { AgentArchitecture } from "../types.js";
+import {
+  type CursorManagedV2StoreIds,
+  requireCursorManagedV2StoreIdsSync,
+} from "./cursor/hosted-store-secrets.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+
+export type AgentV2Hosting =
+  | { kind: "not-v2" }
+  | { kind: "self-hosted" }
+  | {
+      kind: "cursor-managed";
+      resolveStoreIds: () => CursorManagedV2StoreIds;
+    };
+
+/**
+ * Close the architecture/hosting inputs into a compiler-owned union.
+ *
+ * Managed freeze processes exist before task bind, so store resolution stays
+ * lazy. Consumers can branch once on `kind`; managed storage operations then
+ * receive a resolver whose successful result always contains both ids.
+ */
+export function resolveAgentV2Hosting(input: {
+  architecture: AgentArchitecture | undefined;
+  env?: NodeJS.ProcessEnv;
+}): AgentV2Hosting {
+  if (input.architecture !== "v2") {
+    return { kind: "not-v2" };
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    return { kind: "self-hosted" };
+  }
+  return {
+    kind: "cursor-managed",
+    resolveStoreIds: () => requireCursorManagedV2StoreIdsSync(env),
+  };
+}

package/src/internal/workspace-sync.ts

@@ -0,0 +1,55 @@
+/**
+ * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
+ * cloud-runtime turns read them from the store mount (the first cloud prompt
+ * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
+ * write store-root `workspace/<path>`. Local `serve`/`run` with
+ * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
+ * USER store.
+ */
+
+import { readFile } from "node:fs/promises";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import { MEMORY_DIR_NAME } from "../memory.js";
+import type { SeedFile } from "../types.js";
+import { mirrorToStore, storeRelPath } from "./store-mirror.js";
+
+/**
+ * Mirror the seed tree onto the store at its authored relative paths and
+ * delete keys no seed claims so redeploys drop removed files. Every seed
+ * loads and validates before the store is touched.
+ */
+export async function syncWorkspaceToStore(args: {
+  sink: FileSink;
+  seedFiles: readonly SeedFile[];
+  /** Store-root directory that holds the seed tree. Defaults to `workspace/`. */
+  workspacePrefix?: string;
+}): Promise<void> {
+  const workspacePrefix =
+    args.workspacePrefix ?? agentStoreKeys.workspacePrefix();
+  const desired = new Map<string, Uint8Array>();
+  for (const seed of args.seedFiles) {
+    desired.set(
+      agentStoreKeys.workspaceFile(
+        seedRelPath(seed.relativePath),
+        workspacePrefix
+      ),
+      await readFile(seed.sourcePath)
+    );
+  }
+  await mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
+}
+
+/**
+ * Same reservation as local materialization's `resolveWorkspaceWritePath`:
+ * `memory/` is the shared cross-session journal, so a seed under it fails
+ * the sync exactly as it fails a local first turn.
+ */
+function seedRelPath(relPath: string): string {
+  const rel = storeRelPath(relPath, "workspace file");
+  if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
+    throw new Error(
+      `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`
+    );
+  }
+  return rel;
+}

package/src/internal/workspace.ts

@@ -66,6 +66,20 @@ export function buildCloudMemorySection(agentName: string): string {
   ].join("\n");
 }
 
+/**
+ * First-turn preamble section for cloud-runtime sessions with authored
+ * `agent/sandbox/workspace/**` seeds. Cloud VMs get no materialized
+ * workspace; the seeds are synced onto the store mount instead (see
+ * `syncWorkspaceToStore`), so the model has to be told where they are.
+ */
+export function buildCloudWorkspaceSection(dir: string): string {
+  return [
+    "## Workspace files",
+    "",
+    `The agent's authored workspace files live at \`${dir}\` on this machine. Relative paths in your instructions that name these files resolve under that directory rather than your working directory. Read them with your normal file tools. The directory is shared across sessions, so copy a file into your working directory before editing it.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;