@cursor/july 0.1.108 → 0.1.109

package/skills/deploy/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: agentsdk-deploy
+description: >-
+  Deploy or redeploy an Agent SDK project to Cursor-managed hosting
+  with an attached service account. Use when asked to deploy,
+  redeploy, publish, or update a hosted Agent SDK agent.
+---
+
+# Deploy an Agent SDK agent
+
+Use this skill only after a person asks for a deployment. It deploys a
+pushed Git ref to Cursor-managed hosting. Local files never upload.
+
+Use the exact published `@cursor/july` release embedded in the installed
+skill. Do not use a floating npm tag or a workspace build of the CLI.
+
+## Gather the target
+
+Resolve these values from the request and checkout:
+
+- Agent directory. Default to the current directory only when it contains
+  one Agent SDK project.
+- Deployment slug. Default to the normalized directory name.
+- Git ref. Default to the exact pushed `HEAD` commit.
+- Team. Use the service account's team unless the request names another.
+- Cursor-event repositories and CLI-only egress domains.
+
+Ask one focused question when the target or requested ref is ambiguous.
+Do not ask for values the checkout or existing deployment supplies.
+
+## Use the attached service account
+
+Continue only when `CURSOR_SERVICE_ACCOUNT_KEY` is present. Never print
+the value. Do not run `agent-sdk login`.
+
+On Linux and macOS, run every Agent SDK command through this wrapper:
+
+```bash
+CURSOR_JULY_VERSION="__CURSOR_JULY_VERSION__"
+case "$CURSOR_JULY_VERSION" in
+  __CURSOR_JULY_*__)
+    echo "The Agent SDK deploy skill is not bound to a package version." >&2
+    exit 1
+    ;;
+esac
+
+run_agent_sdk() {
+  env -u NODE_OPTIONS -u CURSOR_API_KEY \
+    CURSOR_API_KEY_FILE=/dev/null \
+    npx --yes "@cursor/july@$CURSOR_JULY_VERSION" "$@"
+}
+```
+
+The installed copy pins the release it came from. The wrapper isolates that
+published CLI and the attached service account. The presence check prevents a
+stored personal login from being used when the attachment is missing.
+
+Verify the principal before any write:
+
+```bash
+test -n "${CURSOR_SERVICE_ACCOUNT_KEY:-}" || {
+  echo "No attached Cursor service account." >&2
+  exit 1
+}
+run_agent_sdk whoami --json
+```
+
+Continue only when `credentialSource` is `service-account`. Record the
+team and complete service-account ID for the final report. Stop on an
+authentication, team-access, repository-scope, or hosting-entitlement
+error.
+
+## Pin pushed source
+
+Find the Git root and commit:
+
+```bash
+GIT_ROOT="$(git -C "$AGENT_DIR" rev-parse --show-toplevel)"
+SOURCE_REF="$(git -C "$GIT_ROOT" rev-parse HEAD)"
+git -C "$GIT_ROOT" status --short
+git -C "$GIT_ROOT" branch -r --contains "$SOURCE_REF"
+```
+
+Use a ref from the request instead of `SOURCE_REF` when the person names
+one. Confirm the selected commit exists on the remote. If intended
+changes are uncommitted or unpushed, stop and explain they will not ship.
+Do not commit or push unless the request includes that work.
+
+The CLI infers the normalized HTTPS `origin`, agent path, and slug from
+`--dir`. Pass `--repo`, `--path`, or `--slug` when the request overrides
+the inferred value. Never print a remote URL that contains credentials.
+
+## Preserve deployment inputs
+
+A redeploy replaces its source, Cursor-event repositories, and
+CLI-supplied egress domains. Preserve the existing
+`cursorEventRepos` and `egressAllowedDomains` unless the request or
+project changes them. Reapply each value with:
+
+```text
+--cursor-events-repo <owner/repo>
+--allow-domain <hostname>
+```
+
+Read existing settings through a filter that selects only those two
+fields:
+
+```bash
+run_agent_sdk deployment "$SLUG" --json |
+  node -e '
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { raw += chunk; });
+    process.stdin.on("end", () => {
+      const value = JSON.parse(raw);
+      console.log(JSON.stringify({
+        cursorEventRepos: value.cursorEventRepos ?? [],
+        egressAllowedDomains: value.egressAllowedDomains ?? [],
+      }, null, 2));
+    });
+  '
+```
+
+Never print or save the full response because it can contain short-lived
+engine-access headers.
+
+For a new SCM-channel deployment, ask which repositories should wake the
+agent when the project does not declare the answer. The source repository
+is not always the event repository.
+
+## Validate, deploy, and verify
+
+Validate with the same published package and principal:
+
+```bash
+run_agent_sdk validate --dir "$AGENT_DIR"
+```
+
+Stop on validation errors. Review hosting warnings about secret names,
+egress domains, and channel configuration before continuing.
+
+Deploy the pinned source. Add the preserved or requested repeatable
+flags:
+
+```bash
+run_agent_sdk deploy \
+  --dir "$AGENT_DIR" \
+  --ref "$SOURCE_REF"
+```
+
+The command waits for a terminal deployment state. Do not treat
+`pending`, `accepted`, or `deploying` as success. If the command is
+interrupted, resume inspection with:
+
+```bash
+run_agent_sdk deployment "$SLUG"
+```
+
+A first deployment prints a one-time alias token. Never paste it into
+chat or expose it in an agent-captured terminal. Before a first deploy,
+ask for a secure destination or ask the person to run the final command
+in a private terminal. When writing the token, use mode `0600` and print
+only the path. Redeploys do not print the token. JSON deployment output
+can also contain credentials, so filter it before display.
+
+Finish only when the deployment reports `running`. Report the slug,
+team, generation, pinned ref, and complete service-account ID. On
+failure, report the deployment status and sanitized error without
+retrying a different ref or principal.

package/skills/evals/SKILL.md

@@ -3,17 +3,17 @@ name: agentsdk-evals
 description: >-
   Author and run defineEval cases. Use when writing, fixing, seeding,
   or hillclimbing evals. Ask whether to generate samples or take
-  uploaded data. Materialize API-backed fixtures first. Live A/B is
-  defineAB (skills/ab), not defineEval.
+  uploaded data. Materialize API-backed fixtures first.
 ---
 
 # Agent SDK evals
 
 Fixed input, model turn, gates on the trajectory. Files live at
 project-root `evals/**/*.eval.ts`. `agent/evals/` is ignored.
+Guide: `docs/evals.md`.
 
-Live traffic variants: `skills/ab/SKILL.md`. That is not a test
-runner.
+Observing production: hooks. Tool logic without a model:
+`agent-sdk call <tool> --input '{...}'`.
 
 ```bash
 agent-sdk eval --dir . --list
@@ -27,9 +27,13 @@ agent-sdk eval --dir . --tag smoke
 | `evals/weather.eval.ts` + `test` | `weather` |
 | `evals/weather/nyc.eval.ts` + `test` | `weather/nyc` |
 | `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
+| `evals/sql.eval.ts` exporting an array of `defineEval` calls | `sql/0000`, `sql/0001`, ... |
 
 `eval` boots an ephemeral server and a temp state root. `--url`
-points at a running agent. Model turns need a Cursor credential (`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then `CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`).
+points at a running agent. Model turns need a Cursor credential
+(`CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE`, then
+`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`); `--list` does
+not. Node 22.13+, never Bun.
 
 ## Seeding
 
@@ -79,9 +83,30 @@ export default defineEvalConfig({
 });
 ```
 
-Either `test(t)` or `cases`, not both. `t.send` waits for park/fail.
-`workspaceFiles` seeds the first turn. Assert with `t.succeeded()`,
-`calledTool` / `notCalledTool`, `t.check(t.reply, …)`, `t.metric`.
+Either `test(t)` or `cases`, not both. `t.send` waits for the turn to
+settle (complete, park, or fail) and returns it; `turn.calledTool(...)`
+reads only that turn, `t.*` reads the whole run. First-send options:
+`workspaceFiles`, `workspaceDir`, `cloud`.
+
+Gates: `t.succeeded()` / `t.parked()`,
+`calledTool(name, { input, output, status, count })` / `notCalledTool`,
+`toolOrder`, `maxToolCalls`, `taggedArtifact`, `event` / `notEvent`,
+`t.check(value, includes | equals | matches | similarity | satisfies)`.
+Records: `t.metric`, `t.log`, `t.score` (soft 0-1).
+
+Severity is on the handle: default gate; `.soft()` tracked;
+`.atLeast(0.8)` soft with a bar (verdict `scored`, exit 1 only under
+`--strict`); `.gate(0.8)` hard. `t.judge.factuality`, `summarizes`,
+`closedQA`, and `sql` are soft by default and need a judge model
+(`judge` in `evals.config.ts`, on the eval or case, or per-call
+`{ model }`).
+
+## Side effects
+
+Eval sessions run real tools. Guard actuation with
+`ctx.session.purpose === "eval"` in the tool, hook, or `defineResult`
+and return a shaped result so `calledTool` can still assert the
+decision.
 
 ## What to gate
 
@@ -103,6 +128,18 @@ drifting inputs (pin them).
 | GitHub | `github replay … --dry-run --out fixtures/github` |
 | Host-prep PR review | A team-owned PR; gate findings shape, not counts |
 | Workspace | `workspaceFiles` in `t.send` |
+| Dataset | `loadJson` / `loadJsonl` / `loadYaml` from `@cursor/july/evals/loaders`, paths from the project root |
+
+## Debug and CI
+
+A failed local run leaves `evals/<case-id>.json` (assertions, inputs,
+tool I/O, final text, logs) under `evals/<stamp>/` in the project state
+directory (the CLI prints the path); read it before editing the eval.
+`--state-root <path>` keeps the raw session events too.
+
+CI: `agent-sdk eval --dir . --json --no-stream --junit reports/evals.xml`.
+Exit `1` on a failed gate, `2` when nothing matched, `--strict` to fail
+on `scored`.
 
 Every kept hillclimb change lands an eval that would have failed
 before it. Never weaken a gate to pass a round.

package/skills/framework-map/SKILL.md

@@ -51,7 +51,6 @@ Path is identity. Full list: README "Folder structure".
 | `agent/hooks/*.ts` | Observe-only |
 | `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
 | `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
-| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
 | `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
 | `agent/sandbox/workspace/` | Session seed files (local only) |
@@ -99,10 +98,10 @@ only this agent's directory.
 | --- | --- |
 | Scaffold | `skills/create-agent/SKILL.md` |
 | Evals | `skills/evals/SKILL.md` |
-| Live A/B | `skills/ab/SKILL.md` |
 | OpenTelemetry | `skills/otel/SKILL.md` |
 | GitHub | `skills/github/SKILL.md` |
 | Slack | `skills/setup-slack/SKILL.md` |
 | Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Managed deployment | `skills/deploy/SKILL.md` |
 | Local triage | `skills/debug/SKILL.md` |
 | Measured improvement | `skills/hillclimb/SKILL.md` |

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,