@cursor/july 0.1.102 → 0.1.103

package/src/channels/bitbucket/types.ts

@@ -0,0 +1,266 @@
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type {
+  AgentCloudOptions,
+  ArtifactsApi,
+  AuthContext,
+  AuthPolicy,
+  ChannelEventHandlers,
+  ChannelStartArgs,
+  HostContext,
+  SendMessageFn,
+} from "../../types.js";
+import type { BitbucketTokenProvider } from "./api.js";
+import type { BitbucketHandle } from "./binding.js";
+import type { BitbucketChannelState } from "./state.js";
+
+/**
+ * Which Bitbucket sent the payload. Cloud bodies carry `pullrequest` and
+ * `repository.uuid`; Data Center bodies carry `pullRequest` and
+ * `repository.project.key`.
+ */
+export type BitbucketDialect = "cloud" | "data-center";
+
+export interface BitbucketUser {
+  /** Cloud `uuid` (braces included) or Data Center numeric `id`. */
+  id: string;
+  displayName?: string;
+  /** Cloud `nickname` / Data Center `name`. */
+  username?: string;
+}
+
+export interface BitbucketRepositoryRef {
+  dialect: BitbucketDialect;
+  /**
+   * `workspace/repo` (Cloud) or `PROJECT/repo` (Data Center), as delivered.
+   * Continuation keys lowercase it; consumers should too when comparing.
+   */
+  fullName: string;
+  /** Workspace slug (Cloud) or project key (Data Center). */
+  owner: string;
+  slug: string;
+  /** Cloud `repository.uuid` (braces included). */
+  uuid?: string;
+  /** Data Center numeric repository id. */
+  id?: number;
+  /** Web URL when the payload carries one. */
+  htmlUrl?: string;
+}
+
+/** A pull request normalized from either dialect. */
+export interface BitbucketPullRequestEvent {
+  /**
+   * Cloud-normalized action: `created`, `updated`, `approved`, `unapproved`,
+   * `changes_request_created`, `fulfilled`, `rejected`.
+   */
+  action: string;
+  id: number;
+  title?: string;
+  description?: string | null;
+  /** `OPEN`, `MERGED`, `DECLINED`, `SUPERSEDED`. */
+  state?: string;
+  draft?: boolean;
+  sourceBranch?: string;
+  targetBranch?: string;
+  /** Source-branch head: Cloud `source.commit.hash` / DC `fromRef.latestCommit`. */
+  headSha?: string;
+  /** DC `previousFromHash` on `pr:from_ref_updated` — new commits were pushed. */
+  previousHeadSha?: string;
+  author?: BitbucketUser;
+  htmlUrl?: string;
+}
+
+export interface BitbucketPullRequestComment {
+  id: number;
+  body: string;
+  author?: BitbucketUser;
+  htmlUrl?: string;
+  /** Cloud `comment.inline` when the comment is anchored to a file. */
+  inline?: { path?: string; to?: number; from?: number };
+}
+
+export interface BitbucketPushChange {
+  ref?: string;
+  /** Branch / tag name. */
+  name?: string;
+  before?: string;
+  after?: string;
+  type?: string;
+}
+
+export interface BitbucketPush {
+  changes: BitbucketPushChange[];
+}
+
+export interface BitbucketEventContext {
+  /** `X-Request-UUID` (Cloud) / `X-Request-Id` (DC), when present. */
+  deliveryId?: string;
+  /** Cloud-normalized event key (`pullrequest:created`, `repo:push`, …). */
+  eventType: string;
+  /** Raw `X-Event-Key` as delivered (DC keys before normalization). */
+  rawEventType: string;
+  repository: BitbucketRepositoryRef;
+  pullRequestId?: number;
+  pullRequestUrl?: string;
+  /** Raw parsed payload record, for consumers whose normalization needs more. */
+  payload: Record<string, unknown>;
+  /** `actor` on the payload — who triggered the delivery. */
+  sender?: BitbucketUser;
+  /**
+   * Repo-bound Bitbucket API (`api`, `request`, `setBuildStatus`,
+   * `createCheck`) in the delivery's dialect. Routes through the Cursor SCM
+   * proxy under `cursorAccount` + `--cursor-scm-proxy`; otherwise uses
+   * {@link BitbucketChannelOptions.token} / `BITBUCKET_TOKEN` against the
+   * dialect's API base.
+   */
+  bitbucket: BitbucketHandle;
+  /**
+   * Channel `send`. Set on every delivery path (HTTP webhook, hosted
+   * admission) so a hook can start a turn itself instead of returning
+   * `{ auth, message }` or a deferred `{ task }`.
+   */
+  send?: SendMessageFn;
+  host: HostContext;
+  artifacts: ArtifactsApi;
+}
+
+export type BitbucketTurnDispatch = {
+  auth: AuthContext;
+  message?: string;
+  title?: string;
+  context?: readonly string[];
+};
+
+/** Bound per-delivery helpers passed to a {@link BitbucketTaskDispatch.task}. */
+export interface BitbucketTaskArgs {
+  send: SendMessageFn;
+  waitUntil: (promise: Promise<unknown>) => void;
+}
+
+/** Run a host-side handler after the webhook is acknowledged with a 202. */
+export type BitbucketTaskDispatch = {
+  task: (args: BitbucketTaskArgs) => void | Promise<void>;
+};
+
+export type BitbucketDispatch = BitbucketTurnDispatch | BitbucketTaskDispatch;
+
+export type BitbucketDispatchResult =
+  | BitbucketDispatch
+  | null
+  | Promise<BitbucketDispatch | null>;
+
+export type BitbucketPullRequestHook = (
+  ctx: BitbucketEventContext,
+  pullRequest: BitbucketPullRequestEvent
+) => BitbucketDispatchResult;
+
+export type BitbucketPullRequestCommentHook = (
+  ctx: BitbucketEventContext,
+  comment: BitbucketPullRequestComment,
+  pullRequest: BitbucketPullRequestEvent
+) => BitbucketDispatchResult;
+
+export type BitbucketPushHook = (
+  ctx: BitbucketEventContext,
+  push: BitbucketPush
+) => BitbucketDispatchResult;
+
+export type BitbucketEventHook = (
+  ctx: BitbucketEventContext,
+  event: { eventType: string; rawEventType: string; payload: unknown }
+) => BitbucketDispatchResult;
+
+export type BitbucketCloudOptionsResolver = (
+  ctx: BitbucketEventContext,
+  pullRequest: BitbucketPullRequestEvent
+) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
+
+/** One verified Bitbucket delivery handed to {@link dispatchBitbucketWebhook}. */
+export interface BitbucketWebhookDelivery {
+  /** Cloud-normalized event key (hosted admission passes the envelope's). */
+  eventType: string;
+  /** `X-Event-Key` as delivered. Defaults to {@link eventType}. */
+  rawEventType?: string;
+  payload: Record<string, unknown>;
+  deliveryId?: string;
+}
+
+export interface BitbucketChannelOptions {
+  /**
+   * Use the signed-in Cursor account for inbound Bitbucket events delivered
+   * by the Cursor backend. `true` takes repo scope from the deployment;
+   * `{ repos }` (`workspace/repo` or `PROJECT/repo`) makes the channel
+   * self-contained.
+   */
+  cursorAccount?: boolean | { repos: readonly string[] };
+  /**
+   * Access token (or provider) for direct `ctx.bitbucket` calls when not in
+   * proxy mode. Sent as `Authorization: Bearer`. Falls back to
+   * `BITBUCKET_TOKEN`.
+   */
+  token?: string | BitbucketTokenProvider;
+  /**
+   * REST base for direct `ctx.bitbucket` calls. Defaults to
+   * `BITBUCKET_API_BASE_URL`, else api.bitbucket.org 2.0 (Cloud). Data
+   * Center deploys must set one of these; the payload's repository link is
+   * never used to pick where the token is sent.
+   */
+  apiBaseUrl?: string;
+  /**
+   * Webhook secret for direct HTTP deliveries: `X-Hub-Signature`
+   * `sha256=<hmac>` over the raw body (both dialects). Falls back to
+   * `BITBUCKET_WEBHOOK_SECRET`. With a secret set the HMAC is the request
+   * auth; without one production stays loopback-strict and `serve --dev`
+   * admits unsigned loopback deliveries.
+   */
+  webhookSecret?: string | (() => string | undefined);
+  /**
+   * Optional repo allowlist (`workspace/repo` / `PROJECT/repo`,
+   * case-insensitive). Events from other repos are acked without a turn.
+   */
+  repos?: readonly string[];
+  /** Route auth chain; defaults follow {@link webhookSecret}. */
+  auth?: AuthPolicy[];
+  /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
+  path?: string;
+  /**
+   * Pin the event keys this channel dispatches on (Cloud vocabulary; DC keys
+   * are normalized). Published as `meta.bitbucketWebhookEvents`. Defaults to
+   * the set derived from hooks.
+   */
+  webhookEvents?: readonly string[];
+  /**
+   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+   * engine-minted per-PR continuation unless the agent set
+   * `architecture: "v2"` (then `bitbucket.pr/v2`, or `bitbucket.none/v2`
+   * when a non-PR event is declared).
+   */
+  continuation?: ContinuationIdentity;
+  /**
+   * Decide whether an inbound pull-request event starts a turn. Return
+   * `{ auth: defaultBitbucketAuth(ctx) }` to dispatch, `null` to ignore.
+   * Without this hook the channel dispatches on `created` and on `updated`
+   * that pushed commits (Data Center `previousFromHash` differs from the
+   * head; Cloud `pullrequest:updated` carries no diff and is not dispatched).
+   */
+  onPullRequest?: BitbucketPullRequestHook;
+  /** Opt-in `pullrequest:comment_created` handler. */
+  onPullRequestComment?: BitbucketPullRequestCommentHook;
+  /** Opt-in `repo:push` handler. No default dispatch. */
+  onPush?: BitbucketPushHook;
+  /**
+   * Catch-all for event keys without a typed hook (`repo:fork`,
+   * `issue:created`, …). NOT a fallback: typed events never reach it.
+   */
+  onEvent?: BitbucketEventHook;
+  /**
+   * Per-session cloud options. Pass `true` to attach the repo using the
+   * pull request's web URL, or a resolver for custom cloud options.
+   */
+  cloud?: boolean | AgentCloudOptions | BitbucketCloudOptionsResolver;
+  /** Channel stream-event handlers. */
+  events?: ChannelEventHandlers<BitbucketChannelState>;
+  /** Called once when the server mounts this channel. */
+  onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+  /** Called when the server shuts down. */
+  onStop?: () => void | Promise<void>;
+}

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

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { defineChannel, localDevStrict, POST } from "../../channels.js";
+import { skipped, tagOutcome } from "../../internal/channel-dispatch.js";
 import {
   deploymentEventMatches,
   resolveDeploymentSubscriptions,
@@ -49,16 +50,16 @@ export function getDeploymentsChannelOptions(
  * subscriptions. Published as `meta.deploymentEventTypes` so the deploy
  * manifest can extract `eventTypes`.
  *
- * A channel with no resolved subscriptions declares the full event set:
- * deploy sources usually come from env vars read at module load, and the
- * hosted freeze bakes hermetically (no customer env/secrets), so deriving
- * `[]` there would leave the manifest without event types and no
+ * A channel with no resolved subscriptions declares the full event set.
+ * That covers an omitted `deploySourceUris` and the env-configured case:
+ * the hosted freeze bakes hermetically (no customer env/secrets), so
+ * deriving `[]` there would leave the manifest without event types and no
  * subscription edge could ever materialize (invariant 26). Capability is
  * the channel's code shape — `onEvent` handles any deployment event —
  * while sources/environments/event narrowing are runtime subscription
  * config; the hosted-admission adapter re-applies them before authored
  * code runs. Inertness is still guaranteed by scope: a deploy that names
- * no deploy sources binds no edges.
+ * no repositories binds no edges.
  */
 export function deriveDeploymentEventTypes(
   options: Pick<DeploymentsChannelOptions, "deploySourceUris" | "events">
@@ -97,28 +98,7 @@ export async function dispatchDeploymentEvent(input: {
   );
   // "task": authored `onEvent` ran to completion without a captured send.
   // Hosted admission only consults this when no send was captured.
-  return withDispatchOutcome(Response.json({ ok: true }), "task");
-}
-
-export type DeploymentsDispatchOutcome = "skip" | "task";
-
-const dispatchOutcomeByResponse = new WeakMap<
-  Response,
-  DeploymentsDispatchOutcome
->();
-
-function withDispatchOutcome(
-  response: Response,
-  outcome: DeploymentsDispatchOutcome
-): Response {
-  dispatchOutcomeByResponse.set(response, outcome);
-  return response;
-}
-
-export function getDeploymentsDispatchOutcome(
-  response: Response
-): DeploymentsDispatchOutcome | undefined {
-  return dispatchOutcomeByResponse.get(response);
+  return tagOutcome(Response.json({ ok: true }), "task");
 }
 
 /**
@@ -129,13 +109,14 @@ export function getDeploymentsDispatchOutcome(
  * the v1 relay does before `onEvent`.
  *
  * A channel with NO resolved subscriptions admits everything the control
- * plane delivered: deploy sources usually come from env vars read at
- * module load, and the hosted freeze bakes hermetically (no customer env),
- * so on a restored pod an env-configured channel resolves empty — the
- * deploy-time edges (bound from the watched repositories) already carry
- * the customer's scope, and refusing here would silently drop every
- * delivery. Same posture as {@link deriveDeploymentEventTypes}: authored
- * subscriptions narrow; an unconfigured channel defers to the deploy scope.
+ * plane delivered. Omitting `deploySourceUris` picks that deliberately:
+ * the deploy-time edges (bound from the watched repositories) already
+ * carry the tenant's scope, so re-filtering here could only narrow it with
+ * another tenant's list. The same holds for an env-configured channel that
+ * resolves empty on a restored pod, where refusing would silently drop
+ * every delivery. Same rule as {@link deriveDeploymentEventTypes}:
+ * authored subscriptions narrow; a channel that names none defers to the
+ * deploy scope.
  */
 export function deploymentEventMatchesChannel(
   options: DeploymentsChannelOptions,
@@ -181,6 +162,15 @@ export function deploymentEventMatchesChannel(
  * adapter re-applies this channel's subscription filter — environments are
  * not edge identity — and skips before authored code runs.
  *
+ * A hosted agent therefore omits `deploySourceUris`:
+ *
+ * ```ts
+ * export default deploymentsChannel({
+ *   events: ["deployment.created", "deployment.succeeded"],
+ *   onEvent: async (event, { send }) => { ... },
+ * });
+ * ```
+ *
  * The route on this channel exists for local replay (`agent-sdk` and tests):
  * POST an event body and it runs the same `onEvent`.
  */
@@ -232,18 +222,10 @@ export function deploymentsChannel(
       }
       const event = parsed.data as DeploymentEvent;
       if (!deploymentEventMatchesChannel(options, event)) {
-        return withDispatchOutcome(
-          Response.json({
-            ok: true,
-            skipped: true,
-            reason: "subscription_mismatch",
-          }),
-          "skip"
-        );
+        return skipped("subscription_mismatch");
       }
       return dispatchDeploymentEvent({ options, event, args });
     },
-    getOutcome: (response) => getDeploymentsDispatchOutcome(response),
   });
   return definition;
 }

package/src/channels/deployments/types.ts

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
 
 /** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
@@ -54,12 +54,18 @@ export interface DeploymentsChannelOptions {
    * and then receives nothing. A bare string takes the default environment and
    * event filters.
    *
-   * There is no team-wide subscription: every deploy source is named. An
-   * empty list is how a consumer *deregisters*, so it cannot also mean
-   * "everything". A live array that starts empty and is filled later is
-   * re-read on each registration heartbeat.
+   * Omit on hosted v2. The control plane then binds `deploy_source` edges
+   * from the deploy's watched `repositories` and the channel admits what it
+   * is sent. That is the multi-tenant shape: an agent cannot enumerate
+   * sources for a tenant it has never seen.
+   *
+   * Name sources to narrow below that scope, or to drive the self-hosted
+   * relay, which has no deploy scope to inherit. On that wire `[]` means
+   * deregister, which is why deferring to the deploy scope is an omitted
+   * field and not an empty one. A live array that starts empty and is filled
+   * later is re-read on each registration heartbeat.
    */
-  deploySourceUris: readonly (string | DeploymentSubscription)[];
+  deploySourceUris?: readonly (string | DeploymentSubscription)[];
   /**
    * Applied to every subscription that does not set its own. Omit or leave
    * empty for every environment.

package/src/channels/github/binding.ts

@@ -52,6 +52,12 @@ export interface GitHubBindingState {
   pullRequestNumber: number | null;
   repo: string;
   repositoryId: number | null;
+  /**
+   * `repository.html_url` from the delivery. Carries the GitHub Enterprise
+   * Server host; absent on state persisted before this field existed, in
+   * which case handles fall back to `https://github.com`.
+   */
+  repositoryUrl?: string | null;
   reviewCommentId: number | null;
   reviewThreadRootCommentId: number | null;
   triggeringCommentId: number | null;
@@ -113,7 +119,8 @@ export function buildGitHubBinding(input: {
   const { config, state } = input;
   const repository: GitHubRepositoryRef = {
     fullName: `${state.owner}/${state.repo}`,
-    url: `https://github.com/${state.owner}/${state.repo}`,
+    url:
+      state.repositoryUrl ?? `https://github.com/${state.owner}/${state.repo}`,
     owner: state.owner,
     name: state.repo,
     ...(state.repositoryId === null ? {} : { id: state.repositoryId }),

package/src/channels/github/cursor-account.ts

@@ -259,20 +259,31 @@ const pendingByResolver = new WeakMap<
   PendingCursorGithubCredentials
 >();
 
+/** Forges whose cursorAccount packs route through the backend SCM forwarder. */
+export type CursorScmProxyForge = "github" | "gitlab" | "bitbucket";
+
 /**
- * Backend GitHub-proxy base URL for proxy mode (`--cursor-github-proxy`).
- * `AGENT_SERVE_GITHUB_PROXY_URL` overrides the default of the Cursor API
- * base URL + `/v0/github-proxy`.
+ * Backend SCM-proxy base URL for proxy mode (`--cursor-scm-proxy`). Each
+ * pack derives its own route, `/v0/<forge>-proxy`, from the Cursor API
+ * base URL; `AGENT_SERVE_<FORGE>_PROXY_URL` overrides it.
  */
-export function resolveCursorGithubProxyUrl(backendBaseUrl: string): string {
-  const override = process.env.AGENT_SERVE_GITHUB_PROXY_URL;
+export function resolveCursorScmProxyUrl(
+  forge: CursorScmProxyForge,
+  backendBaseUrl: string
+): string {
+  const override = process.env[`AGENT_SERVE_${forge.toUpperCase()}_PROXY_URL`];
   const url =
     override !== undefined && override.trim() !== ""
       ? new URL(override)
-      : new URL("/v0/github-proxy", backendBaseUrl);
+      : new URL(`/v0/${forge}-proxy`, backendBaseUrl);
   return url.toString().replace(/\/+$/, "");
 }
 
+/** GitHub-proxy base URL; see {@link resolveCursorScmProxyUrl}. */
+export function resolveCursorGithubProxyUrl(backendBaseUrl: string): string {
+  return resolveCursorScmProxyUrl("github", backendBaseUrl);
+}
+
 export function isCursorAccountGithubTokenResolver(
   value: unknown
 ): value is CursorAccountGithubTokenResolver {

package/src/channels/github/events.ts

@@ -1,7 +1,7 @@
 /**
  * Webhook event derivation for the GitHub channel.
  *
- * `agent-serve github forward` reads the set of webhook events a channel is
+ * `agent-sdk github forward` reads the set of webhook events a channel is
  * wired to dispatch (published as `meta.githubWebhookEvents`) so it can build
  * `gh webhook forward --events=…` without the operator hand-listing them.
  */

package/src/channels/github/forward.ts

@@ -1,5 +1,5 @@
 /**
- * Planning helpers for `agent-serve github forward` — turning discovered
+ * Planning helpers for `agent-sdk github forward` — turning discovered
  * GitHub channels into a `gh webhook forward` invocation.
  *
  * These are pure functions (no process spawning) so they are unit-testable;
@@ -8,6 +8,7 @@
  * @see https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing
  */
 
+import { CLI_COMMAND_NAME as CLI } from "../../internal/distribution.js";
 import type { AgentProject } from "../../types.js";
 import { GITHUB_CHANNEL_KIND } from "./events.js";
 
@@ -316,7 +317,7 @@ export function detectGitHubEnvTokenOverride(
 
 /** Guidance shown when {@link detectGitHubEnvTokenOverride} finds an override. */
 export function githubEnvTokenHint(varName: string): string {
-  return `${varName} is set — gh webhook forward authenticates its relay with the GitHub CLI's own login, so an env token usually causes HTTP 401. Blank it for the command (e.g. \`GITHUB_TOKEN= GH_TOKEN= agent-serve github forward …\`) or \`unset GITHUB_TOKEN GH_TOKEN\`.`;
+  return `${varName} is set — gh webhook forward authenticates its relay with the GitHub CLI's own login, so an env token usually causes HTTP 401. Blank it for the command (e.g. \`GITHUB_TOKEN= GH_TOKEN= ${CLI} github forward …\`) or \`unset GITHUB_TOKEN GH_TOKEN\`.`;
 }
 
 /**