@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/bitbucket.md

@@ -1,84 +1,285 @@
 # Bitbucket agents
 
-Use `bitbucketChannel()` for Bitbucket Cloud and Bitbucket Data Center. The
-channel detects the source from each signed payload and normalizes Data Center
-events to the Bitbucket Cloud event vocabulary.
+A Bitbucket agent wakes from a verified repository event, reads the
+current pull-request or commit state, and writes the result back to
+Bitbucket. `bitbucketChannel()` gives the same hooks and normalized
+payloads on Bitbucket Cloud and Data Center.
 
-## Define the channel
+## Review a pull request
 
-Author `agent/channels/bitbucket.ts`:
+Creating a pull request, or pushing new commits to a Data Center pull
+request, starts a review. The hook reads the current diff through the
+repository-bound API, the model returns a verdict, and the completed
+answer appears as a comment on the pull request.
 
 ```ts
-import { bitbucketChannel } from "@cursor/july/channels/bitbucket";
+// agent/channels/bitbucket.ts
+import {
+  bitbucketChannel,
+  bitbucketChannelStateForEvent,
+  defaultBitbucketAuth,
+} from "@cursor/july/channels/bitbucket";
+import {
+  postPullRequestComment,
+  setPushTriageStatus,
+} from "../lib/bitbucket.js";
 
-export default bitbucketChannel({});
+export default bitbucketChannel({
+  repos: ["acme/widgets"],
+  onPullRequest: async (ctx, pullRequest) => {
+    if (pullRequest.draft) {
+      return null;
+    }
+    const hasNewCommits =
+      pullRequest.action === "updated" &&
+      pullRequest.previousHeadSha !== undefined &&
+      pullRequest.previousHeadSha !== pullRequest.headSha;
+    if (pullRequest.action !== "created" && !hasNewCommits) {
+      return null;
+    }
+
+    const diff = await ctx.bitbucket.api.getPullRequestDiff(pullRequest.id);
+    return {
+      // `auth` starts a model turn running as the event sender.
+      auth: defaultBitbucketAuth(ctx),
+      message: `Review ${ctx.repository.fullName}#${pullRequest.id}.`,
+      context: [`<bitbucket_diff>${diff}</bitbucket_diff>`],
+    };
+  },
+  events: {
+    async "message.completed"(event, channel, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      const pullRequestId = channel.state.pullRequestId;
+      if (
+        !channel.state.eventType?.startsWith("pullrequest:") ||
+        pullRequestId === null
+      ) {
+        return;
+      }
+      await postPullRequestComment(
+        channel.state,
+        pullRequestId,
+        event.data.text
+      );
+    },
+  },
+});
 ```
 
-Without `onPullRequest`, new pull requests start turns. Data Center updates
-also start turns when the source branch has new commits. Comments and pushes
-are opt-in through `onPullRequestComment` and `onPush`. Use `onEvent` for
-other event types. Set `webhookEvents` when managed event delivery must
-subscribe to an event that only `onEvent` handles.
+`postPullRequestComment` is a small wrapper around the normalized
+Bitbucket API. Configure it with the same token and API base described
+under [Connect](#connect). It takes the repository and PR ID from the
+verified event state, so the model never chooses where its review is
+posted.
 
-Filter comment hooks by author before starting a turn. This prevents comments
-posted by the agent from triggering another turn.
+## Answer a pull-request comment
 
-`ctx.bitbucket.api` can read pull requests, post comments, and create build
-statuses. See the [Channels reference](/docs/reference/channels.md) for hook
-return values and session behavior.
+Mentioning `@cursor-reviewer` in a PR comment resumes that pull
+request's conversation, and the first example's reply sink posts the
+answer back to the same PR. The author guard ignores comments written
+by the agent, preventing each reply from starting another turn.
 
-## Connect Bitbucket
+```ts
+const AGENT_USERNAME = "cursor-reviewer";
 
-Set a repository hook secret and API token:
+onPullRequestComment: (ctx, comment) => {
+  if (comment.author?.username === AGENT_USERNAME) {
+    return null;
+  }
+  if (!comment.body.includes(`@${AGENT_USERNAME}`)) {
+    return null;
+  }
+  return {
+    auth: defaultBitbucketAuth(ctx),
+    message: comment.body,
+  };
+},
+```
 
-```bash
-BITBUCKET_WEBHOOK_SECRET=...
-BITBUCKET_TOKEN=...
+Add this property to the same `bitbucketChannel()` declaration as the
+review handler.
+
+## Triage a push to `main`
+
+A push to `main` immediately adds a running `cursor/push-triage` build
+status to the new commit. The webhook is acknowledged while the model
+investigates, then the status reports whether that triage turn
+completed.
+
+```ts
+onPush: (ctx, push) => {
+  const change = push.changes.find(
+    candidate =>
+      candidate.name === "main" && candidate.after !== undefined
+  );
+  if (change?.after === undefined) {
+    return null;
+  }
+  const sha = change.after;
+
+  return {
+    // `task` runs this host sequence after the webhook is acknowledged.
+    task: async ({ send }) => {
+      await ctx.bitbucket.setBuildStatus({
+        sha,
+        key: "cursor/push-triage",
+        state: "INPROGRESS",
+        name: "Cursor push triage",
+        description: "Investigating push to main",
+      });
+
+      await send(`Triage push ${sha} on ${ctx.repository.fullName}.`, {
+        auth: defaultBitbucketAuth(ctx),
+        title: `Bitbucket push ${sha}`,
+        state: {
+          ...bitbucketChannelStateForEvent({
+            repository: ctx.repository,
+            headSha: sha,
+            eventType: ctx.eventType,
+          }),
+        },
+      });
+    },
+  };
+},
+```
+
+Extend the `events` map so the turn's terminal event concludes the
+status through the same provider wrapper:
+
+```ts
+async "message.completed"(event, channel, ctx) {
+  if (
+    ctx.session.purpose !== "eval" &&
+    channel.state.eventType === "repo:push" &&
+    channel.state.headSha !== null &&
+    event.data.finishReason !== "tool_call"
+  ) {
+    await setPushTriageStatus(
+      channel.state,
+      "SUCCESSFUL",
+      "Push triage complete"
+    );
+    return;
+  }
+
+  // Continue with the pull-request reply branch from the first example.
+},
+async "turn.failed"(_event, channel, ctx) {
+  if (
+    ctx.session.purpose === "eval" ||
+    channel.state.eventType !== "repo:push" ||
+    channel.state.headSha === null
+  ) {
+    return;
+  }
+  await setPushTriageStatus(
+    channel.state,
+    "FAILED",
+    "Push triage failed"
+  );
+},
 ```
 
-Add a repository webhook for
-`https://<your-host>/<slug>/v1/channels/bitbucket`. Use the same secret on
-both sides. The channel verifies the `X-Hub-Signature` HMAC before it parses
-the payload.
+This status reports the triage run, not the health of the pushed commit
+itself.
+
+## Events
+
+Use `onPullRequest`, `onPullRequestComment`, or `onPush` for the events
+shown above. Each hook returns one of three decisions:
+
+| Return | What happens |
+| --- | --- |
+| `{ auth }` | Start a model turn as the Bitbucket event sender |
+| `{ task }` | Acknowledge the webhook, then run host code that may also call `send` |
+| `null` | Skip the event |
+
+The [Channels reference](/docs/reference/channels.md) covers the remaining
+hook and session behavior.
 
-Bitbucket Cloud uses its 2.0 API by default. Data Center also needs its REST
-API base:
+## Pull-request affinity
+
+Every pull-request event and comment for the same repository and PR ID
+resumes one agent session. A new PR, later commits, and a mention in the
+discussion therefore share the same conversation across both Bitbucket
+dialects.
+
+## Call Bitbucket through `ctx.bitbucket`
+
+Each hook receives an API client already bound to the repository and
+dialect from the verified delivery. Use `ctx.bitbucket.api` for
+pull-request reads and comments, `setBuildStatus()` for one status
+update, or `createCheck()` when a status changes throughout longer
+work.
+
+The repository does not come from model output. Keep API calls on this
+bound client so the event decides where reads and writes go.
+
+## Connect
+
+On Cursor-managed hosting, use the signed-in Cursor account and list
+the repositories that may wake the agent:
+
+```ts
+export default bitbucketChannel({
+  cursorAccount: {
+    repos: ["acme/widgets"],
+  },
+});
+```
+
+`cursorAccount` covers event delivery and API calls made through
+`ctx.bitbucket` inside hooks. The `postPullRequestComment` and
+`setPushTriageStatus` wrappers are separate REST clients, so configure
+their Bitbucket API credential too.
+
+For direct webhooks, configure the repository hook secret, API token,
+and allowed repositories. Data Center also needs its REST API base:
 
 ```ts
 export default bitbucketChannel({
-  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
   repos: ["PLATFORM/api"],
+  webhookSecret: () => process.env.BITBUCKET_WEBHOOK_SECRET,
+  token: () => process.env.BITBUCKET_TOKEN ?? "",
+  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
 });
 ```
 
-You can set `BITBUCKET_API_BASE_URL` instead.
+Without `webhookSecret`, the direct production route stays
+loopback-only. Setting it admits deliveries signed with the matching
+repository-hook secret; `token` authorizes the API reads and writes in
+the examples.
+
+Register the repository webhook at
+`https://<your-host>/<slug>/v1/channels/bitbucket` with the same secret.
+For Bitbucket Cloud, omit `apiBaseUrl`.
 
 ## Test locally
 
-Start the agent, then replay a pull request you can read:
+Replay lets you exercise the same hooks with a pull request you can
+read before registering a live repository webhook.
 
 ```bash
 agent-sdk dev
 agent-sdk bitbucket replay \
-  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42
-```
-
-Replay supports Bitbucket Cloud and Data Center URLs. `BITBUCKET_TOKEN` needs
-pull request read access. The command reads the pull request, creates a payload
-in the matching dialect, and sends it through the same channel route. Use
-`--events '*'` to replay the supported events declared by the channel. Use
-`--dry-run --out fixtures/bitbucket` to save fixtures.
-
-```bash
-agent-sdk bitbucket events --dir .
-agent-sdk bitbucket forward --dir .
+  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42 \
+  --events '*'
 ```
 
-`forward` prints the repository-hook and HTTPS tunnel setup for live
-deliveries.
+Use `--dry-run --out fixtures/bitbucket` to save the payloads instead of
+posting them. `BITBUCKET_TOKEN` needs read access to the pull request.
 
 ## Related
 
-- [Channels reference](/docs/reference/channels.md)
-- [Webhooks and custom channels](/docs/guides/webhooks.md)
-- [Evals](/docs/evals.md)
+- [Channels reference](/docs/reference/channels.md): channel hooks,
+  dispatch decisions, and session behavior
+- [Webhooks and custom channels](/docs/guides/webhooks.md): direct webhook auth
+  and reply delivery
+- [Evals](/docs/evals.md): turn saved Bitbucket payloads into regression
+  fixtures