@cursor/bdk 0.2.4 → 0.2.6

package/dist/docs/assets/{guides_github.md.Bq9kQU9B.js → guides_github.md.Cr1Xlf-m.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks.","frontmatter":{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),h={name:"guides/github.md"};function e(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>GitHub agents work both directions. They wake from repo events, read the latest PR and CI state, then write back reviews, comments, checks, or pushes. Pull events from Cursor, so you don&#39;t expose a public webhook URL.</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><p>Connect GitHub in Cursor for the repos you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). Sign the host in with <code>bdk login</code>. <code>cursorAccount</code> reuses that connection for events and API calls. You don&#39;t set up a GitHub App or a PAT.</p><p>Start from a template when one fits: <a href="./../templates/security-reviewer.html">security reviewer</a> or <a href="./../templates/triage.html">issue triager</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>Wake when a PR is ready for review. Fetch the latest diff in a tool, then post a verdict.</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/github.ts</span></span>
+import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks.","frontmatter":{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),h={name:"guides/github.md"};function e(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>GitHub agents work both directions. They wake from repo events, read the latest PR and CI state, then write back reviews, comments, checks, or pushes. Pull events from Cursor, so you don&#39;t expose a public webhook URL.</p><p>Connect GitHub in Cursor for the repos you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). Sign the host in with <code>bdk login</code>. <code>cursorAccount</code> reuses that connection for events and API calls. You don&#39;t set up a GitHub App or a PAT.</p><p>Start from a template when one fits: <a href="./../templates/security-reviewer.html">security reviewer</a> or <a href="./../templates/triage.html">issue triager</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>Wake when a PR is ready for review. Fetch the latest diff in a tool, then post a verdict.</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/github.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels/github&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;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -115,7 +115,7 @@ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o
 <span class="line"><span>  --repo acme/checkout --repo acme/payments</span></span>
 <span class="line"><span>bdk deploy --dir . \\</span></span>
 <span class="line"><span>  --cursor-events-repo acme/checkout \\</span></span>
-<span class="line"><span>  --cursor-events-repo acme/payments</span></span></code></pre></div><p>The <code>--cursor-events-repo</code> flags on a deploy form its complete list and replace the previous one, so pass every repository on each redeploy. A deploy without the flag watches the agent&#39;s GitHub source repository instead. Use <a href="./../reference/cli.html#event-repos"><code>bdk event-repos</code></a> to change or clear the list without redeploying.</p><h2 id="pr-and-agent-affinity" tabindex="-1">PR and agent affinity <a class="header-anchor" href="#pr-and-agent-affinity" aria-label="Permalink to &quot;PR and agent affinity&quot;">​</a></h2><p>Every wake for the same repo and PR number resumes the same session. The channel keys turns as <code>github-pr:acme/checkout#42</code>. Opens, comments, and CI results share that conversation.</p><h2 id="call-github-from-determistic-code-via-ctx" tabindex="-1">Call GitHub from determistic code via <code>ctx</code> <a class="header-anchor" href="#call-github-from-determistic-code-via-ctx" aria-label="Permalink to &quot;Call GitHub from determistic code via \`ctx\`&quot;">​</a></h2><p><code>cursorAccount</code> puts one credential on both surfaces:</p><ul><li><p>Channel hooks: <code>ctx.github.getOctokit()</code>, <code>ctx.thread.post()</code>, <code>ctx.repository</code>, and <code>ctx.conversation</code></p></li><li><p>Tools: <code>ctx.host.github.getOctokit()</code></p></li></ul><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;">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;">pr</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>  --cursor-events-repo acme/payments</span></span></code></pre></div><p>The <code>--cursor-events-repo</code> flags on a deploy form its complete list and replace the previous one, so pass every repository on each redeploy. A deploy without the flag watches the agent&#39;s GitHub source repository instead. Use <a href="./../reference/cli.html#event-repos"><code>bdk event-repos</code></a> to change or clear the list without redeploying.</p><h2 id="pr-and-agent-affinity" tabindex="-1">PR and agent affinity <a class="header-anchor" href="#pr-and-agent-affinity" aria-label="Permalink to &quot;PR and agent affinity&quot;">​</a></h2><p>Every wake for the same repo and PR number resumes the same session. The channel keys turns as <code>github-pr:acme/checkout#42</code>. Opens, comments, and CI results share that conversation.</p><h2 id="call-github-from-deterministic-code-via-ctx" tabindex="-1">Call GitHub from deterministic code via <code>ctx</code> <a class="header-anchor" href="#call-github-from-deterministic-code-via-ctx" aria-label="Permalink to &quot;Call GitHub from deterministic code via \`ctx\`&quot;">​</a></h2><p><code>cursorAccount</code> puts one credential on both surfaces:</p><ul><li><p>Channel hooks: <code>ctx.github.getOctokit()</code>, <code>ctx.thread.post()</code>, <code>ctx.repository</code>, and <code>ctx.conversation</code></p></li><li><p>Tools: <code>ctx.host.github.getOctokit()</code></p></li></ul><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;">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;">pr</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;"> (pr.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;opened&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:#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>
@@ -159,4 +159,4 @@ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o
 <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;">GITHUB_TOKEN</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;">GITHUB_WEBHOOK_SECRET</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>Add a repository webhook for <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/github</code> with the same secret. Event pull and <code>github replay</code> target GitHub.com, so test Enterprise Server with saved fixtures.</p><p>Prefer event pull on github.com. Use the channel route directly when you already terminate GitHub webhooks yourself. Set a webhook secret on both sides. The <a href="./webhooks.html">Webhooks guide</a> covers the shared mechanism.</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="./../quickstart.html">Build a PR reviewer</a>: the full read and write loop, one step at a time</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>: the companion skill for coding agents</li></ul>`,56)])])}const g=i(h,[["render",e]]);export{o as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Add a repository webhook for <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/github</code> with the same secret. Event pull and <code>github replay</code> target GitHub.com, so test Enterprise Server with saved fixtures.</p><p>Prefer event pull on github.com. Use the channel route directly when you already terminate GitHub webhooks yourself. Set a webhook secret on both sides. The <a href="./webhooks.html">Webhooks guide</a> covers the shared mechanism.</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="./../quickstart.html">Build a PR reviewer</a>: the full read and write loop, one step at a time</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>: the companion skill for coding agents</li></ul>`,55)])])}const g=i(h,[["render",e]]);export{o as __pageData,g as default};

package/dist/docs/assets/{guides_github.md.Bq9kQU9B.lean.js → guides_github.md.Cr1Xlf-m.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks.","frontmatter":{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),h={name:"guides/github.md"};function e(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t("",56)])])}const g=i(h,[["render",e]]);export{o as __pageData,g as default};
+import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks.","frontmatter":{"title":"GitHub","description":"Let your agent read pull requests and CI, then write back reviews, comments, and checks."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),h={name:"guides/github.md"};function e(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t("",55)])])}const g=i(h,[["render",e]]);export{o as __pageData,g as default};

package/dist/docs/assets/{guides_gitlab.md.BM27P43u.js → guides_gitlab.md.CMpmFi4M.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab.","frontmatter":{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab."},"headers":[],"relativePath":"guides/gitlab.md","filePath":"guides/gitlab.md"}'),t={name:"guides/gitlab.md"};function h(l,s,p,k,E,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="gitlab-agents" tabindex="-1">GitLab agents <a class="header-anchor" href="#gitlab-agents" aria-label="Permalink to &quot;GitLab agents&quot;">​</a></h1><p>A GitLab agent wakes from a verified project event, reads the current project or merge-request state, and writes the result back to GitLab. <code>gitlabChannel()</code> supports the same hooks on GitLab.com and self-managed GitLab.</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-merge-request" tabindex="-1">Review a merge request <a class="header-anchor" href="#review-a-merge-request" aria-label="Permalink to &quot;Review a merge request&quot;">​</a></h2><p>Opening, reopening, or pushing commits to a merge request starts a review. The hook reads the latest diff through the project-bound GitLab client, the model returns a verdict, and the completed answer appears as a note on the merge 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/gitlab.ts</span></span>
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab.","frontmatter":{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab."},"headers":[],"relativePath":"guides/gitlab.md","filePath":"guides/gitlab.md"}'),t={name:"guides/gitlab.md"};function h(l,s,p,k,E,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="gitlab-agents" tabindex="-1">GitLab agents <a class="header-anchor" href="#gitlab-agents" aria-label="Permalink to &quot;GitLab agents&quot;">​</a></h1><p>A GitLab agent wakes from a verified project event, reads the current project or merge-request state, and writes the result back to GitLab. <code>gitlabChannel()</code> supports the same hooks on GitLab.com and self-managed GitLab.</p><h2 id="review-a-merge-request" tabindex="-1">Review a merge request <a class="header-anchor" href="#review-a-merge-request" aria-label="Permalink to &quot;Review a merge request&quot;">​</a></h2><p>Opening, reopening, or pushing commits to a merge request starts a review. The hook reads the latest diff through the project-bound GitLab client, the model returns a verdict, and the completed answer appears as a note on the merge 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/gitlab.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;">  createGitLabApi,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  defaultGitLabAuth,</span></span>
@@ -150,4 +150,4 @@ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const g
 <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 that carry the matching project-hook secret; <code>token</code> authorizes the API reads and writes in the examples.</p><p>Register the project webhook at <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/gitlab</code> with the same secret. For GitLab.com, 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 channel hooks with a merge request you can read before registering a live project 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 gitlab replay \\</span></span>
 <span class="line"><span>  https://gitlab.example.com/acme/platform/-/merge_requests/42 \\</span></span>
-<span class="line"><span>  --events &#39;*&#39;</span></span></code></pre></div><p>Use <code>--dry-run --out fixtures/gitlab</code> to save the payloads instead of posting them. <code>GITLAB_TOKEN</code> needs read access to the merge 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 GitLab payloads into regression fixtures</li></ul>`,40)])])}const o=i(t,[["render",h]]);export{g as __pageData,o as default};
+<span class="line"><span>  --events &#39;*&#39;</span></span></code></pre></div><p>Use <code>--dry-run --out fixtures/gitlab</code> to save the payloads instead of posting them. <code>GITLAB_TOKEN</code> needs read access to the merge 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 GitLab payloads into regression fixtures</li></ul>`,39)])])}const o=i(t,[["render",h]]);export{g as __pageData,o as default};

package/dist/docs/assets/{guides_gitlab.md.BM27P43u.lean.js → guides_gitlab.md.CMpmFi4M.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab.","frontmatter":{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab."},"headers":[],"relativePath":"guides/gitlab.md","filePath":"guides/gitlab.md"}'),t={name:"guides/gitlab.md"};function h(l,s,p,k,E,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",40)])])}const o=i(t,[["render",h]]);export{g as __pageData,o as default};
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab.","frontmatter":{"title":"GitLab","description":"Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab."},"headers":[],"relativePath":"guides/gitlab.md","filePath":"guides/gitlab.md"}'),t={name:"guides/gitlab.md"};function h(l,s,p,k,E,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",39)])])}const o=i(t,[["render",h]]);export{g as __pageData,o as default};

package/dist/docs/assets/{guides_grokbot-agents.md.yxVbSlKA.js → guides_grokbot-agents.md.tD1smFhU.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,e,l,h,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="grok-bot-agents" tabindex="-1">Grok Bot agents <a class="header-anchor" href="#grok-bot-agents" aria-label="Permalink to &quot;Grok Bot agents&quot;">​</a></h1><p>The <code>cursor-grokbot-agents</code> extension lets a BDK agent consult the Grok Bot agents on its serve host&#39;s Cursor account. The bot keeps its existing conversation, memory, and tools, while your agent carries the delivered reply back into the current conversation.</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><p>Use this extension on the local runtime. It consults another Grok Bot; it does not move this agent onto a Grok Bot runtime.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>List the bots your agent may contact and decide whether each new message needs approval. Descriptions teach the model when to choose one bot over another.</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/extensions/grokbot.ts</span></span>
+import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,e,l,h,p,d){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="grok-bot-agents" tabindex="-1">Grok Bot agents <a class="header-anchor" href="#grok-bot-agents" aria-label="Permalink to &quot;Grok Bot agents&quot;">​</a></h1><p>The <code>cursor-grokbot-agents</code> extension lets a BDK agent consult the Grok Bot agents on its serve host&#39;s Cursor account. The bot keeps its existing conversation, memory, and tools, while your agent carries the delivered reply back into the current conversation.</p><p>Use this extension on the local runtime. It consults another Grok Bot; it does not move this agent onto a Grok Bot runtime.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>List the bots your agent may contact and decide whether each new message needs approval. Descriptions teach the model when to choose one bot over another.</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/extensions/grokbot.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorGrokBotAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions/cursor-grokbot-agents&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;"> cursorGrokBotAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -13,4 +13,4 @@ import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u
 <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;">  needsApproval: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</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>Mounted as <code>grokbot</code>, the extension contributes <code>grokbot__ask</code>, <code>grokbot__check</code>, <code>grokbot__interrupt</code>, and <code>grokbot__list</code>, plus guidance for consulting them.</p><p>You can also scaffold the packaged example:</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 init ./grokbot --template grokbot-agents</span></span></code></pre></div><h2 id="ask-a-named-bot" tabindex="-1">Ask a named bot <a class="header-anchor" href="#ask-a-named-bot" aria-label="Permalink to &quot;Ask a named bot&quot;">​</a></h2><p>When someone says, &quot;Ask Plan Keeper whether we should move the picnic,&quot; your agent prepares one self-contained message, requests approval, and waits for the bot&#39;s delivered reply. That reply appears in the current conversation as the consultation result.</p><p>The message must include who is asking, the relevant facts, and the shape of the answer. The Grok Bot does not see the current BDK conversation.</p><blockquote><p>Netto is deciding whether to move Saturday&#39;s picnic. The forecast is 70% rain from 1-4pm. Recommend keep or move, give one reason, and name the best alternate time.</p></blockquote><p>When exactly one bot is configured, the model may omit its name.</p><h2 id="keep-waiting-for-a-long-reply" tabindex="-1">Keep waiting for a long reply <a class="header-anchor" href="#keep-waiting-for-a-long-reply" aria-label="Permalink to &quot;Keep waiting for a long reply&quot;">​</a></h2><p>If the bot is still working when <code>ask</code> reaches its wait limit, the tool returns <code>status: &quot;running&quot;</code> and any reply received so far. Your agent calls <code>check</code> for the same bot and reports the final answer when it arrives.</p><p><code>check</code> advances this caller&#39;s read position, so it returns only replies not already consumed. Check when the answer is needed instead of polling in a tight loop.</p><p>Earlier unread replies can arrive alongside the current result. Keep their order and pass them on when they still matter.</p><h2 id="interrupt-a-bot-turn" tabindex="-1">Interrupt a bot turn <a class="header-anchor" href="#interrupt-a-bot-turn" aria-label="Permalink to &quot;Interrupt a bot turn&quot;">​</a></h2><p>Use <code>interrupt</code> when the bot is pursuing the wrong task or the person changes direction. The active turn stops, but the host account&#39;s conversation with that bot remains, so a later <code>ask</code> continues with its existing memory.</p><blockquote><p>Stop Plan Keeper&#39;s current turn. Then ask it to compare indoor venues instead of changing the time.</p></blockquote><p>Only <code>ask</code> uses <code>needsApproval</code>. <code>check</code> and <code>interrupt</code> execute without an approval card, so expose this extension only to callers who may read or stop those bot conversations.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p><code>agents</code> is a name allowlist, not an existence check. A name outside the list is refused, but a misspelled configured name may create a new empty bot on first use. If a result says <code>created: true</code>, tell the person and check the name before sending more work.</p><p>With no <code>agents</code> list, any name is allowed and approval defaults on. Prefer an explicit list for a shared agent. <code>list</code> returns configured bots and bots this caller already contacted; it does not enumerate the whole account.</p><p>Calls use the serve host credential: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or <code>bdk login</code>. Use <code>apiKey</code> only when the extension should run under a different account.</p><p><code>pollIntervalMs</code> changes how often a waiting tool reads for new bot output. Keep the default unless the service needs a different balance between response latency and request volume.</p><h2 id="account-and-caller-boundaries" tabindex="-1">Account and caller boundaries <a class="header-anchor" href="#account-and-caller-boundaries" aria-label="Permalink to &quot;Account and caller boundaries&quot;">​</a></h2><p>Every tool reaches the serve host account&#39;s existing Grok Bot conversation. Authenticated BDK callers have separate contact lists and read positions, but they do not get separate Grok Bot accounts or isolated bot memory.</p><p>A shared bearer token or anonymous host also collapses callers into one BDK principal. Use per-caller auth when contact history and read positions must remain separate.</p><p>If <code>ask</code> finds the bot busy with an earlier message, it sends nothing. For a bot this caller already contacted, use <code>check</code> or <code>interrupt</code>. On first contact, wait for the existing turn in the Grok Bot app to finish, then ask again.</p><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to &quot;Adjust it&quot;">​</a></h2><p>To remove a capability such as <code>interrupt</code>, mount the extension as a directory and disable that tool. See <a href="./../reference/extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./../reference/extensions.html">Extensions</a>: namespaces, trust, and overlays</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Tool approvals</a>: approve asks</li></ul>`,36)])])}const k=t(o,[["render",i]]);export{u as __pageData,k as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Mounted as <code>grokbot</code>, the extension contributes <code>grokbot__ask</code>, <code>grokbot__check</code>, <code>grokbot__interrupt</code>, and <code>grokbot__list</code>, plus guidance for consulting them.</p><p>You can also scaffold the packaged example:</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 init ./grokbot --template grokbot-agents</span></span></code></pre></div><h2 id="ask-a-named-bot" tabindex="-1">Ask a named bot <a class="header-anchor" href="#ask-a-named-bot" aria-label="Permalink to &quot;Ask a named bot&quot;">​</a></h2><p>When someone says, &quot;Ask Plan Keeper whether we should move the picnic,&quot; your agent prepares one self-contained message, requests approval, and waits for the bot&#39;s delivered reply. That reply appears in the current conversation as the consultation result.</p><p>The message must include who is asking, the relevant facts, and the shape of the answer. The Grok Bot does not see the current BDK conversation.</p><blockquote><p>Avery is deciding whether to move Saturday&#39;s picnic. The forecast is 70% rain from 1-4pm. Recommend keep or move, give one reason, and name the best alternate time.</p></blockquote><p>When exactly one bot is configured, the model may omit its name.</p><h2 id="keep-waiting-for-a-long-reply" tabindex="-1">Keep waiting for a long reply <a class="header-anchor" href="#keep-waiting-for-a-long-reply" aria-label="Permalink to &quot;Keep waiting for a long reply&quot;">​</a></h2><p>If the bot is still working when <code>ask</code> reaches its wait limit, the tool returns <code>status: &quot;running&quot;</code> and any reply received so far. Your agent calls <code>check</code> for the same bot and reports the final answer when it arrives.</p><p><code>check</code> advances this caller&#39;s read position, so it returns only replies not already consumed. Check when the answer is needed instead of polling in a tight loop.</p><p>Earlier unread replies can arrive alongside the current result. Keep their order and pass them on when they still matter.</p><h2 id="interrupt-a-bot-turn" tabindex="-1">Interrupt a bot turn <a class="header-anchor" href="#interrupt-a-bot-turn" aria-label="Permalink to &quot;Interrupt a bot turn&quot;">​</a></h2><p>Use <code>interrupt</code> when the bot is pursuing the wrong task or the person changes direction. The active turn stops, but the host account&#39;s conversation with that bot remains, so a later <code>ask</code> continues with its existing memory.</p><blockquote><p>Stop Plan Keeper&#39;s current turn. Then ask it to compare indoor venues instead of changing the time.</p></blockquote><p>Only <code>ask</code> uses <code>needsApproval</code>. <code>check</code> and <code>interrupt</code> execute without an approval card, so expose this extension only to callers who may read or stop those bot conversations.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p><code>agents</code> is a name allowlist, not an existence check. A name outside the list is refused, but a misspelled configured name may create a new empty bot on first use. If a result says <code>created: true</code>, tell the person and check the name before sending more work.</p><p>With no <code>agents</code> list, any name is allowed and approval defaults on. Prefer an explicit list for a shared agent. <code>list</code> returns configured bots and bots this caller already contacted; it does not enumerate the whole account.</p><p>Calls use the serve host credential: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or <code>bdk login</code>. Use <code>apiKey</code> only when the extension should run under a different account.</p><p><code>pollIntervalMs</code> changes how often a waiting tool reads for new bot output. Keep the default unless the service needs a different balance between response latency and request volume.</p><h2 id="account-and-caller-boundaries" tabindex="-1">Account and caller boundaries <a class="header-anchor" href="#account-and-caller-boundaries" aria-label="Permalink to &quot;Account and caller boundaries&quot;">​</a></h2><p>Every tool reaches the serve host account&#39;s existing Grok Bot conversation. Authenticated BDK callers have separate contact lists and read positions, but they do not get separate Grok Bot accounts or isolated bot memory.</p><p>A shared bearer token or anonymous host also collapses callers into one BDK principal. Use per-caller auth when contact history and read positions must remain separate.</p><p>If <code>ask</code> finds the bot busy with an earlier message, it sends nothing. For a bot this caller already contacted, use <code>check</code> or <code>interrupt</code>. On first contact, wait for the existing turn in the Grok Bot app to finish, then ask again.</p><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to &quot;Adjust it&quot;">​</a></h2><p>To remove a capability such as <code>interrupt</code>, mount the extension as a directory and disable that tool. See <a href="./../reference/extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./../reference/extensions.html">Extensions</a>: namespaces, trust, and overlays</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Tool approvals</a>: approve asks</li></ul>`,35)])])}const k=t(o,[["render",i]]);export{u as __pageData,k as default};

package/dist/docs/assets/{guides_grokbot-agents.md.yxVbSlKA.lean.js → guides_grokbot-agents.md.tD1smFhU.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,e,l,h,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n("",36)])])}const k=t(o,[["render",i]]);export{u as __pageData,k as default};
+import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,e,l,h,p,d){return s(),a("div",null,[...e[0]||(e[0]=[n("",35)])])}const k=t(o,[["render",i]]);export{u as __pageData,k as default};

package/dist/docs/assets/{guides_hooks.md.BWoiNaMq.js → guides_hooks.md.5Ce3NXxZ.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>Hooks observe session events after they are recorded and run side effects such as updating metrics or sending alerts. They never change the turn, prompt, or reply. Author them under <code>bot/hooks/</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="meter-token-usage" tabindex="-1">Meter token usage <a class="header-anchor" href="#meter-token-usage" aria-label="Permalink to &quot;Meter token usage&quot;">​</a></h2><p>With <a href="./opentelemetry.html">OpenTelemetry</a> configured, this hook adds a live turn&#39;s reported input and output tokens to your counters. Eval runs stay quiet, so the dashboard reflects live traffic instead of the test suite.</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/hooks/usage.ts</span></span>
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>Hooks observe session events after they are recorded and run side effects such as updating metrics or sending alerts. They never change the turn, prompt, or reply. Author them under <code>bot/hooks/</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>.</p><h2 id="meter-token-usage" tabindex="-1">Meter token usage <a class="header-anchor" href="#meter-token-usage" aria-label="Permalink to &quot;Meter token usage&quot;">​</a></h2><p>With <a href="./opentelemetry.html">OpenTelemetry</a> configured, this hook adds a live turn&#39;s reported input and output tokens to your counters. Eval runs stay quiet, so the dashboard reflects live traffic instead of the test suite.</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/hooks/usage.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/hooks&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;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -47,4 +47,4 @@ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E
 <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><h2 id="events-when-hooks-run" tabindex="-1">Events / when hooks run <a class="header-anchor" href="#events-when-hooks-run" aria-label="Permalink to &quot;Events / when hooks run&quot;">​</a></h2><p>Use event names from the <a href="./../reference/sessions.html#stream-events">session event vocabulary</a>. A hook receives each matching event after it is recorded, and the model does not wait for the handler.</p><p>Within one session, handlers run one at a time. A slow handler delays later handlers for that session, but it does not delay the model or handlers for other sessions. Hooks also fire for evals, so check <code>ctx.session.purpose === &quot;eval&quot;</code> before metering or paging. A restart does not replay recorded events into hooks.</p><h2 id="when-not-to-use-a-hook" tabindex="-1">When not to use a hook <a class="header-anchor" href="#when-not-to-use-a-hook" aria-label="Permalink to &quot;When not to use a hook&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Want</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model</td><td><code>instructions.md</code>, skills, or <code>workspaceFiles</code></td></tr><tr><td>Deliver to Slack or a PR</td><td>Channel <a href="./../reference/channels.html#events"><code>events</code></a> or packs</td></tr><tr><td>Block or approve a tool</td><td><a href="./../reference/tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a></td></tr><tr><td>Gate final assistant text</td><td><code>defineResult</code></td></tr><tr><td>Gate behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a> in <code>.cursor/hooks.json</code> are a different product. They can observe, block, or modify the local agent loop.</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/hooks.html">Hooks reference</a>: payloads, context, and discovery</li><li><a href="./../reference/sessions.html#stream-events">Sessions: stream events</a>: event vocabulary and payload sequence</li><li><a href="./opentelemetry.html">OpenTelemetry</a>: export traces and custom metrics</li><li><a href="./../reference/channels.html#events">Channels: events</a>: deliver replies back to Slack, source control, or another surface</li></ul>`,17)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="events-when-hooks-run" tabindex="-1">Events / when hooks run <a class="header-anchor" href="#events-when-hooks-run" aria-label="Permalink to &quot;Events / when hooks run&quot;">​</a></h2><p>Use event names from the <a href="./../reference/sessions.html#stream-events">session event vocabulary</a>. A hook receives each matching event after it is recorded, and the model does not wait for the handler.</p><p>Within one session, handlers run one at a time. A slow handler delays later handlers for that session, but it does not delay the model or handlers for other sessions. Hooks also fire for evals, so check <code>ctx.session.purpose === &quot;eval&quot;</code> before metering or paging. A restart does not replay recorded events into hooks.</p><h2 id="when-not-to-use-a-hook" tabindex="-1">When not to use a hook <a class="header-anchor" href="#when-not-to-use-a-hook" aria-label="Permalink to &quot;When not to use a hook&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Want</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model</td><td><code>instructions.md</code>, skills, or <code>workspaceFiles</code></td></tr><tr><td>Deliver to Slack or a PR</td><td>Channel <a href="./../reference/channels.html#events"><code>events</code></a> or packs</td></tr><tr><td>Block or approve a tool</td><td><a href="./../reference/tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a></td></tr><tr><td>Gate final assistant text</td><td><code>defineResult</code></td></tr><tr><td>Gate behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a> in <code>.cursor/hooks.json</code> are a different product. They can observe, block, or modify the local agent loop.</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/hooks.html">Hooks reference</a>: payloads, context, and discovery</li><li><a href="./../reference/sessions.html#stream-events">Sessions: stream events</a>: event vocabulary and payload sequence</li><li><a href="./opentelemetry.html">OpenTelemetry</a>: export traces and custom metrics</li><li><a href="./../reference/channels.html#events">Channels: events</a>: deliver replies back to Slack, source control, or another surface</li></ul>`,16)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};

package/dist/docs/assets/{guides_hooks.md.BWoiNaMq.lean.js → guides_hooks.md.5Ce3NXxZ.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e("",17)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e("",16)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};

package/dist/docs/assets/{guides_improve.md.COtL-6ft.js → guides_improve.md.CRrYq22s.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.","frontmatter":{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(r,e,l,h,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="self-improvement" tabindex="-1">Self-improvement <a class="header-anchor" href="#self-improvement" aria-label="Permalink to &quot;Self-improvement&quot;">​</a></h1><p>The <code>improve</code> extension teaches an agent how to turn &quot;change how you work&quot; into a source change. The agent prepares a brief, a Cursor cloud agent edits a checkout and opens a pull request, and the running agent reports the verified PR for human review.</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><p>Durable behavior does not change until that source is merged and deployed.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>Mount Cloud agents with the agent&#39;s own repository allowlisted, keep launch approval explicit, then mount <code>improve</code> with the source directory.</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/extensions/cloud.ts</span></span>
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.","frontmatter":{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(r,e,l,h,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="self-improvement" tabindex="-1">Self-improvement <a class="header-anchor" href="#self-improvement" aria-label="Permalink to &quot;Self-improvement&quot;">​</a></h1><p>The <code>improve</code> extension teaches an agent how to turn &quot;change how you work&quot; into a source change. The agent prepares a brief, a Cursor cloud agent edits a checkout and opens a pull request, and the running agent reports the verified PR for human review.</p><p>Durable behavior does not change until that source is merged and deployed.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>Mount Cloud agents with the agent&#39;s own repository allowlisted, keep launch approval explicit, then mount <code>improve</code> with the source directory.</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/extensions/cloud.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorCloudAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions/cursor-cloud-agents&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;"> cursorCloudAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -19,4 +19,4 @@ import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  repo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/agents&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agents/concierge&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ref: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;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></code></pre></div><p>Mounted as <code>improve</code>, the extension contributes the <code>improve__yourself</code> skill. It does not contribute a tool that can bypass the normal repository workflow.</p><h2 id="ask-for-one-behavioral-change" tabindex="-1">Ask for one behavioral change <a class="header-anchor" href="#ask-for-one-behavioral-change" aria-label="Permalink to &quot;Ask for one behavioral change&quot;">​</a></h2><p>State the change, how to tell it worked, and what behavior must stay fixed. The agent maps the request to instructions, a skill, a tool, channel configuration, or the model setting before preparing the coding brief.</p><blockquote><p>Improve yourself: stop opening incident replies with a summary. Start with the decision, keep the existing evidence bullets, and preserve every current eval.</p></blockquote><p>The success criterion and freeze line keep the cloud agent from turning a narrow behavior request into an unrelated refactor.</p><h2 id="follow-the-source-change" tabindex="-1">Follow the source change <a class="header-anchor" href="#follow-the-source-change" aria-label="Permalink to &quot;Follow the source change&quot;">​</a></h2><p>The agent requests approval and launches one cloud agent on the configured repository and ref. It reports the complete cloud-agent ID and URL immediately, then checks the same run instead of launching another agent for follow-up work.</p><p>When the cloud agent opens a pull request, the running agent reads the result and the PR before reporting what changed and which checks passed. The pull request, not the delegation transcript, is the durable deliverable.</p><p>Use the <a href="./cloud-agents.html">Cloud agents guide</a> for launch, status, transcript, steering, and cancellation behavior.</p><h2 id="review-merge-then-deploy" tabindex="-1">Review, merge, then deploy <a class="header-anchor" href="#review-merge-then-deploy" aria-label="Permalink to &quot;Review, merge, then deploy&quot;">​</a></h2><p>The workflow stops at a pull request. A human reviews the diff and decides whether to merge it; a separate deployment action decides when the new behavior becomes live.</p><p>This separation gives each boundary a real control:</p><ul><li>Repository permissions limit who can push the branch.</li><li>Branch protection and review policy govern the merge.</li><li>Deployment authorization governs the running agent.</li></ul><p>After deployment, repeat the original request or regression eval to confirm the behavior changed without crossing the freeze line.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><ul><li><code>repo</code> is the source repository URL.</li><li><code>path</code> is the agent&#39;s repository-relative directory.</li><li><code>ref</code> is the deployed branch or ref that new branches and pull requests target; it defaults to <code>main</code>.</li><li><code>notes</code> adds tree-specific guidance to every coding brief, such as a required test command or PR convention.</li><li><code>deploy</code> tells the skill who deploys a merged change and when it becomes live.</li></ul><p><code>notes</code> and <code>deploy</code> insert prose into the contributed skill. They do not run checks, merge a branch, or trigger a deployment.</p><p>Validation checks the URL and path shape. It does not prove the source exists, matches the current deployment, or appears in the Cloud agents repository allowlist, so keep those values aligned yourself.</p><h2 id="what-the-extension-enforces" tabindex="-1">What the extension enforces <a class="header-anchor" href="#what-the-extension-enforces" aria-label="Permalink to &quot;What the extension enforces&quot;">​</a></h2><p><code>improve__yourself</code> is model guidance for locating the change, writing a brief, following repository rules, opening a PR, and reporting it. Rules such as &quot;never merge&quot; are instructions, not framework-enforced permissions.</p><p>Use repository and deployment controls for hard enforcement. The extension provides a repeatable path through those controls; it does not replace them.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./cloud-agents.html">Cloud agents</a>: delegation and steering</li><li><a href="./../building-with-agents.html">Build with a coding agent</a>: have an external coding agent edit the project directly</li><li><a href="./../reference/extensions.html">Extensions</a>: namespaces and overlays</li><li><a href="./../deployment.html">Deployment</a>: make a merged source change live</li><li><a href="./../evals.html">Evals</a>: protect the requested behavior before and after the change</li></ul>`,31)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Mounted as <code>improve</code>, the extension contributes the <code>improve__yourself</code> skill. It does not contribute a tool that can bypass the normal repository workflow.</p><h2 id="ask-for-one-behavioral-change" tabindex="-1">Ask for one behavioral change <a class="header-anchor" href="#ask-for-one-behavioral-change" aria-label="Permalink to &quot;Ask for one behavioral change&quot;">​</a></h2><p>State the change, how to tell it worked, and what behavior must stay fixed. The agent maps the request to instructions, a skill, a tool, channel configuration, or the model setting before preparing the coding brief.</p><blockquote><p>Improve yourself: stop opening incident replies with a summary. Start with the decision, keep the existing evidence bullets, and preserve every current eval.</p></blockquote><p>The success criterion and freeze line keep the cloud agent from turning a narrow behavior request into an unrelated refactor.</p><h2 id="follow-the-source-change" tabindex="-1">Follow the source change <a class="header-anchor" href="#follow-the-source-change" aria-label="Permalink to &quot;Follow the source change&quot;">​</a></h2><p>The agent requests approval and launches one cloud agent on the configured repository and ref. It reports the complete cloud-agent ID and URL immediately, then checks the same run instead of launching another agent for follow-up work.</p><p>When the cloud agent opens a pull request, the running agent reads the result and the PR before reporting what changed and which checks passed. The pull request, not the delegation transcript, is the durable deliverable.</p><p>Use the <a href="./cloud-agents.html">Cloud agents guide</a> for launch, status, transcript, steering, and cancellation behavior.</p><h2 id="review-merge-then-deploy" tabindex="-1">Review, merge, then deploy <a class="header-anchor" href="#review-merge-then-deploy" aria-label="Permalink to &quot;Review, merge, then deploy&quot;">​</a></h2><p>The workflow stops at a pull request. A human reviews the diff and decides whether to merge it; a separate deployment action decides when the new behavior becomes live.</p><p>This separation gives each boundary a real control:</p><ul><li>Repository permissions limit who can push the branch.</li><li>Branch protection and review policy govern the merge.</li><li>Deployment authorization governs the running agent.</li></ul><p>After deployment, repeat the original request or regression eval to confirm the behavior changed without crossing the freeze line.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><ul><li><code>repo</code> is the source repository URL.</li><li><code>path</code> is the agent&#39;s repository-relative directory.</li><li><code>ref</code> is the deployed branch or ref that new branches and pull requests target; it defaults to <code>main</code>.</li><li><code>notes</code> adds tree-specific guidance to every coding brief, such as a required test command or PR convention.</li><li><code>deploy</code> tells the skill who deploys a merged change and when it becomes live.</li></ul><p><code>notes</code> and <code>deploy</code> insert prose into the contributed skill. They do not run checks, merge a branch, or trigger a deployment.</p><p>Validation checks the URL and path shape. It does not prove the source exists, matches the current deployment, or appears in the Cloud agents repository allowlist, so keep those values aligned yourself.</p><h2 id="what-the-extension-enforces" tabindex="-1">What the extension enforces <a class="header-anchor" href="#what-the-extension-enforces" aria-label="Permalink to &quot;What the extension enforces&quot;">​</a></h2><p><code>improve__yourself</code> is model guidance for locating the change, writing a brief, following repository rules, opening a PR, and reporting it. Rules such as &quot;never merge&quot; are instructions, not framework-enforced permissions.</p><p>Use repository and deployment controls for hard enforcement. The extension provides a repeatable path through those controls; it does not replace them.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./cloud-agents.html">Cloud agents</a>: delegation and steering</li><li><a href="./../building-with-agents.html">Build with a coding agent</a>: have an external coding agent edit the project directly</li><li><a href="./../reference/extensions.html">Extensions</a>: namespaces and overlays</li><li><a href="./../deployment.html">Deployment</a>: make a merged source change live</li><li><a href="./../evals.html">Evals</a>: protect the requested behavior before and after the change</li></ul>`,30)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{guides_improve.md.COtL-6ft.lean.js → guides_improve.md.CRrYq22s.lean.js}

@@ -1 +1 @@
-import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.","frontmatter":{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(r,e,l,h,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",31)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.","frontmatter":{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(r,e,l,h,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",30)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{guides_jev.md.CRcgmjDb.js → guides_jev.md.D7XH4JH3.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="use-jev-in-review-tools" tabindex="-1">Use Jev in review tools <a class="header-anchor" href="#use-jev-in-review-tools" aria-label="Permalink to &quot;Use Jev in review tools&quot;">​</a></h1><p>Use Jev when a review workflow needs a typed decision instead of prose. A review agent can filter speculative findings, classify pull request risk, choose a reviewer, or decide whether a merge needs a documentation follow-up. Jev returns a choice, score, or probability; your TypeScript decides what happens next.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>Set <code>TYPESAFE_API_KEY</code>. The default model is <code>jev-latest</code>.</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/extensions/jev.ts</span></span>
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="use-jev-in-review-tools" tabindex="-1">Use Jev in review tools <a class="header-anchor" href="#use-jev-in-review-tools" aria-label="Permalink to &quot;Use Jev in review tools&quot;">​</a></h1><p>Use Jev when a review workflow needs a typed decision instead of prose. A review agent can filter speculative findings, classify pull request risk, choose a reviewer, or decide whether a merge needs a documentation follow-up. Jev returns a choice, score, or probability; your TypeScript decides what happens next.</p><p>Set <code>TYPESAFE_API_KEY</code>. The default model is <code>jev-latest</code>.</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/extensions/jev.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> jev </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions/jev&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;"> jev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>On Cursor-managed hosting, this mount adds <code>api.typesafe.ai</code> to the deployment&#39;s egress allowlist and <code>TYPESAFE_API_KEY</code> to the secrets it expects, so <code>bdk deploy</code> warns until you set the key. A project that imports <code>decide</code> or <code>evaluate</code> without mounting the extension has to list <code>api.typesafe.ai</code> in <code>hosting.egressDomains</code> itself; see <a href="./../deployment.html#add-egress-and-secrets">Add egress and secrets</a>.</p><h2 id="start-only-the-review-turns-you-need" tabindex="-1">Start only the review turns you need <a class="header-anchor" href="#start-only-the-review-turns-you-need" aria-label="Permalink to &quot;Start only the review turns you need&quot;">​</a></h2><p>Call Jev from a channel hook before a model turn starts. When a pull request opens or becomes ready for review, this hook sends its title, body, labels, and filenames to Jev to decide whether the change needs security review. A result that clears the threshold starts the review turn; otherwise, the hook returns <code>null</code>, so the agent doesn&#39;t run or post to GitHub.</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/github.ts</span></span>
@@ -148,4 +148,4 @@ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o
 <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;"> jev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  harnessTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  skills: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</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><code>harnessTools: false</code> removes <code>jev__evaluate</code> from discovery. <code>skills: false</code> removes both Jev skills. These switches do not remove the exported helpers, so project tools can still import <code>decide</code>, <code>above</code>, and <code>needsHuman</code>.</p><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;">​</a></h2><ul><li><p>Pass the pull request title, a short summary, and the draft finding. Don&#39;t send the checkout.</p></li><li><p>Calibrate <code>above</code> and <code>needsHuman</code> on pull requests you have already labeled. <code>needsHuman</code> defaults to <code>0.7</code>.</p></li></ul><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="./../templates/agentic-owners.html">Agentic owners</a>: a risk tier, then the host approves or asks for reviewers</li><li><a href="./../templates/security-reviewer.html">Security reviewer</a>: a finding, or no comment</li><li><a href="./../templates/thermo-review.html">Thermo review</a>: bugs and breakage, posted the same way</li><li><a href="./../reference/cli.html#init">Code wiki</a>: documentation follow-ups after a merge</li><li><a href="./../evals.html">Evals</a>: checks on the full turn</li><li><a href="./github.html">GitHub agents</a>: how the review gets onto the pull request</li></ul>`,39)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>harnessTools: false</code> removes <code>jev__evaluate</code> from discovery. <code>skills: false</code> removes both Jev skills. These switches do not remove the exported helpers, so project tools can still import <code>decide</code>, <code>above</code>, and <code>needsHuman</code>.</p><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;">​</a></h2><ul><li><p>Pass the pull request title, a short summary, and the draft finding. Don&#39;t send the checkout.</p></li><li><p>Calibrate <code>above</code> and <code>needsHuman</code> on pull requests you have already labeled. <code>needsHuman</code> defaults to <code>0.7</code>.</p></li></ul><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="./../templates/agentic-owners.html">Agentic owners</a>: a risk tier, then the host approves or asks for reviewers</li><li><a href="./../templates/security-reviewer.html">Security reviewer</a>: a finding, or no comment</li><li><a href="./../templates/thermo-review.html">Thermo review</a>: bugs and breakage, posted the same way</li><li><a href="./../reference/cli.html#init">Code wiki</a>: documentation follow-ups after a merge</li><li><a href="./../evals.html">Evals</a>: checks on the full turn</li><li><a href="./github.html">GitHub agents</a>: how the review gets onto the pull request</li></ul>`,38)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};

package/dist/docs/assets/{guides_jev.md.CRcgmjDb.lean.js → guides_jev.md.D7XH4JH3.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e("",39)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e("",38)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};

package/dist/docs/assets/{guides_mcp-oauth.md.Cu6mhZ_3.js → guides_mcp-oauth.md.DR3zhC9r.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function h(l,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="connect-a-private-mcp-server-with-oauth" tabindex="-1">Connect a private MCP server with OAuth <a class="header-anchor" href="#connect-a-private-mcp-server-with-oauth" aria-label="Permalink to &quot;Connect a private MCP server with OAuth&quot;">​</a></h1><p>Host MCP OAuth lets a BDK process authorize a remote MCP server without putting tokens in the agent&#39;s source or workspace. Use it when the server speaks OAuth and its credentials should belong to the serve host instead of a person&#39;s Cursor account.</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="use-a-private-mcp-tool-locally" tabindex="-1">Use a private MCP tool locally <a class="header-anchor" href="#use-a-private-mcp-tool-locally" aria-label="Permalink to &quot;Use a private MCP tool locally&quot;">​</a></h2><p>Declare the remote server, authorize it once in the browser, and start the agent. The next local turn can call the server&#39;s named tools with the credentials stored on that host.</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/mcp-connections/inventory.ts</span></span>
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function h(l,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="connect-a-private-mcp-server-with-oauth" tabindex="-1">Connect a private MCP server with OAuth <a class="header-anchor" href="#connect-a-private-mcp-server-with-oauth" aria-label="Permalink to &quot;Connect a private MCP server with OAuth&quot;">​</a></h1><p>Host MCP OAuth lets a BDK process authorize a remote MCP server without putting tokens in the agent&#39;s source or workspace. Use it when the server speaks OAuth and its credentials should belong to the serve host instead of a person&#39;s Cursor account.</p><h2 id="use-a-private-mcp-tool-locally" tabindex="-1">Use a private MCP tool locally <a class="header-anchor" href="#use-a-private-mcp-tool-locally" aria-label="Permalink to &quot;Use a private MCP tool locally&quot;">​</a></h2><p>Declare the remote server, authorize it once in the browser, and start the agent. The next local turn can call the server&#39;s named tools with the credentials stored on that host.</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/mcp-connections/inventory.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/connections&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;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -47,4 +47,4 @@ import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
 <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><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 mcp oauth inventory --store</span></span>
 <span class="line"><span>bdk secrets list my-agent</span></span>
-<span class="line"><span>bdk deploy</span></span></code></pre></div><p><code>--store</code> writes deployment secrets; it does not restart the current engine. Follow the CLI or dashboard prompt to redeploy, then exercise the hosted agent.</p><p>These credentials belong to the deployment, not to the person who clicked Connect. Anyone able to use that agent can reach the MCP capabilities you expose, so keep privileged servers host-only or narrow their tool list.</p><h2 id="choose-where-credentials-live" tabindex="-1">Choose where credentials live <a class="header-anchor" href="#choose-where-credentials-live" aria-label="Permalink to &quot;Choose where credentials live&quot;">​</a></h2><p>Use the credential shape that matches who should own access:</p><ul><li><p>Choose <code>cursorAccount: true</code> for connectors already authorized under MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.</p></li><li><p>Choose <code>url</code> with <code>oauth: true</code> when the serve host or hosted deployment should hold OAuth credentials.</p></li><li><p>Choose <code>url</code> with static <code>headers</code> when the server uses an API key or bearer token instead of OAuth.</p></li></ul><p>Host OAuth and per-session <code>auth</code> are different identity models and cannot be combined on one connection. Use per-session auth when each caller needs a different downstream identity.</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="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>: the companion setup procedure for coding agents</li><li><a href="./../reference/connections.html">MCP connections</a>: transports, account connectors, per-session auth, and tool filtering</li><li><a href="./../reference/cli.html#mcp-oauth">CLI reference</a>: OAuth command flags and browser callback behavior</li><li><a href="./../deployment.html">Deployment</a>: hosted secrets and egress</li><li><a href="./../troubleshooting.html">Troubleshooting</a>: authorization symptoms and remedies</li></ul>`,29)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
+<span class="line"><span>bdk deploy</span></span></code></pre></div><p><code>--store</code> writes deployment secrets; it does not restart the current process. Follow the CLI or dashboard prompt to redeploy, then exercise the hosted agent.</p><p>These credentials belong to the deployment, not to the person who clicked Connect. Anyone able to use that agent can reach the MCP capabilities you expose, so keep privileged servers host-only or narrow their tool list.</p><h2 id="choose-where-credentials-live" tabindex="-1">Choose where credentials live <a class="header-anchor" href="#choose-where-credentials-live" aria-label="Permalink to &quot;Choose where credentials live&quot;">​</a></h2><p>Use the credential shape that matches who should own access:</p><ul><li><p>Choose <code>cursorAccount: true</code> for connectors already authorized under MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.</p></li><li><p>Choose <code>url</code> with <code>oauth: true</code> when the serve host or hosted deployment should hold OAuth credentials.</p></li><li><p>Choose <code>url</code> with static <code>headers</code> when the server uses an API key or bearer token instead of OAuth.</p></li></ul><p>Host OAuth and per-session <code>auth</code> are different identity models and cannot be combined on one connection. Use per-session auth when each caller needs a different downstream identity.</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="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>: the companion setup procedure for coding agents</li><li><a href="./../reference/connections.html">MCP connections</a>: transports, account connectors, per-session auth, and tool filtering</li><li><a href="./../reference/cli.html#mcp-oauth">CLI reference</a>: OAuth command flags and browser callback behavior</li><li><a href="./../deployment.html">Deployment</a>: hosted secrets and egress</li><li><a href="./../troubleshooting.html">Troubleshooting</a>: authorization symptoms and remedies</li></ul>`,28)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{guides_mcp-oauth.md.Cu6mhZ_3.lean.js → guides_mcp-oauth.md.DR3zhC9r.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function h(l,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",29)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function h(l,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",28)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{guides_opentelemetry.md.DLlIB5rv.js → guides_opentelemetry.md.jcPNrQbH.js}

@@ -1,8 +1,10 @@
-import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function o(l,s,p,r,h,d){return t(),a("div",null,[...s[0]||(s[0]=[i(`<h1 id="observe-an-agent-with-opentelemetry" tabindex="-1">Observe an agent with OpenTelemetry <a class="header-anchor" href="#observe-an-agent-with-opentelemetry" aria-label="Permalink to &quot;Observe an agent with OpenTelemetry&quot;">​</a></h1><p>OpenTelemetry connects an agent turn to the observability system your team already uses. Once you configure an OTLP collector, each request, model turn, tool call, and subagent appears alongside token, tool, and cost metrics from the serve process.</p><p>Export is opt-in. Nothing leaves the process until you configure a destination.</p><p>The <code>bdk</code> commands on this page are docs-ahead until <code>@cursor/bdk</code> is published; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="connect-an-otlp-collector" tabindex="-1">Connect an OTLP collector <a class="header-anchor" href="#connect-an-otlp-collector" aria-label="Permalink to &quot;Connect an OTLP collector&quot;">​</a></h2><p>Set the collector endpoint, start the agent, and send it a message. You should see an <code>agent_sdk.http</code> request span and an <code>agent_sdk.turn</code> trace, with any tool or subagent work nested under the turn.</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>export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com</span></span>
-<span class="line"><span>export OTEL_EXPORTER_OTLP_HEADERS=&quot;Authorization=Bearer $OTEL_TOKEN&quot;</span></span>
-<span class="line"><span>export OTEL_SERVICE_NAME=incident-agent</span></span>
-<span class="line"><span></span></span>
-<span class="line"><span>bdk serve --dir . --dev</span></span></code></pre></div><p>The default protocol is OTLP/HTTP protobuf. If you already call <code>serve()</code> from TypeScript, you can configure the same destination in code:</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;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir, {</span></span>
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function l(o,s,p,h,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="observe-an-agent-with-opentelemetry" tabindex="-1">Observe an agent with OpenTelemetry <a class="header-anchor" href="#observe-an-agent-with-opentelemetry" aria-label="Permalink to &quot;Observe an agent with OpenTelemetry&quot;">​</a></h1><p>OpenTelemetry connects an agent turn to the observability system your team already uses. Once you configure an OTLP collector, each request, model turn, tool call, and subagent appears alongside token, tool, and cost metrics from the serve process.</p><p>Export is opt-in. Nothing leaves the process until you configure a destination.</p><h2 id="connect-an-otlp-collector" tabindex="-1">Connect an OTLP collector <a class="header-anchor" href="#connect-an-otlp-collector" aria-label="Permalink to &quot;Connect an OTLP collector&quot;">​</a></h2><p>Set the collector endpoint, start the agent, and send it a message. You should see an <code>agent_sdk.http</code> request span and an <code>agent_sdk.turn</code> trace, with any tool or subagent work nested under the turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Authorization=Bearer </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$OTEL_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident-agent</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><p>The default protocol is OTLP/HTTP protobuf. If you already call <code>serve()</code> from TypeScript, you can configure the same destination in code:</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { serve } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&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;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</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;">  otel: {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    serviceName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    exporters: [</span></span>
@@ -32,4 +34,4 @@ import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  outcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approved&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>This API is available in tools, hooks, and channel handlers. A session-bound context adds <code>cursor.conversation.id</code> and <code>agent_sdk.agent</code> automatically, so custom measurements join the first-party telemetry without extra plumbing.</p><p>Prefix custom names with your team or agent. First-party metric names and join keys are reserved, and this surface does not create custom spans.</p><h2 id="choose-signals" tabindex="-1">Choose signals <a class="header-anchor" href="#choose-signals" aria-label="Permalink to &quot;Choose signals&quot;">​</a></h2><p>Once export has a destination, traces and metrics are on by default; logs remain off until you opt in.</p><table tabindex="0"><thead><tr><th>Signal</th><th>What appears</th></tr></thead><tbody><tr><td>Traces</td><td>HTTP requests, turns, tools, and subagents</td></tr><tr><td>Metrics</td><td>Token usage, tool calls, cost, and BDK session or turn counts</td></tr><tr><td>Logs</td><td>Session events, after you enable log export</td></tr></tbody></table><p>The first metrics to look for are <code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, and <code>cursor.cost.usage</code>. Configure <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: true</code> under <code>serve({ otel })</code> when you need a different signal mix.</p><h2 id="control-what-leaves-the-process" tabindex="-1">Control what leaves the process <a class="header-anchor" href="#control-what-leaves-the-process" aria-label="Permalink to &quot;Control what leaves the process&quot;">​</a></h2><p>User prompts, tool arguments, tool results, and failure text stay off the wire by default. You still get trace structure, tool names and status, usage metrics, and generic failure status without exporting the underlying content.</p><p>Turn on logs first, then opt into prompt or tool content separately:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOGS_EXPORTER</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">otlp</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOG_USER_PROMPTS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOG_TOOL_CONTENT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span></code></pre></div><p><code>OTEL_LOG_USER_PROMPTS</code> exports user text. <code>OTEL_LOG_TOOL_CONTENT</code> exports tool inputs, outputs, and failure details. Enable either only when the collector&#39;s access and retention policies are appropriate for that data.</p><p>The same controls are available as <code>logs: { userPrompts, toolContent }</code> under <code>serve({ otel })</code>.</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="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>: compact configuration and custom-metric reference for coding agents</li><li><a href="./../reference/hooks.html">Hooks</a>: emit domain telemetry from session events</li><li><a href="./../deployment.html">Deployment</a>: set collector endpoints and secrets on hosted or self-hosted agents</li><li><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>: send organization-wide Cursor telemetry to the same collector</li></ul>`,32)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOG_TOOL_CONTENT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span></code></pre></div><p><code>OTEL_LOG_USER_PROMPTS</code> exports user text. <code>OTEL_LOG_TOOL_CONTENT</code> exports tool inputs, outputs, and failure details. Enable either only when the collector&#39;s access and retention policies are appropriate for that data.</p><p>The same controls are available as <code>logs: { userPrompts, toolContent }</code> under <code>serve({ otel })</code>.</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="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>: compact configuration and custom-metric reference for coding agents</li><li><a href="./../reference/hooks.html">Hooks</a>: emit domain telemetry from session events</li><li><a href="./../deployment.html">Deployment</a>: set collector endpoints and secrets on hosted or self-hosted agents</li><li><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>: send organization-wide Cursor telemetry to the same collector</li></ul>`,31)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{guides_opentelemetry.md.DLlIB5rv.lean.js → guides_opentelemetry.md.jcPNrQbH.lean.js}

@@ -1 +1 @@
-import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function o(l,s,p,r,h,d){return t(),a("div",null,[...s[0]||(s[0]=[i("",32)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function l(o,s,p,h,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t("",31)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};