@cursor/july 0.1.107 → 0.1.109

package/src/bin/agent-serve.ts

@@ -99,6 +99,7 @@ Usage:
   ${CLI} session     <sessionId> [--url <baseUrl> | --prod]
                           [--json | --text | --events] [--out <file.ndjson>]
                           [--slug <slug>] [--team <id>] [--dir <path>]
+                 or: --prod [<sessionId>] --slug <slug> --message "…" [--dry-run] [--as-of <instant>]
   ${CLI} cost        [sessionId] [--url <baseUrl> | --prod] [--json]
                           [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} playground  [--url <baseUrl> | --prod] [--session <id>] [--print]
@@ -108,6 +109,7 @@ Usage:
                           [--session <id>] [--continuation-token <t>]
                           [--events <file.ndjson>] [--no-events] [--text]
                           [--timeout-ms <n>] [--no-stream] [--slug <slug>] [--team <id>]
+                          [--dry-run] [--as-of <instant>]
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
@@ -197,6 +199,10 @@ Commands:
               Writes a single events.ndjson trace (summarize with trajectory).
               Streams tool calls and reply text to stderr when stderr is a TTY.
               Pass --prod to hit the hosted deployment instead of a local server.
+              On an AgentSDK v2 slug, --prod starts a hosted session through
+              the control plane (Temporal, no resident engine); --session
+              ses_… resumes that exact session. A 404 falls back to the v1
+              engine alias.
   trajectory  Summarize an events.ndjson file into a trajectory.
   call        Call an authored server tool deterministically (no model turn)
               via POST /v1/tools/:toolName. --session runs it inside an
@@ -311,8 +317,11 @@ Options:
                      ALB/ECS checks; use single when one agent is the whole host.
   --dev              Dev mode: mounts POST /v1/dev/schedules/:scheduleId and
                      disables the cron runner (dispatch schedules by hand).
-  --api-key          Cursor API key (defaults to CURSOR_API_KEY, then the
-                     stored \`${CLI} login\` credential).
+  --api-key          Cursor API key (defaults to CURSOR_API_KEY, then
+                     CURSOR_API_KEY_FILE — hosted default
+                     /run/cursor/secrets/CURSOR_API_KEY when unset —
+                     then CURSOR_SERVICE_ACCOUNT_KEY, then the stored
+                     \`${CLI} login\` credential).
   --key-name         login: label for the minted API key (defaults to
                      "${CLI} (<hostname>)").
   --state-root       Durable state directory (default <dir>/.agent-serve). Put it
@@ -361,6 +370,9 @@ Options:
                      --dir basename. Mutually exclusive with --url. Requires
                      \`${CLI} login\`. For eval, this is how you opt into the
                      persisted server-side batch (default is local).
+  --dry-run          run/session --prod: mark the hosted v2 turn non-mutating.
+  --as-of            run/session --prod: freeze the session clock at this
+                     timezone-bearing ISO-8601 instant.
   --once             logs: print current progress / log buffer once and exit
                      (default is to follow).
   --print            playground/docs: print the URL only; do not open a
@@ -571,6 +583,7 @@ async function main(argv: string[]): Promise<number> {
       context: { type: "string" },
       comment: { type: "string" },
       "dry-run": { type: "boolean", default: false },
+      "as-of": { type: "string" },
       out: { type: "string" },
       team: { type: "string" },
       "no-wait": { type: "boolean", default: false },
@@ -914,6 +927,8 @@ async function main(argv: string[]): Promise<number> {
           stateRoot: values["state-root"],
           timeoutMs: parseTimeoutMs(values["timeout-ms"]),
           stream: values["no-stream"] ? false : undefined,
+          dryRun: values["dry-run"],
+          asOf: values["as-of"],
         })
       );
     }
@@ -1094,6 +1109,10 @@ async function main(argv: string[]): Promise<number> {
     }
 
     case "session": {
+      const messages = await loadMessages(
+        values.message,
+        values["messages-file"]
+      );
       return cmdSession(
         positionals[0],
         axFromOptions({
@@ -1108,6 +1127,10 @@ async function main(argv: string[]): Promise<number> {
           text: values.text,
           rawEvents: values["raw-events"],
           out: values.out,
+          messages,
+          sessionId: values["session-id"] ?? values.session,
+          dryRun: values["dry-run"],
+          asOf: values["as-of"],
         })
       );
     }
@@ -1488,6 +1511,8 @@ function axFromOptions(
     sessionId: partial.sessionId,
     resume: partial.resume,
     continuationToken: partial.continuationToken,
+    dryRun: partial.dryRun,
+    asOf: partial.asOf,
     timeoutMs: partial.timeoutMs,
     events: partial.events,
     text: partial.text,

package/src/channels/bitbucket/api.ts

@@ -290,6 +290,8 @@ export interface BitbucketApiPullRequest {
   title?: string;
   description?: string;
   state?: string;
+  draft?: boolean;
+  authorUsername?: string;
   sourceBranch?: string;
   targetBranch?: string;
   headSha?: string;
@@ -298,6 +300,20 @@ export interface BitbucketApiPullRequest {
   raw: unknown;
 }
 
+export interface BitbucketApiChangedFile {
+  path: string;
+  previousPath?: string;
+  status: "added" | "modified" | "removed" | "renamed";
+  patch?: string;
+}
+
+export interface BitbucketPullRequestDiffInput {
+  headSha?: string;
+  baseSha?: string;
+  mergeBaseSha?: string;
+  mergeBaseResolved?: boolean;
+}
+
 /**
  * The handful of operations review products need, implemented once per
  * dialect. `ctx.bitbucket.api` is the repo-bound instance.
@@ -318,6 +334,30 @@ export interface BitbucketApi {
   getFileAtRef(path: string, ref: string): Promise<string>;
 }
 
+export interface BitbucketPullRequestReadApi {
+  getPullRequest(id: number): Promise<BitbucketApiPullRequest>;
+  getMergeBaseSha(
+    id: number,
+    base: string,
+    headSha: string
+  ): Promise<string | undefined>;
+  listChangedFiles(
+    id: number,
+    input?: BitbucketPullRequestDiffInput
+  ): Promise<BitbucketApiChangedFile[]>;
+}
+
+export interface BitbucketPullRequestReadClient {
+  readonly repository: BitbucketRepositoryRef;
+  readonly api: Pick<BitbucketApi, "getPullRequest" | "getPullRequestDiff">;
+  request<T = unknown>(input: BitbucketRequestInput): Promise<T>;
+}
+
+export type BitbucketPullRequestReadDiagnostic =
+  | { kind: "commit-expansion-failed"; sha: string; error: unknown }
+  | { kind: "diff-fallback"; status: number }
+  | { kind: "metadata-fallback"; status: number };
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -334,6 +374,111 @@ function num(value: unknown): number | undefined {
     : undefined;
 }
 
+function errorStatus(error: unknown): number | undefined {
+  return num(asRecord(error)?.status);
+}
+
+function bitbucketAuthorUsername(raw: unknown): string | undefined {
+  const author = asRecord(asRecord(raw)?.author);
+  const user = asRecord(author?.user);
+  return (
+    str(author?.nickname) ??
+    str(user?.name) ??
+    str(user?.slug) ??
+    str(author?.display_name) ??
+    str(user?.displayName)
+  );
+}
+
+const GIT_PATH_ESCAPES: Readonly<Record<string, string>> = {
+  a: "\u0007",
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  v: "\v",
+  "\\": "\\",
+  '"': '"',
+};
+
+function unescapeGitPath(path: string, quoted: boolean): string {
+  if (!quoted) {
+    return path;
+  }
+  const bytes: number[] = [];
+  let output = "";
+  const flush = () => {
+    if (bytes.length > 0) {
+      output += Buffer.from(bytes).toString("utf8");
+      bytes.length = 0;
+    }
+  };
+  for (let index = 0; index < path.length; index += 1) {
+    const character = path[index] as string;
+    if (character !== "\\") {
+      flush();
+      output += character;
+      continue;
+    }
+    const octal = /^[0-7]{1,3}/.exec(path.slice(index + 1));
+    if (octal !== null) {
+      bytes.push(Number.parseInt(octal[0], 8));
+      index += octal[0].length;
+      continue;
+    }
+    flush();
+    const next = path[index + 1] ?? "";
+    output += GIT_PATH_ESCAPES[next] ?? next;
+    index += 1;
+  }
+  flush();
+  return output;
+}
+
+/** Split a Git-style unified diff into normalized changed files. */
+export function splitBitbucketUnifiedDiff(
+  diff: string
+): BitbucketApiChangedFile[] {
+  const files: BitbucketApiChangedFile[] = [];
+  const sections = diff.split(/^(?=diff --git )/m).filter(Boolean);
+  for (const section of sections) {
+    const lines = section.replace(/\n$/, "").split("\n");
+    const header = /^diff --git ("?)a\/(.+?)\1 ("?)b\/(.+?)\3$/.exec(
+      lines[0] ?? ""
+    );
+    if (header === null) {
+      continue;
+    }
+    const oldPath = unescapeGitPath(header[2] ?? "", header[1] !== "");
+    const newPath = unescapeGitPath(header[4] ?? "", header[3] !== "");
+    let status: BitbucketApiChangedFile["status"] = "modified";
+    let bodyStart = 1;
+    for (; bodyStart < lines.length; bodyStart += 1) {
+      const line = lines[bodyStart] ?? "";
+      if (line.startsWith("@@")) {
+        break;
+      }
+      if (line === "--- /dev/null") {
+        status = "added";
+      } else if (line === "+++ /dev/null") {
+        status = "removed";
+      }
+    }
+    if (status === "modified" && oldPath !== newPath) {
+      status = "renamed";
+    }
+    const patch = lines.slice(bodyStart).join("\n");
+    files.push({
+      path: newPath,
+      previousPath: status === "renamed" ? oldPath : undefined,
+      status,
+      patch: patch === "" ? undefined : patch,
+    });
+  }
+  return files;
+}
+
 function encodePath(path: string): string {
   return path
     .split("/")
@@ -367,6 +512,202 @@ export function bitbucketDataCenterRepoPath(repository: {
   return `/projects/${encodeURIComponent(repository.owner)}/repos/${encodeURIComponent(repository.slug)}`;
 }
 
+export async function expandBitbucketCloudCommitSha(
+  bitbucket: Pick<BitbucketClient, "request">,
+  repository: Pick<BitbucketRepositoryRef, "owner" | "slug">,
+  sha: string | undefined,
+  onError?: (error: unknown) => void
+): Promise<string | undefined> {
+  if (sha === undefined || !/^[0-9a-f]{7,39}$/i.test(sha)) {
+    return sha;
+  }
+  try {
+    const commit = await bitbucket.request<{ hash?: string }>({
+      method: "GET",
+      path: `${bitbucketCloudRepoPath(repository)}/commit/${encodeURIComponent(sha)}`,
+    });
+    return /^[0-9a-f]{40}$/i.test(commit.hash ?? "") ? commit.hash : sha;
+  } catch (error) {
+    onError?.(error);
+    return sha;
+  }
+}
+
+function bitbucketPullRequestFromRaw(
+  raw: Record<string, unknown>,
+  id: number,
+  htmlUrl?: string
+): BitbucketApiPullRequest {
+  const source = asRecord(raw.source);
+  const destination = asRecord(raw.destination);
+  return {
+    id,
+    title: str(raw.title),
+    description: str(raw.description),
+    state: str(raw.state),
+    draft: typeof raw.draft === "boolean" ? raw.draft : undefined,
+    authorUsername: bitbucketAuthorUsername(raw),
+    sourceBranch:
+      str(asRecord(source?.branch)?.name) ??
+      str(asRecord(raw.fromRef)?.displayId),
+    targetBranch:
+      str(asRecord(destination?.branch)?.name) ??
+      str(asRecord(raw.toRef)?.displayId),
+    headSha:
+      str(asRecord(source?.commit)?.hash) ??
+      str(asRecord(raw.fromRef)?.latestCommit),
+    baseSha:
+      str(asRecord(destination?.commit)?.hash) ??
+      str(asRecord(raw.toRef)?.latestCommit),
+    htmlUrl,
+    raw,
+  };
+}
+
+export function createBitbucketPullRequestReadApi(
+  bitbucket: BitbucketPullRequestReadClient,
+  options: {
+    onDiagnostic?: (diagnostic: BitbucketPullRequestReadDiagnostic) => void;
+  } = {}
+): BitbucketPullRequestReadApi {
+  const { repository } = bitbucket;
+  const repo =
+    repository.dialect === "cloud"
+      ? bitbucketCloudRepoPath(repository)
+      : bitbucketDataCenterRepoPath(repository);
+  const cloudPullRequestFromActivity = async (
+    id: number
+  ): Promise<BitbucketApiPullRequest | undefined> => {
+    let path = `${repo}/pullrequests/${id}/activity`;
+    let query: Record<string, string | number> | undefined = { pagelen: 50 };
+    for (let page = 0; page < 20; page += 1) {
+      const response = await bitbucket.request<Record<string, unknown>>({
+        method: "GET",
+        path,
+        query,
+      });
+      for (const value of Array.isArray(response.values)
+        ? response.values
+        : []) {
+        const update = asRecord(asRecord(value)?.update);
+        if (update !== undefined) {
+          return bitbucketPullRequestFromRaw(update, id);
+        }
+      }
+      const next = str(response.next);
+      if (next === undefined) {
+        return undefined;
+      }
+      const nextUrl = new URL(next);
+      const marker = nextUrl.pathname.indexOf("/repositories/");
+      path = marker === -1 ? nextUrl.pathname : nextUrl.pathname.slice(marker);
+      query = Object.fromEntries(nextUrl.searchParams.entries());
+    }
+    return undefined;
+  };
+  return {
+    async getPullRequest(id) {
+      let pullRequest: BitbucketApiPullRequest;
+      try {
+        pullRequest = await bitbucket.api.getPullRequest(id);
+      } catch (error) {
+        const status = errorStatus(error);
+        if (
+          repository.dialect !== "cloud" ||
+          status === undefined ||
+          status < 500
+        ) {
+          throw error;
+        }
+        options.onDiagnostic?.({ kind: "metadata-fallback", status });
+        const fallback = await cloudPullRequestFromActivity(id);
+        if (fallback === undefined) {
+          throw error;
+        }
+        pullRequest = fallback;
+      }
+      const normalized = {
+        ...pullRequest,
+        draft: asRecord(pullRequest.raw)?.draft === true,
+        authorUsername: bitbucketAuthorUsername(pullRequest.raw),
+      };
+      if (repository.dialect !== "cloud") {
+        return normalized;
+      }
+      const [headSha, baseSha] = await Promise.all([
+        expandBitbucketCloudCommitSha(
+          bitbucket,
+          repository,
+          pullRequest.headSha,
+          (error) =>
+            pullRequest.headSha === undefined
+              ? undefined
+              : options.onDiagnostic?.({
+                  kind: "commit-expansion-failed",
+                  sha: pullRequest.headSha,
+                  error,
+                })
+        ),
+        expandBitbucketCloudCommitSha(
+          bitbucket,
+          repository,
+          pullRequest.baseSha,
+          (error) =>
+            pullRequest.baseSha === undefined
+              ? undefined
+              : options.onDiagnostic?.({
+                  kind: "commit-expansion-failed",
+                  sha: pullRequest.baseSha,
+                  error,
+                })
+        ),
+      ]);
+      return { ...normalized, headSha, baseSha };
+    },
+    async getMergeBaseSha(id, base, headSha) {
+      if (repository.dialect === "cloud") {
+        const commit = await bitbucket.request<{ hash?: string }>({
+          method: "GET",
+          path: `${repo}/merge-base/${encodeURIComponent(headSha)}..${encodeURIComponent(base)}`,
+        });
+        return str(commit.hash);
+      }
+      const commit = await bitbucket.request<{ id?: string }>({
+        method: "GET",
+        path: `${repo}/pull-requests/${id}/merge-base`,
+      });
+      return str(commit.id);
+    },
+    async listChangedFiles(id, input) {
+      try {
+        return splitBitbucketUnifiedDiff(
+          await bitbucket.api.getPullRequestDiff(id)
+        );
+      } catch (error) {
+        const status = errorStatus(error);
+        const comparisonBase = input?.mergeBaseSha ?? input?.baseSha;
+        if (
+          repository.dialect !== "cloud" ||
+          status === undefined ||
+          status < 500 ||
+          input?.headSha === undefined ||
+          comparisonBase === undefined
+        ) {
+          throw error;
+        }
+        options.onDiagnostic?.({ kind: "diff-fallback", status });
+        const diff = await bitbucket.request<string>({
+          method: "GET",
+          path: `${repo}/diff/${encodeURIComponent(input.headSha)}..${encodeURIComponent(comparisonBase)}`,
+          query: { topic: input.mergeBaseResolved === true ? "false" : "true" },
+          accept: "text/plain",
+        });
+        return splitBitbucketUnifiedDiff(diff);
+      }
+    },
+  };
+}
+
 export function cloudBitbucketApi(
   client: BitbucketClient,
   repository: BitbucketRepositoryRef

package/src/channels/bitbucket/binding.ts

@@ -265,6 +265,31 @@ export function bitbucketPullRequestUrl(
     : `${repository.htmlUrl.replace(/\/browse\/?$/, "")}/pull-requests/${id}`;
 }
 
+/** Absolute PR URL, or undefined when a Data Center payload has no repo URL. */
+export function bitbucketAbsolutePullRequestUrl(
+  repository: BitbucketRepositoryRef,
+  id: number,
+  explicit?: string
+): string | undefined {
+  if (explicit !== undefined) {
+    return explicit;
+  }
+  if (repository.dialect === "cloud") {
+    return `https://bitbucket.org/${repository.fullName}/pull-requests/${id}`;
+  }
+  return repository.htmlUrl === undefined
+    ? undefined
+    : `${repository.htmlUrl.replace(/\/+$/, "").replace(/\/browse$/, "")}/pull-requests/${id}`;
+}
+
+/** Whether a Data Center `updated` payload publishes a draft pull request. */
+export function bitbucketDraftMarkedReady(
+  payload: Record<string, unknown>,
+  draft: boolean | undefined
+): boolean {
+  return payload.previousDraft === true && draft === false;
+}
+
 /**
  * Normalize the pull request from either dialect. `action` is the suffix of
  * the Cloud-normalized event key (`pullrequest:created` → `created`).

package/src/channels/bitbucket/index.ts

@@ -24,8 +24,10 @@
 export * from "./api.js";
 export {
   type BitbucketHandle,
+  bitbucketAbsolutePullRequestUrl,
   bitbucketCommentFromPayload,
   bitbucketDialectOf,
+  bitbucketDraftMarkedReady,
   bitbucketPullRequestFromPayload,
   bitbucketPullRequestUrl,
   bitbucketPushFromPayload,

package/src/channels/github/github-channel.ts

@@ -831,11 +831,9 @@ async function handlePullRequest(input: {
     dispatch.message ?? defaultGitHubPullRequestMessage(ctx, pullRequest),
     ...(dispatch.context ?? []),
   ].join("\n");
-  const cloud = await resolveCloudOptions(
-    input.options.cloud,
-    ctx,
-    pullRequest
-  );
+  const cloud =
+    dispatch.cloud ??
+    (await resolveCloudOptions(input.options.cloud, ctx, pullRequest));
   return startTurn({
     options: input.options,
     args: input.args,
@@ -1558,6 +1556,8 @@ async function startTurn(input: {
 }): Promise<Response> {
   const files = input.dispatch.workspaceFiles;
   const lazy = typeof files === "function";
+  const cloud = input.dispatch.cloud ?? input.cloud;
+  const state = { ...input.dispatch.state, ...input.state };
 
   const sendTurn = async () => {
     const workspaceFiles = lazy ? await files() : files;
@@ -1568,11 +1568,11 @@ async function startTurn(input: {
         ? { continuationToken: githubContinuationKey(input.ctx) }
         : {}),
       title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
-      ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+      cloud,
       ...(workspaceFiles === undefined ? {} : { workspaceFiles }),
-      state: input.state as unknown as JsonValue,
+      state: state as unknown as JsonValue,
       // Resume must refresh headSha / refs without wiping sticky banner id.
-      refreshState: input.state as unknown as JsonValue,
+      refreshState: state as unknown as JsonValue,
     });
   };
 

package/src/channels/github/types.ts

@@ -7,6 +7,7 @@ import type {
   ChannelEventHandlers,
   ChannelStartArgs,
   HostContext,
+  JsonObject,
   SendMessageFn,
   SendMessageOptions,
 } from "../../types.js";
@@ -355,6 +356,10 @@ export interface GitHubTurnDispatch {
   message?: string;
   /** Optional session title override. */
   title?: string;
+  /** Per-turn cloud options. Overrides the channel-level `cloud` resolver. */
+  cloud?: AgentCloudOptions;
+  /** Extra durable channel state. Provider-owned fields take precedence. */
+  state?: JsonObject;
   /**
    * Seeded into the session workspace before the turn (`send`'s
    * `workspaceFiles`). A function runs after the webhook is