@cursor/bdk 0.2.1

package/dist/docs/guides/agent-to-agent.md

@@ -0,0 +1,152 @@
+# Peer agents
+
+A peer connection lets one agent ask another agent on the same host for
+help. The specialist keeps its own instructions, tools, and session,
+while the caller decides when to delegate and returns the answer to the
+user. Co-host both projects under one `bdk` process.
+
+The `@cursor/bdk` imports and `bdk` commands on this page are docs-ahead
+until publication; see [BDK package availability](/docs/index.md#bdk-package-availability).
+
+## Delegate a question to a specialist
+
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
+
+```ts
+// bot/mcp-connections/weather.ts
+import { defineConnection } from "@cursor/bdk/connections";
+
+export default defineConnection({
+  agent: "weather-agent",
+  description: "Delegate weather questions to the weather specialist.",
+});
+```
+
+Give the concierge a narrow routing rule:
+
+```md
+When a request needs current weather, ask the `weather` peer. Return its
+answer.
+```
+
+```text
+bdk dev ./agents
+bdk chat --url http://127.0.0.1:3000/concierge \
+  --message "What's the weather in Paris right now?"
+```
+
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
+
+## Continue the specialist's session
+
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
+
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
+}
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
+
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
+
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
+
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
+```
+
+The peer owns this session, so follow-ups continue the specialist's
+context.
+
+## Call a deterministic peer tool
+
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
+
+```ts
+const result = await ctx.host.mcp.callTool("weather", "call_tool", {
+  toolName: "get_forecast",
+  input: { city: "Paris" },
+});
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
+
+return {
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
+};
+```
+
+`call_tool` appears only when the peer declares at least one
+deterministic server tool.
+
+## Peer or subagent?
+
+Use a [subagent](/docs/reference/subagents.md) to split one agent's job
+into roles that share its project. Use a peer when the specialist is a
+complete agent you would also run, inspect, or expose on its own.
+
+| | Subagent | Peer |
+| --- | --- | --- |
+| Context | Child role inside one agent | Independent agent and session |
+| Tools and connections | Inherits the parent project | Owns its project surface |
+| Reachability | Parent only | Other co-hosted agents and MCP clients |
+
+## Affinity
+
+Those turns show up in the peer's playground. Only the session owner
+can continue or check them.
+
+## Practices
+
+- Give each caller a one-way routing rule, and don't configure reciprocal
+  routes for the same request.
+
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
+
+## Other hosts
+
+Peers require the default multi-agent layout; unknown slugs and
+self-references fail at startup.
+
+Local-runtime peers on the same serve host use loopback. Turns that run
+elsewhere cannot reach that address, so expose the process separately,
+protect it with `--bearer-token`, and pass its external base URL through
+`--public-url`. The flag advertises the URL; it does not expose the
+process. The [Deployment guide](/docs/deployment.md) owns the hosting setup.
+
+## Related
+
+- [MCP connections](/docs/reference/connections.md#peer-mcp-connection):
+  peer configuration and connection naming
+- [MCP endpoint](/docs/reference/http-api.md#mcp-endpoint): exact `ask`,
+  `check`, and `call_tool` schemas
+- [Subagents](/docs/reference/subagents.md): specialists inside one agent
+- [Deployment](/docs/deployment.md): secure shared-host setup

package/dist/docs/guides/bitbucket.html

@@ -0,0 +1,204 @@
+<!DOCTYPE html>
+<html lang="en-US" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>Bitbucket | Grok Bot Development Kit (BDK)</title>
+    <meta name="description" content="Review pull requests, answer comments, and triage pushes on Bitbucket Cloud or Data Center.">
+    <meta name="generator" content="VitePress v1.6.4">
+    <link rel="preload stylesheet" href="/docs/assets/style.C130MVnH.css" as="style">
+    <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
+    
+    <script type="module" src="/docs/assets/app.JVQvbRO-.js"></script>
+    <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
+    <link rel="modulepreload" href="/docs/assets/chunks/framework.BNw1pucY.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.zK3OJa_C.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/katex.DkKDou_j.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.DMGGa3uA.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.Buf3seya.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.D0AsQFSX.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.6_Aky-ut.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.DQT1Hnwf.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.CGd_eJbn.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.DHIwqnqN.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.Cd4gMyAz.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.DfAl9sy4.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.CNuqFRBj.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.e8BPicch.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.DJ5CmTCl.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.BRn9WcrR.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.NPiy3Hz7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.NPiy3Hz7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.F12urmm7.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2._auCa3fR.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.AWLXtelc.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.B7GiQBeC.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.By_RAMaP.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.CagPhAn5.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.D-T_AKJj.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.Dw8W9BTk.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.DRvQV16Z.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.CQXAOmqd.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.DDjnwRmY.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.CAY_TPVz.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.D1uw7MXq.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.D0niwuY_.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.RwyrIr8Q.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.DKaqpT7K.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/virtual_mermaid-config.DDnGl6nM.js">
+    <link rel="modulepreload" href="/docs/assets/guides_bitbucket.md.Cb3LPKt3.lean.js">
+    <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
+    <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
+    <link rel="alternate" type="text/plain" href="/docs/llms.txt">
+    <link rel="alternate" type="text/markdown" href="/docs/guides/bitbucket.md">
+  </head>
+  <body>
+    <div id="app"><div class="Layout" data-v-76086e96><!--[--><!--]--><!--[--><span tabindex="-1" data-v-97fb5898></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-97fb5898>Skip to content</a><!--]--><!----><header class="VPNav" data-v-76086e96 data-v-781b1279><div class="VPNavBar" data-v-781b1279 data-v-b33015df><div class="wrapper" data-v-b33015df><div class="container" data-v-b33015df><div class="title" data-v-b33015df><div class="VPNavBarTitle has-sidebar" data-v-b33015df data-v-a0c466dc><a class="title" href="/docs/" data-v-a0c466dc><!--[--><!--]--><!----><span data-v-a0c466dc>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.1 (@cursor/bdk package)" data-v-d89e5038>0.2.1</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-b33015df><div class="content-body" data-v-b33015df><!--[--><!--]--><div class="VPNavBarSearch search" data-v-b33015df><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-b33015df data-v-8906c751><span id="main-nav-aria-label" class="visually-hidden" data-v-8906c751> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-8906c751 data-v-e9bcc08e><!--[--><span data-v-e9bcc08e>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-b33015df data-v-959ed110><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-959ed110 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-b33015df data-v-a713f501 data-v-1d7aa189><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-1d7aa189><span class="vpi-more-horizontal icon" data-v-1d7aa189></span></button><div class="menu" data-v-1d7aa189><div class="VPMenu" data-v-1d7aa189 data-v-e34b7e14><!----><!--[--><!--[--><!----><div class="group" data-v-a713f501><div class="item appearance" data-v-a713f501><p class="label" data-v-a713f501>Appearance</p><div class="appearance-action" data-v-a713f501><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-a713f501 data-v-79ad6d7f data-v-0a895de9><span class="check" data-v-0a895de9><span class="icon" data-v-0a895de9><!--[--><span class="vpi-sun sun" data-v-79ad6d7f></span><span class="vpi-moon moon" data-v-79ad6d7f></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-b33015df data-v-cb5d0edb><span class="container" data-v-cb5d0edb><span class="top" data-v-cb5d0edb></span><span class="middle" data-v-cb5d0edb></span><span class="bottom" data-v-cb5d0edb></span></span></button></div></div></div></div><div class="divider" data-v-b33015df><div class="divider-line" data-v-b33015df></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-76086e96 data-v-6f794310><div class="container" data-v-6f794310><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-6f794310><span class="vpi-align-left menu-icon" data-v-6f794310></span><span class="menu-text" data-v-6f794310>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-6f794310 data-v-bab84d9c><button data-v-bab84d9c>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-76086e96 data-v-4daa293d><div class="curtain" data-v-4daa293d></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-4daa293d><span class="visually-hidden" id="sidebar-aria-label" data-v-4daa293d> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Getting started</h2><!----></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible has-active" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/deployment.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-095feacd><section class="VPSidebarItem level-0 collapsible" data-v-095feacd data-v-d79cbf7e><div class="item" role="button" tabindex="0" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><h2 class="text" data-v-d79cbf7e>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-d79cbf7e><span class="vpi-chevron-right caret-icon" data-v-d79cbf7e></span></div></div><div class="items" data-v-d79cbf7e><!--[--><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-d79cbf7e><div class="item" data-v-d79cbf7e><div class="indicator" data-v-d79cbf7e></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-d79cbf7e><!--[--><p class="text" data-v-d79cbf7e>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-76086e96 data-v-258cbba4><div class="VPDoc has-sidebar has-aside" data-v-258cbba4 data-v-afe580da><!--[--><!--]--><div class="container" data-v-afe580da><div class="aside" data-v-afe580da><div class="aside-curtain" data-v-afe580da></div><div class="aside-container" data-v-afe580da><div class="aside-content" data-v-afe580da><div class="VPDocAside" data-v-afe580da data-v-fb5275a4><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-fb5275a4 data-v-b3783f18><div class="content" data-v-b3783f18><div class="outline-marker" data-v-b3783f18></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-b3783f18>On this page</div><ul class="VPDocOutlineItem root" data-v-b3783f18 data-v-72702c6e><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-fb5275a4></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-afe580da><div class="content-container" data-v-afe580da><!--[--><!--]--><main class="main" data-v-afe580da><div style="position:relative;" class="vp-doc _docs_guides_bitbucket" data-v-afe580da><div><h1 id="bitbucket-agents" tabindex="-1">Bitbucket agents <a class="header-anchor" href="#bitbucket-agents" aria-label="Permalink to &quot;Bitbucket agents&quot;">​</a></h1><p>A Bitbucket agent wakes from a verified repository event, reads the current pull-request or commit state, and writes the result back to Bitbucket. <code>bitbucketChannel()</code> gives the same hooks and normalized payloads on Bitbucket Cloud and Data Center.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="review-a-pull-request" tabindex="-1">Review a pull request <a class="header-anchor" href="#review-a-pull-request" aria-label="Permalink to &quot;Review a pull request&quot;">​</a></h2><p>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.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/channels/bitbucket.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  bitbucketChannel,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  bitbucketChannelStateForEvent,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  defaultBitbucketAuth,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels/bitbucket&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  postPullRequestComment,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  setPushTriageStatus,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/bitbucket.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bitbucketChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme/widgets&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (pullRequest.draft) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> hasNewCommits</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      pullRequest.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;updated&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      pullRequest.previousHeadSha </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      pullRequest.previousHeadSha </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pullRequest.headSha;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (pullRequest.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;created&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">hasNewCommits) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> diff</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.bitbucket.api.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getPullRequestDiff</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(pullRequest.id);</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // `auth` starts a model turn running as the event sender.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultBitbucketAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`Review ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repository</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">fullName</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}#${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pullRequest</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      context: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`&lt;bitbucket_diff&gt;${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">diff</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&lt;/bitbucket_diff&gt;`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;message.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">channel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.data.finishReason </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;tool_call&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.text </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> pullRequestId</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channel.state.pullRequestId;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">channel.state.eventType?.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pullrequest:&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">||</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        pullRequestId </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> postPullRequestComment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        channel.state,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        pullRequestId,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        event.data.text</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      );</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>postPullRequestComment</code> is a small wrapper around the normalized Bitbucket API. Configure it with the same token and API base described under <a href="#connect">Connect</a>. It takes the repository and PR ID from the verified event state, so the model never chooses where its review is posted.</p><h2 id="answer-a-pull-request-comment" tabindex="-1">Answer a pull-request comment <a class="header-anchor" href="#answer-a-pull-request-comment" aria-label="Permalink to &quot;Answer a pull-request comment&quot;">​</a></h2><p>Mentioning <code>@cursor-reviewer</code> in a PR comment resumes that pull request&#39;s conversation, and the first example&#39;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.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AGENT_USERNAME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;cursor-reviewer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onPullRequestComment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">comment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (comment.author?.username </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> AGENT_USERNAME</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">comment.body.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`@${</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">AGENT_USERNAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultBitbucketAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    message: comment.body,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Add this property to the same <code>bitbucketChannel()</code> declaration as the review handler.</p><h2 id="triage-a-push-to-main" tabindex="-1">Triage a push to <code>main</code> <a class="header-anchor" href="#triage-a-push-to-main" aria-label="Permalink to &quot;Triage a push to `main`&quot;">​</a></h2><p>A push to <code>main</code> immediately adds a running <code>cursor/push-triage</code> build status to the new commit. The webhook is acknowledged while the model investigates, then the status reports whether that triage turn completed.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onPush</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> change</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> push.changes.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">find</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">    candidate</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      candidate.name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;main&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> candidate.after </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  );</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (change?.after </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> sha</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> change.after;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // `task` runs this host sequence after the webhook is acknowledged.</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.bitbucket.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setBuildStatus</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        sha,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        key: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cursor/push-triage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        state: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INPROGRESS&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Cursor push triage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Investigating push to main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`Triage push ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sha</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} on ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">repository</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">fullName</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultBitbucketAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`Bitbucket push ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sha</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        state: {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">          ...</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bitbucketChannelStateForEvent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            repository: ctx.repository,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            headSha: sha,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            eventType: ctx.eventType,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Extend the <code>events</code> map so the turn&#39;s terminal event concludes the status through the same provider wrapper:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">async </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;message.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event, channel, ctx) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channel.state.eventType </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;repo:push&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channel.state.headSha </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    event.data.finishReason </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;tool_call&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> setPushTriageStatus</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      channel.state,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;SUCCESSFUL&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;Push triage complete&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    );</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Continue with the pull-request reply branch from the first example.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">async </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(_event, channel, ctx) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channel.state.eventType </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;repo:push&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channel.state.headSha </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> setPushTriageStatus</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channel.state,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;FAILED&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;Push triage failed&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  );</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>This status reports the triage run, not the health of the pushed commit itself.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>Use <code>onPullRequest</code>, <code>onPullRequestComment</code>, or <code>onPush</code> for the events shown above. Each hook returns one of three decisions:</p><table tabindex="0"><thead><tr><th>Return</th><th>What happens</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Start a model turn as the Bitbucket event sender</td></tr><tr><td><code>{ task }</code></td><td>Acknowledge the webhook, then run host code that may also call <code>send</code></td></tr><tr><td><code>null</code></td><td>Skip the event</td></tr></tbody></table><p>The <a href="./../reference/channels.html">Channels reference</a> covers the remaining hook and session behavior.</p><h2 id="pull-request-affinity" tabindex="-1">Pull-request affinity <a class="header-anchor" href="#pull-request-affinity" aria-label="Permalink to &quot;Pull-request affinity&quot;">​</a></h2><p>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.</p><h2 id="call-bitbucket-through-ctx-bitbucket" tabindex="-1">Call Bitbucket through <code>ctx.bitbucket</code> <a class="header-anchor" href="#call-bitbucket-through-ctx-bitbucket" aria-label="Permalink to &quot;Call Bitbucket through `ctx.bitbucket`&quot;">​</a></h2><p>Each hook receives an API client already bound to the repository and dialect from the verified delivery. Use <code>ctx.bitbucket.api</code> for pull-request reads and comments, <code>setBuildStatus()</code> for one status update, or <code>createCheck()</code> when a status changes throughout longer work.</p><p>The repository does not come from model output. Keep API calls on this bound client so the event decides where reads and writes go.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to &quot;Connect&quot;">​</a></h2><p>On Cursor-managed hosting, use the signed-in Cursor account and list the repositories that may wake the agent:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bitbucketChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme/widgets&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> covers event delivery and API calls made through <code>ctx.bitbucket</code> inside hooks. The <code>postPullRequestComment</code> and <code>setPushTriageStatus</code> wrappers are separate REST clients, so configure their Bitbucket API credential too.</p><p>For direct webhooks, configure the repository hook secret, API token, and allowed repositories. Data Center also needs its REST API base:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bitbucketChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;PLATFORM/api&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  webhookSecret</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BITBUCKET_WEBHOOK_SECRET</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  token</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BITBUCKET_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  apiBaseUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://bitbucket.example.com/rest/api/1.0&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Without <code>webhookSecret</code>, the direct production route stays loopback-only. Setting it admits deliveries signed with the matching repository-hook secret; <code>token</code> authorizes the API reads and writes in the examples.</p><p>Register the repository webhook at <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/bitbucket</code> with the same secret. For Bitbucket Cloud, omit <code>apiBaseUrl</code>.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><p>Replay lets you exercise the same hooks with a pull request you can read before registering a live repository webhook.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk dev</span></span>
+<span class="line"><span>bdk bitbucket replay \</span></span>
+<span class="line"><span>  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42 \</span></span>
+<span class="line"><span>  --events &#39;*&#39;</span></span></code></pre></div><p>Use <code>--dry-run --out fixtures/bitbucket</code> to save the payloads instead of posting them. <code>BITBUCKET_TOKEN</code> needs read access to the pull request.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../reference/channels.html">Channels reference</a>: channel hooks, dispatch decisions, and session behavior</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: direct webhook auth and reply delivery</li><li><a href="./../evals.html">Evals</a>: turn saved Bitbucket payloads into regression fixtures</li></ul></div></div></main><footer class="VPDocFooter" data-v-afe580da data-v-feab96e0><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-feab96e0><span class="visually-hidden" id="doc-footer-aria-label" data-v-feab96e0>Pager</span><div class="pager" data-v-feab96e0><a class="VPLink link pager-link prev" href="/docs/guides/gitlab.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Previous page</span><span class="title" data-v-feab96e0>GitLab</span><!--]--></a></div><div class="pager" data-v-feab96e0><a class="VPLink link pager-link next" href="/docs/reference/extensions.html" data-v-feab96e0><!--[--><span class="desc" data-v-feab96e0>Next page</span><span class="title" data-v-feab96e0>Overview</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"-fcjCmJU\",\"deployment.md\":\"nGo1yIsa\",\"evals.md\":\"CCAtNcuL\",\"guides_agent-to-agent.md\":\"CGkicXeB\",\"guides_bitbucket.md\":\"Cb3LPKt3\",\"guides_cloud-agents.md\":\"BuEkDCwo\",\"guides_convert-automation.md\":\"Ci-Y2iD5\",\"guides_github.md\":\"C2_DSWlE\",\"guides_gitlab.md\":\"BM27P43u\",\"guides_grokbot-agents.md\":\"yxVbSlKA\",\"guides_hooks.md\":\"BWoiNaMq\",\"guides_improve.md\":\"COtL-6ft\",\"guides_jev.md\":\"BNDm14Gy\",\"guides_mcp-oauth.md\":\"Cu6mhZ_3\",\"guides_opentelemetry.md\":\"DLlIB5rv\",\"guides_slack.md\":\"ZbHQETOT\",\"guides_webhooks.md\":\"D0furjw0\",\"hillclimbing.md\":\"Biy0m-Qb\",\"index.md\":\"CVc_oOA3\",\"quickstart.md\":\"wG4shE1f\",\"reference_agent-config.md\":\"DzGI777n\",\"reference_artifacts.md\":\"IFFC5Zln\",\"reference_channels.md\":\"mbNtKCiR\",\"reference_cli.md\":\"BK2QUH67\",\"reference_connections.md\":\"_XpKiOaF\",\"reference_evals.md\":\"DqNyHMA6\",\"reference_extensions.md\":\"CPPrkWlJ\",\"reference_hooks.md\":\"Dg3dEugd\",\"reference_http-api.md\":\"BZOvhCqY\",\"reference_instructions.md\":\"Bdwscs4G\",\"reference_playground.md\":\"BdQzRJc2\",\"reference_project-layout.md\":\"CpLQ9j4K\",\"reference_prompt.md\":\"BQZB4eaV\",\"reference_schedules.md\":\"BVU5EFbz\",\"reference_sessions.md\":\"BtpTjZmh\",\"reference_skills.md\":\"Cy00QMKS\",\"reference_subagents.md\":\"B8oyeXOI\",\"reference_tools.md\":\"hg2Wi5Bq\",\"templates_agentic-owners.md\":\"BykUiZ8j\",\"templates_security-reviewer.md\":\"DXMmKl_o\",\"templates_thermo-quality-review.md\":\"Dg1p1MsG\",\"templates_thermo-review.md\":\"Dlylkowj\",\"templates_triage.md\":\"CvJyx81N\",\"troubleshooting.md\":\"BzZSu1Gz\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.1\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    
+  </body>
+</html>