@cursor/july 0.1.111 → 0.1.113

package/dist/docs/assets/guides_bitbucket.md.CTpCl__f.js

@@ -1,10 +0,0 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Bitbucket","description":"Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center.","frontmatter":{"title":"Bitbucket","description":"Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center."},"headers":[],"relativePath":"guides/bitbucket.md","filePath":"guides/bitbucket.md"}'),n={name:"guides/bitbucket.md"};function l(h,e,p,o,r,d){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="bitbucket-agents" tabindex="-1">Bitbucket agents <a class="header-anchor" href="#bitbucket-agents" aria-label="Permalink to &quot;Bitbucket agents&quot;">​</a></h1><p>Use <code>bitbucketChannel()</code> for Bitbucket Cloud and Bitbucket Data Center. The channel detects the source from each signed payload and normalizes Data Center events to the Bitbucket Cloud event vocabulary.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/bitbucket.ts</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;"> { bitbucketChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/bitbucket&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bitbucketChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({});</span></span></code></pre></div><p>Without <code>onPullRequest</code>, new pull requests start turns. Data Center updates also start turns when the source branch has new commits. Comments and pushes are opt-in through <code>onPullRequestComment</code> and <code>onPush</code>. Use <code>onEvent</code> for other event types. Set <code>webhookEvents</code> when managed event delivery must subscribe to an event that only <code>onEvent</code> handles.</p><p>Filter comment hooks by author before starting a turn. This prevents comments posted by the agent from triggering another turn.</p><p><code>ctx.bitbucket.api</code> can read pull requests, post comments, and create build statuses. See the <a href="./../reference/channels.html">Channels reference</a> for hook return values and session behavior.</p><h2 id="connect-bitbucket" tabindex="-1">Connect Bitbucket <a class="header-anchor" href="#connect-bitbucket" aria-label="Permalink to &quot;Connect Bitbucket&quot;">​</a></h2><p>Set a repository hook secret and API token:</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:#24292E;--shiki-dark:#E1E4E8;">BITBUCKET_WEBHOOK_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">BITBUCKET_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">...</span></span></code></pre></div><p>Add a repository webhook for <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/bitbucket</code>. Use the same secret on both sides. The channel verifies the <code>X-Hub-Signature</code> HMAC before it parses the payload.</p><p>Bitbucket Cloud uses its 2.0 API by default. Data Center also needs its REST API base:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bitbucketChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  apiBaseUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://bitbucket.example.com/rest/api/1.0&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;PLATFORM/api&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>You can set <code>BITBUCKET_API_BASE_URL</code> instead.</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>Start the agent, then replay a pull request you can read:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bitbucket</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42</span></span></code></pre></div><p>Replay supports Bitbucket Cloud and Data Center URLs. <code>BITBUCKET_TOKEN</code> needs pull request read access. The command reads the pull request, creates a payload in the matching dialect, and sends it through the same channel route. Use <code>--events &#39;*&#39;</code> to replay the supported events declared by the channel. Use <code>--dry-run --out fixtures/bitbucket</code> to save fixtures.</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bitbucket</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bitbucket</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>forward</code> prints the repository-hook and HTTPS tunnel setup for live deliveries.</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></li><li><a href="./webhooks.html">Webhooks and custom channels</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,23)])])}const u=s(n,[["render",l]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_bitbucket.md.CTpCl__f.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Bitbucket","description":"Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center.","frontmatter":{"title":"Bitbucket","description":"Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center."},"headers":[],"relativePath":"guides/bitbucket.md","filePath":"guides/bitbucket.md"}'),n={name:"guides/bitbucket.md"};function l(h,e,p,o,r,d){return a(),t("div",null,[...e[0]||(e[0]=[i("",23)])])}const u=s(n,[["render",l]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_cloud-agents.md.lSE_l7lH.js

@@ -1,9 +0,0 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.dypDpWZ3.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.","frontmatter":{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),o={name:"guides/cloud-agents.md"};function i(r,e,h,l,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="cloud-agents" tabindex="-1">Cloud agents <a class="header-anchor" href="#cloud-agents" aria-label="Permalink to &quot;Cloud agents&quot;">​</a></h1><p>The <code>cursor-cloud-agents</code> extension lets an agent delegate coding work to Cursor cloud agents and stay in the conversation while they do it. The cloud agents work on real repository checkouts and push branches and pull requests; your agent hands off the task, reports back, and answers questions in the meantime. A Slack triage agent turns a bug report into a PR, a planner fans a refactor out across repositories, a reviewer asks a cloud agent to address its own comments.</p><p>This is different from <code>[runtime: &quot;cloud&quot;](../reference/agent-config.md#choose-a-runtime)</code>. The runtime moves <em>this</em> agent&#39;s turns onto a cloud VM. The extension keeps the agent where it is and lets it start <em>other</em> cloud agents.</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>The extension ships with <code>@cursor/july</code>. Mount it with one file.</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;">// agent/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/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/api&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </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;">    autoCreatePR: </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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Launches run under the host&#39;s signed-in account (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>) and spend its cloud-agent budget. Name the repositories the agent may target, and keep approval on when you can&#39;t.</p><p>Mount it on an agent that runs on the local runtime; that is where launches park for approval. On the cloud runtime approvals don&#39;t resolve.</p><h2 id="what-the-agent-can-do" tabindex="-1">What the agent can do <a class="header-anchor" href="#what-the-agent-can-do" aria-label="Permalink to &quot;What the agent can do&quot;">​</a></h2><p>With the extension mounted, the agent can hand off coding work and stay in the conversation while it happens:</p><ul><li><strong>Hand off a task.</strong> Launch a cloud agent on one of your repositories, or on a pull request, with a self-contained brief. It gets back an agent id and a URL to share.</li><li><strong>Check on it.</strong> See whether the agent is still running, what it produced, and which branches or pull requests it pushed.</li><li><strong>Read what was done.</strong> Pull the agent&#39;s full conversation into the workspace, quote its final report, or trace the exact edits before summarizing for a person.</li><li><strong>Steer or stop.</strong> Send a follow-up to an agent it launched; it queues behind the current run, or interrupts it on request. Cancel a run that went sideways.</li><li><strong>Keep track.</strong> List the agents launched in this conversation, or everything it has launched before.</li></ul><p>A skill teaches the model when to delegate, how to write a brief a cloud agent can act on alone, and how to follow up. Everything the extension launches stays bound to whoever launched it: an agent started by another user, or outside the extension, is out of reach. That separation is only as fine as your host&#39;s auth; a shared bearer token or <code>--allow-anonymous</code> makes every caller one principal, so use <a href="./../reference/channels.html#auth-policies">authored auth</a> when callers need their own.</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><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>cloud</code></td><td>Launch defaults, in the same shape as the agent&#39;s own <a href="./../reference/agent-config.html#cloud-options">cloud options</a>.</td></tr><tr><td><code>cloud.repos</code></td><td>The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can&#39;t name one, so secrets in <code>cloud.envVars</code> never reach a repository you didn&#39;t list.</td></tr><tr><td><code>model</code></td><td>The model launched agents run. Omit it to use the account default.</td></tr><tr><td><code>needsApproval</code></td><td>Park launches and follow-ups for a <a href="./../reference/tools.html#gate-a-tool-on-human-approval">human decision</a>. Defaults to <code>true</code> when no <code>cloud.repos</code> are configured, <code>false</code> otherwise.</td></tr><tr><td><code>apiKey</code></td><td>A Cursor API key to launch with instead of the host&#39;s own.</td></tr></tbody></table><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 take a capability away, such as sending follow-ups, mount as a directory and disable that tool; see <a href="./../reference/extensions.html#adjust-a-mounted-extension">overlays</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><p>Continue with these pages:</p><ul><li><a href="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: where parked launches get approved</li></ul>`,19)])])}const g=t(o,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_cloud-agents.md.lSE_l7lH.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.dypDpWZ3.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.","frontmatter":{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),o={name:"guides/cloud-agents.md"};function i(r,e,h,l,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n("",19)])])}const g=t(o,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_convert-automation.md.Ck6Cr68A.js

@@ -1,12 +0,0 @@
-import{_ as t,c as a,o,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.","frontmatter":{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it."},"headers":[],"relativePath":"guides/convert-automation.md","filePath":"guides/convert-automation.md"}'),s={name:"guides/convert-automation.md"};function i(r,e,d,c,l,h){return o(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="convert-a-cursor-automation" tabindex="-1">Convert a Cursor Automation <a class="header-anchor" href="#convert-a-cursor-automation" aria-label="Permalink to &quot;Convert a Cursor Automation&quot;">​</a></h1><p><code>convert-automation</code> exports a dashboard Automation into a local Agent SDK project. Use it when you need to edit, test, or deploy the Automation as code. Keep using the dashboard if you only need to change its prompt or trigger.</p><p>The converter refuses Cursor-managed Automations because their behavior lives in managed configuration. The <a href="./../reference/cli.html#convert-automation">CLI reference</a> lists flags and exit codes.</p><h2 id="run-the-conversion" tabindex="-1">Run the conversion <a class="header-anchor" href="#run-the-conversion" aria-label="Permalink to &quot;Run the conversion&quot;">​</a></h2><p>Sign in before converting. Unlike <code>init</code>, this command does not start a login flow.</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span></span></code></pre></div><p>Pass the Automation&#39;s dashboard URL or UUID. The URL must end with <code>/automations/&lt;uuid&gt;</code> or <code>/custom-agents/&lt;uuid&gt;</code>. Do not add path segments after the UUID.</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> convert-automation</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555</span></span></code></pre></div><p>The summary prints the output directory. Change into it before running any setup command. For an Automation named &quot;Nightly triage&quot;:</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:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nightly-triage</span></span></code></pre></div><p>The command fetches the Automation before writing files. A 404 means it was not found, you do not have access, or convert is not enabled for your team. A 422 means it is Cursor-managed. The command writes nothing after either error.</p><p>The command runs <code>npm install</code> after writing the project. If the install fails, the files remain. Run <code>npm install</code> in the output directory before <code>dev</code>.</p><h2 id="what-the-project-contains" tabindex="-1">What the project contains <a class="header-anchor" href="#what-the-project-contains" aria-label="Permalink to &quot;What the project contains&quot;">​</a></h2><p>A cron Automation with a Linear MCP server might produce:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>nightly-triage/</span></span>
-<span class="line"><span>  package.json</span></span>
-<span class="line"><span>  tsconfig.json</span></span>
-<span class="line"><span>  agent/</span></span>
-<span class="line"><span>    agent.ts</span></span>
-<span class="line"><span>    instructions.md</span></span>
-<span class="line"><span>    schedules/nightly-triage.ts</span></span>
-<span class="line"><span>    mcp-connections/linear.ts</span></span>
-<span class="line"><span>  evals/</span></span></code></pre></div><p>The command adds missing <code>init</code> scaffold files but omits the demo <code>echo</code> tool. It writes the memory hook only when memory was enabled. File generation leaves existing paths unchanged and marks them as <code>exist</code>. This does not cover <code>npm install</code>, which may update lockfiles or run lifecycle scripts from an existing <code>package.json</code>.</p><table tabindex="0"><thead><tr><th>Automation input</th><th>Project output</th></tr></thead><tbody><tr><td>First prompt</td><td>Copies text to <code>agent/instructions.md</code>. Action markup such as <code>@[label](action:...)</code> becomes the label text.</td></tr><tr><td>Prompt model</td><td>Pins the model on <code>defineAgent</code> in <code>agent/agent.ts</code>. <code>git_config</code> and <code>agent_options</code> remain comments.</td></tr><tr><td>Cron trigger</td><td>Creates <code>agent/schedules/&lt;slug&gt;.ts</code> with <code>defineSchedule</code> in UTC.</td></tr><tr><td>GitHub trigger</td><td>Creates <code>agent/channels/github.ts</code>. It converts pull-request action, push branch, issue action, and user allowlist filters.</td></tr><tr><td>Slack trigger</td><td>Creates <code>agent/channels/slack.ts</code> as Socket Mode with <code>envPrefix</code> from the automation name (same names <code>slack create</code> writes). Watches add <code>engagement.channelPosts</code>. Run <code>agent-sdk slack create</code> for the bot.</td></tr><tr><td>Linear, PagerDuty, Sentry, Teams, or generic webhook</td><td>Creates a boilerplate <code>agent/channels/&lt;slug&gt;.ts</code>.</td></tr><tr><td>HTTP or SSE MCP server</td><td>Creates a name-based Cursor-account connection under <code>agent/mcp-connections/</code>. The project contains no server URL or credentials.</td></tr><tr><td>Stdio MCP server</td><td>Writes <code>agent/mcp-connections/&lt;slug&gt;.todo.md</code>.</td></tr><tr><td>Slack post or read action</td><td>Adds <code>agent/mcp-connections/slack.ts</code>. The summary includes a <code>Verify:</code> step for the original action.</td></tr><tr><td>Other built-in dashboard action</td><td>Adds a <code>Verify:</code> setup step instead of an Agent SDK tool.</td></tr></tbody></table><h2 id="finish-unsupported-behavior" tabindex="-1">Finish unsupported behavior <a class="header-anchor" href="#finish-unsupported-behavior" aria-label="Permalink to &quot;Finish unsupported behavior&quot;">​</a></h2><p>Warnings and setup steps identify behavior the converter could not reproduce.</p><h3 id="prompt-snippets" tabindex="-1">Prompt snippets <a class="header-anchor" href="#prompt-snippets" aria-label="Permalink to &quot;Prompt snippets&quot;">​</a></h3><p>The export omits the source text for unresolved <code>%%INLINECODE&lt;n&gt;%%</code> placeholders. Restore those snippets in <code>instructions.md</code>.</p><h3 id="github-filters" tabindex="-1">GitHub filters <a class="header-anchor" href="#github-filters" aria-label="Permalink to &quot;GitHub filters&quot;">​</a></h3><p>Comment text, CI conclusion, label name, and review-state filters stay fail-closed. The generated hooks return <code>null</code> until you add them. The generated Cursor-account event relay includes only pull-request and comment data. Push, issue, and CI triggers need a GitHub App webhook or <code>github forward</code>. Add repositories for org-wide watches. The converter drops non-GitHub remotes.</p><h3 id="slack-triggers" tabindex="-1">Slack triggers <a class="header-anchor" href="#slack-triggers" aria-label="Permalink to &quot;Slack triggers&quot;">​</a></h3><p>Reaction and channel-created triggers have no Agent SDK equivalent. The converter keeps their configuration in comments but adds no handler. Re-add any <code>messageContains</code> filter or completion reaction you need. These triggers and channel watches require a dedicated Socket Mode app. Run <code>agent-sdk slack create --channel-posts</code>, then finish the dashboard wizard.</p><h3 id="provider-webhooks" tabindex="-1">Provider webhooks <a class="header-anchor" href="#provider-webhooks" aria-label="Permalink to &quot;Provider webhooks&quot;">​</a></h3><p>Linear, PagerDuty, Sentry, Teams, and generic webhook channels mount <code>POST /</code> under their channel route. Every accepted body starts a run. In default multi-agent mode, the route is <code>/&lt;agent-slug&gt;/v1/channels/&lt;channel-id&gt;</code>. Single mode uses <code>/v1/channels/&lt;channel-id&gt;</code>.</p><p>Restore the filters and auth before registering the provider. A hosted alias requires <code>X-Agent-Alias-Token</code>. If the provider cannot send that header, use <code>publicEndpoint()</code> with signature verification in the handler, put an alias-token relay in front, or self-host.</p><h3 id="stdio-mcp-servers" tabindex="-1">Stdio MCP servers <a class="header-anchor" href="#stdio-mcp-servers" aria-label="Permalink to &quot;Stdio MCP servers&quot;">​</a></h3><p>The converter does not export the command, arguments, or environment. Run the server, then replace the <code>.todo.md</code> stub with a reachable connection.</p><h3 id="disabled-default-tools" tabindex="-1">Disabled default tools <a class="header-anchor" href="#disabled-default-tools" aria-label="Permalink to &quot;Disabled default tools&quot;">​</a></h3><p>The converter cannot preserve this restriction. Do not rely on <code>instructions.md</code> as enforcement. Use the <a href="./../reference/agent-config.html#allowlist-built-in-harness-tools"><code>tools</code> allowlist</a>, remove unwanted authored or MCP tools, and limit channel permissions.</p><h2 id="review-and-run-the-project" tabindex="-1">Review and run the project <a class="header-anchor" href="#review-and-run-the-project" aria-label="Permalink to &quot;Review and run the project&quot;">​</a></h2><ol><li><p>Read every warning and setup step.</p></li><li><p>Open the generated channel files. Fail-closed GitHub hooks dispatch nothing until you add their filters. Add auth to boilerplate webhook routes.</p></li><li><p>Confirm the account MCP servers are connected under MCP in the Cursor dashboard. The serving host must be signed in with <code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>.</p></li><li><p>Run the printed next steps:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div></li><li><p>Before you <a href="./../deployment.html">deploy</a>, disable the source Automation so both versions do not respond to the same events. The final setup step includes its dashboard URL.</p></li><li><p>A hosted deployment uses a separate service account. After the first deploy, run <code>agent-sdk mcp oauth &lt;connection&gt;</code> for each generated Cursor-account connection.</p></li></ol><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/cli.html#convert-automation">CLI</a>: flags, <code>--json</code>, exit codes</li><li><a href="./../reference/connections.html">MCP connections</a>: Cursor-account connectors</li><li><a href="./github.html">GitHub</a>: hook filters and replay; use <a href="./../reference/cli.html#github"><code>github forward</code></a> for live delivery</li><li><a href="./slack.html">Slack</a>: Cursor connection vs Socket Mode</li><li><a href="./webhooks.html">Webhooks</a>: auth on a custom channel route</li><li><a href="./../deployment.html">Deployment</a>: hosted engines after you have reviewed the project</li></ul>`,36)])])}const g=t(s,[["render",i]]);export{u as __pageData,g as default};

package/dist/docs/assets/guides_convert-automation.md.Ck6Cr68A.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.","frontmatter":{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it."},"headers":[],"relativePath":"guides/convert-automation.md","filePath":"guides/convert-automation.md"}'),s={name:"guides/convert-automation.md"};function i(r,e,d,c,l,h){return o(),a("div",null,[...e[0]||(e[0]=[n("",36)])])}const g=t(s,[["render",i]]);export{u as __pageData,g as default};

package/dist/docs/assets/guides_github.md.D6ER29dG.js

@@ -1,64 +0,0 @@
-import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.","frontmatter":{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),n={name:"guides/github.md"};function h(l,s,o,p,r,d){return a(),i("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>Wake your agent from repository events without exposing a public webhook URL. Prefer <code>serve --cursor-events</code>: the host long-polls Cursor&#39;s SCM event stream for repos you&#39;ve connected to Cursor. You still declare a <code>githubChannel</code> so hooks decide what each event does.</p><p>The companion skill for coding agents is <a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>.</p><h2 id="pull-events-from-cursor" tabindex="-1">Pull events from Cursor <a class="header-anchor" href="#pull-events-from-cursor" aria-label="Permalink to &quot;Pull events from Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for the repositories you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). That gives your account access and lets Cursor receive the repo&#39;s webhooks. Sign the host in (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>), then opt the channel into the Cursor account connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // permissions?: &quot;read&quot; | &quot;pr-write&quot; | &quot;contents-write&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // default &quot;pr-write&quot; (comments / PR writes, no contents:write)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // hooks...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> starts the event relay and mints one short-lived GitHub credential scoped to those repositories. <code>ctx.github</code>, <code>ctx.host.github</code>, and child <code>gh</code> commands share it. The Agent SDK refreshes the credential before expiry. No GitHub App key, PAT, or separate <code>gh auth login</code> is needed on the host.</p><p>Choose <code>permissions</code> by what the agent needs:</p><table tabindex="0"><thead><tr><th><code>permissions</code></th><th>Use when</th></tr></thead><tbody><tr><td><code>&quot;read&quot;</code></td><td>Inspect PRs / issues / statuses only</td></tr><tr><td><code>&quot;pr-write&quot;</code> (default)</td><td>Comment, review, update PR/issue metadata</td></tr><tr><td><code>&quot;contents-write&quot;</code></td><td>Push code, or post merge-box checks</td></tr></tbody></table><p><code>contents-write</code> is an explicit opt-up. <code>progress.commitStatus</code> posts a GitHub check run (<code>checks:write</code>). Hosted <code>cursorAccount</code> mints that permission on <code>&quot;contents-write&quot;</code> tokens. Enabling <code>commitStatus</code> opts a <code>&quot;pr-write&quot;</code> channel up to that tier because it needs check-write permission. <code>&quot;pr-write&quot;</code> without <code>commitStatus</code> is enough for comments and banners. Prefer <code>&quot;pr-write&quot;</code> unless the agent must push or post a merge-box check.</p><p>Set <code>checks: true</code> when channel code posts its own Checks API runs through <code>ctx.github.createCheck</code>. The flag grants access. It does not post a check.</p><p>Selected repositories must share one GitHub owner (one App installation). Configuration that spans owners fails at startup / mint time.</p><p>To keep repository scope in deployment config instead, use <code>cursorAccount: true</code> and pass it at serve time:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</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;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Repeat <code>--repo</code> for each repository. The stream and credential are resolved as the signed-in Cursor principal. <code>serve</code> refuses to start signed out.</p><p>The stream carries event metadata, not full webhook bodies, so your agent should re-read the PR or checks from GitHub instead of trusting a snapshot in the wake.</p><p>This is the preferred production path: no public URL, no repo admin webhook, and no inbound network for GitHub deliveries.</p><h2 id="connect-github-enterprise-server" tabindex="-1">Connect GitHub Enterprise Server <a class="header-anchor" href="#connect-github-enterprise-server" aria-label="Permalink to &quot;Connect GitHub Enterprise Server&quot;">​</a></h2><p>GitHub Enterprise Server uses the same <code>githubChannel()</code> hooks and normalized events. Connect it through the direct webhook route. Set the REST API base and credentials for your server:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  api: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    apiBaseUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.example.com/api/v3&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  credentials: {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    token</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">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:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</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>
-<span class="line"><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:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</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></code></pre></div><p>Add a repository webhook for <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/github</code>. Use the same webhook secret on the server and in <code>GITHUB_WEBHOOK_SECRET</code>. The channel verifies <code>X-Hub-Signature-256</code> before it parses the payload.</p><p>Cursor account event pull, <code>github replay</code>, and <code>github forward</code> target GitHub.com. Test Enterprise Server integrations by posting saved webhook fixtures to a local <code>--dev</code> server. Leave <code>GITHUB_WEBHOOK_SECRET</code> unset for this local test so the channel admits unsigned loopback deliveries. Use a real delivery from your server so the fixture matches its version.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code> from <code>@cursor/july/channels/github</code>. It mounts <code>POST /&lt;slug&gt;/v1/channels/github</code> and publishes the events it dispatches on. That event set comes from the hooks you declare, or you pin it with <code>webhookEvents</code>. Cursor event pull and local replay both use it.</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;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or GITHUB_APP_SLUG; used to ignore self-comments</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: { repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] },</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#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>
-<span class="line"><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:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</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:#6F42C1;--shiki-dark:#B392F0;">  onCheckSuite</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;">suite</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    suite.conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;failure&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> triage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</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></code></pre></div><p>The hooks are <code>onPullRequest</code>, <code>onComment</code>, <code>onIssue</code>, <code>onCheckSuite</code>, <code>onCheckRun</code>, <code>onWorkflowRun</code>, <code>onStatus</code>, the catch-all <code>onEvent</code>, and the lifecycle pair <code>onStart</code> / <code>onStop</code>. Each hook returns one of three things:</p><table tabindex="0"><thead><tr><th>Return</th><th>Meaning</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Start or continue a model turn as that actor. A chat session exists and shows up in the playground.</td></tr><tr><td><code>{ task }</code></td><td>Host-side work. The delivery is 202-ACKed immediately and the task runs past GitHub&#39;s ~10-second timeout. No chat session.</td></tr><tr><td><code>null</code></td><td>Skip this delivery.</td></tr></tbody></table><p><code>{ auth }</code> may also carry <code>workspaceFiles</code>, the same session seed Slack and <code>send()</code> use. Pass a function to fetch after a 202 so I/O can miss GitHub&#39;s ~10s window.</p><p>Return <code>{ task }</code> when the wake drives deterministic code. A security reviewer can run its whole review loop this way and report through PR comments. Return <code>{ auth }</code> when the model needs to reason about the event.</p><p>Without <code>cursorAccount</code>, outbound GitHub API calls prefer App installation tokens when <code>GITHUB_APP_ID</code> and <code>GITHUB_APP_PRIVATE_KEY</code> are set (with an installation id from the event or <code>GITHUB_APP_INSTALLATION_ID</code>). On serve warmup, App-backed hosts also export a short-lived installation token as <code>GH_TOKEN</code> so tools that shell out to <code>gh</code> (a host-side <code>prepare_review</code> tool, say) authenticate without a PAT. For local testing, skip the App credentials and use <code>GITHUB_TOKEN</code>, <code>GH_TOKEN</code>, or <code>gh auth login</code>.</p><h2 id="test-wakes-locally" tabindex="-1">Test wakes locally <a class="header-anchor" href="#test-wakes-locally" aria-label="Permalink to &quot;Test wakes locally&quot;">​</a></h2><p>Use fixtures and <code>github replay</code> so you can develop without waiting on live pushes. Both target the same channel route the Cursor relay uses.</p><h3 id="post-a-saved-fixture" tabindex="-1">Post a saved fixture <a class="header-anchor" href="#post-a-saved-fixture" aria-label="Permalink to &quot;Post a saved fixture&quot;">​</a></h3><p>For offline tests, POST a saved payload with an <code>x-github-event</code> header. A <code>--dev</code> server does not require a signature:</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:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/channels/github</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;x-github-event: pull_request&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @fixtures/github/pull_request.synchronize.json</span></span></code></pre></div><p>Don&#39;t hand-write payloads. Snapshot real ones with replay&#39;s <code>--dry-run --out</code>, below.</p><h3 id="test-with-github-replay" tabindex="-1">Test with <code>github replay</code> <a class="header-anchor" href="#test-with-github-replay" aria-label="Permalink to &quot;Test with \`github replay\`&quot;">​</a></h3><p>Use <code>replay</code> for deterministic tests and <a href="./../hillclimbing.html">hillclimbing</a>. It reads a real PR with <code>gh api</code>, synthesizes GitHub-shaped payloads, signs them when a secret is configured, and POSTs them at the channel. Pull access is enough: no admin, and an env <code>GITHUB_TOKEN</code> is fine here. The same input produces the same delivery.</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:#6A737D;--shiki-dark:#6A737D;"># Replay a pull_request delivery for a PR</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/owner/repo/pull/123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Replay everything the channel listens for, with CI failing</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</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;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --conclusion</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> failure</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inspect payloads without POSTing, and snapshot them as fixtures</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</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;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><p><code>--events</code> defaults to <code>pull_request</code>. <code>&#39;*&#39;</code> replays the events the channel declares and the CLI can synthesize. <code>--action</code>, <code>--conclusion</code>, <code>--comment</code>, and <code>--context</code> shape each event. <code>--secret</code> or <code>GITHUB_WEBHOOK_SECRET</code> signs them.</p><h2 id="receive-webhooks-directly" tabindex="-1">Receive webhooks directly <a class="header-anchor" href="#receive-webhooks-directly" aria-label="Permalink to &quot;Receive webhooks directly&quot;">​</a></h2><p>Most hosts should pull events from Cursor instead. Use the HTTP channel route when you already terminate GitHub webhooks yourself, or when you are POSTing fixtures and replay locally.</p><p>With a webhook secret configured, the route admits everyone (<code>allowAll()</code>) and the channel verifies <code>X-Hub-Signature-256</code> before parsing. The HMAC becomes the request principal. Without a secret, the route is loopback-only. The exception is <code>serve --dev</code>, which admits unsigned loopback deliveries so fixtures and replay work with zero config. Non-dev targets that accept real GitHub POSTs always need the secret, and the same value must live on the server and on whatever signs deliveries.</p><h2 id="handle-high-event-volume" tabindex="-1">Handle high event volume <a class="header-anchor" href="#handle-high-event-volume" aria-label="Permalink to &quot;Handle high event volume&quot;">​</a></h2><p>These patterns come from running a PR agent against real traffic:</p><ul><li>Debounce per PR (~3 seconds, latest event wins), and re-buffer while CI settles. Skip a flush when a turn for that PR is already running.</li><li>Persist the buffer in <code>host.kv</code> before you acknowledge a wake, and restore it on channel start. A restart must not drop buffered wakes.</li><li>Key sessions with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake resumes the PR&#39;s conversation.</li><li>Keep payload details out of wake prompts. Send a generic &quot;re-check the PR&quot; and let the agent re-read source of truth instead of trusting a stale snapshot.</li><li>Cancel PR-scoped reminders on <code>pull_request.closed</code>.</li><li>Decide explicitly which repos the agent may act on. Without an allowlist the channel wakes for whatever deliveries reach it, and every wake spends real model budget.</li></ul><h2 id="show-pr-progress" tabindex="-1">Show PR progress <a class="header-anchor" href="#show-pr-progress" aria-label="Permalink to &quot;Show PR progress&quot;">​</a></h2><p>Autofix-style agents need a deterministic merge-box check and a sticky PR comment that converges when the turn ends. Configure that on the channel with <code>progress.commitStatus</code> and <code>progress.banner</code>. A hook can read and write <code>ctx.host.kv</code> and <code>ctx.host.files</code> after a turn. Use that for derived state. Keep GitHub check-run and banner writes on the channel.</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;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;autofix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  deliverReplies: </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;">  progress: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    reactions: </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;">    commitStatus: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      context: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;autofix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      pending: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix running&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      success: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix finished&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      failure: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    banner: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      pending: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix running…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      success: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix finished&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      failure: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Autofix failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // commitStatus posts a Checks API run. Hosted cursorAccount opts the</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // minted token up to contents-write (checks:write). Banner also works</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // on pr-write without commitStatus.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</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>
-<span class="line"><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:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</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></code></pre></div><p>Default stream events drive the lifecycle:</p><table tabindex="0"><thead><tr><th>Event</th><th>Check run</th><th>Banner</th></tr></thead><tbody><tr><td><code>turn.started</code></td><td><code>in_progress</code></td><td>create (or keep) the sticky comment</td></tr><tr><td><code>turn.completed</code></td><td><code>completed</code> / <code>success</code></td><td>PATCH the same comment</td></tr><tr><td><code>turn.failed</code> / <code>session.failed</code></td><td><code>completed</code> / <code>failure</code></td><td>PATCH the same comment</td></tr></tbody></table><p>Omit <code>commitStatus</code> / <code>banner</code>, or set them to <code>false</code>, to keep today&#39;s behavior. Reactions still default on; set <code>reactions: false</code> when the eyes emoji is noise. Descriptions are optional; defaults derive from <code>botName</code> or the check <code>context</code>.</p><p>To match dashboard automations, set <code>detailsUrl(sessionId)</code>, <code>summaryLinkText: &quot;View agent&quot;</code>, and <code>outputTitle: &quot;context&quot;</code> so the check title is the check name, the summary includes <code>[View agent](…)</code>, and Details opens the session.</p><p>A comment-only first wake has no head SHA, so the check waits for a PR or CI event. The banner still posts. A later turn on the same SHA creates a new check run; GitHub cannot reopen a completed run.</p><p>Override <code>events</code> when the mapping is custom. A handler can post commit status from <code>turn.started</code> / <code>action.result</code> / <code>turn.failed</code> and stay never-red; that pattern still wins when you replace a default handler key. Handlers you author replace the matching defaults (same as <code>progress.reactions</code> composition today).</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="./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="./../reference/hooks.html">Hooks</a>: observe-only; use channel <code>progress</code> for GitHub surfaces</li></ul>`,57)])])}const u=e(n,[["render",h]]);export{c as __pageData,u as default};

package/dist/docs/assets/guides_github.md.D6ER29dG.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.","frontmatter":{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),n={name:"guides/github.md"};function h(l,s,o,p,r,d){return a(),i("div",null,[...s[0]||(s[0]=[t("",57)])])}const u=e(n,[["render",h]]);export{c as __pageData,u as default};

package/dist/docs/assets/guides_gitlab.md.P-TjBnS5.js

@@ -1,14 +0,0 @@
-import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"GitLab","description":"Wake your agent from GitLab merge requests, notes, pipelines, and pushes on GitLab.com or self-managed GitLab.","frontmatter":{"title":"GitLab","description":"Wake your agent from GitLab merge requests, notes, pipelines, and pushes on GitLab.com or self-managed GitLab."},"headers":[],"relativePath":"guides/gitlab.md","filePath":"guides/gitlab.md"}'),n={name:"guides/gitlab.md"};function l(h,s,p,o,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t(`<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>Use <code>gitlabChannel()</code> for GitLab.com and self-managed GitLab. The channel verifies project hooks, normalizes their payloads, and gives each hook a project-bound <code>ctx.gitlab</code> API client.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/gitlab.ts</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;"> { gitlabChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/gitlab&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;"> gitlabChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({});</span></span></code></pre></div><p>Without <code>onMergeRequest</code>, new and reopened merge requests start turns. Updates start turns only when they include new commits. Notes, pushes, and pipelines are opt-in through <code>onNote</code>, <code>onPush</code>, and <code>onPipeline</code>. Use <code>onEvent</code> for other GitLab event types. Set <code>webhookEvents</code> when managed event delivery must subscribe to an event that only <code>onEvent</code> handles.</p><p>Filter note hooks by author before starting a turn. This prevents comments posted by the agent from triggering another turn.</p><p><code>ctx.gitlab</code> can call the project REST API and create commit statuses. See the <a href="./../reference/channels.html">Channels reference</a> for hook return values and session behavior.</p><h2 id="connect-gitlab" tabindex="-1">Connect GitLab <a class="header-anchor" href="#connect-gitlab" aria-label="Permalink to &quot;Connect GitLab&quot;">​</a></h2><p>On Cursor-managed hosting, use the signed-in Cursor account:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gitlabChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    projects: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme/platform&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>For direct webhooks, set a project hook secret and API token:</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:#24292E;--shiki-dark:#E1E4E8;">GITLAB_WEBHOOK_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">GITLAB_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">...</span></span></code></pre></div><p>Add a project webhook for <code>https://&lt;your-host&gt;/&lt;slug&gt;/v1/channels/gitlab</code>. Use the same value for the GitLab secret token and <code>GITLAB_WEBHOOK_SECRET</code>. The channel checks <code>X-Gitlab-Token</code> before it parses the payload.</p><p>Self-managed GitLab also needs its REST API base:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> gitlabChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  apiBaseUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://gitlab.example.com/api/v4&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  projects: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme/platform&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>You can set <code>GITLAB_API_BASE_URL</code> instead.</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>Start the agent, then replay a merge request you can read:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gitlab</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  https://gitlab.example.com/acme/platform/-/merge_requests/42</span></span></code></pre></div><p><code>GITLAB_TOKEN</code> needs API read access. Replay reads the merge request, creates GitLab-shaped payloads, and sends them through the same channel route. Use <code>--events &#39;*&#39;</code> to replay the supported events declared by the channel. Use <code>--dry-run --out fixtures/gitlab</code> to save fixtures.</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gitlab</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> gitlab</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>GitLab has no local webhook relay. <code>forward</code> prints the project-hook and HTTPS tunnel setup for live deliveries.</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></li><li><a href="./webhooks.html">Webhooks and custom channels</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,25)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/guides_gitlab.md.P-TjBnS5.lean.js

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

package/dist/docs/assets/guides_grokbot-agents.md.WBZIOvkz.js

@@ -1,9 +0,0 @@
-import{_ as e,c as a,o as s,a3 as n}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,t,h,l,d,p){return s(),a("div",null,[...t[0]||(t[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 an agent send a message to one of your Grok Bot agents and read the reply. The Grok Bot keeps its own conversation, memory, and tools. Your agent stays where it is and consults that bot the way you would in the Grok Bot app.</p><p>This is different from moving this agent&#39;s turns onto a hosted Grok Bot. The extension keeps the agent where it is and lets it talk to <em>other</em> Grok Bot agents.</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>The extension ships with <code>@cursor/july</code>. Mount it with one file.</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;">// agent/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/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agents: [</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    { name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Plan Keeper&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Keeps or moves outdoor plans.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    { name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Chief of Staff&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Routes work and tracks priorities.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>agents</code> is the allowlist. List every Grok Bot the model may talk to; a name outside the list is refused. Calls run under the host&#39;s signed-in account (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>). Keep approval on when you can&#39;t.</p><p>To scaffold a project that already mounts this:</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:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./grokbot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> grokbot-agents</span></span></code></pre></div><h2 id="what-the-agent-can-do" tabindex="-1">What the agent can do <a class="header-anchor" href="#what-the-agent-can-do" aria-label="Permalink to &quot;What the agent can do&quot;">​</a></h2><p>With the extension mounted, the agent can consult a Grok Bot and stay in its own conversation:</p><ul><li><strong>Ask.</strong> Send a self-contained message to a Grok Bot by the name shown in the Grok Bot app. The message lands in your conversation with that bot. The tool waits for the bot&#39;s reply.</li><li><strong>Keep waiting.</strong> A long turn returns <code>status: &quot;running&quot;</code>. Call check with the same name to read what arrived since the last look.</li><li><strong>Stop a turn.</strong> Interrupt the bot&#39;s current work. The conversation stays; a later ask continues it.</li><li><strong>See who you can talk to.</strong> List the configured bots and the ones this caller has already asked. Add a name to <code>agents</code> when you want the model to reach another bot.</li></ul><p>A skill teaches the model when to bring a Grok Bot in, how to write a message the bot can act on alone, and how to wait or interrupt. The reply is what the Grok Bot sent to the person. If a turn finishes with no reply, the bot sent nothing; ask again with a clearer request, or open the bot in the Grok Bot app.</p><p>The tools reach Grok Bot agents on the signed-in account. A bot another user owns is out of reach. That separation is only as fine as your host&#39;s auth; a shared bearer token or <code>--allow-anonymous</code> makes every caller one principal, so use <a href="./../reference/channels.html#auth-policies">authored auth</a> when callers need their own.</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><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>agents</code></td><td>The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit <code>agents</code> to allow any name; an unknown name creates an empty Grok Bot on the account.</td></tr><tr><td><code>needsApproval</code></td><td>Park asks for a <a href="./../reference/tools.html#gate-a-tool-on-human-approval">human decision</a>. Defaults to <code>true</code> when no <code>agents</code> are configured, <code>false</code> otherwise.</td></tr><tr><td><code>apiKey</code></td><td>A Cursor API key to call with instead of the host&#39;s own.</td></tr></tbody></table><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 take a capability away, such as interrupting a turn, mount as a directory and disable that tool; see <a href="./../reference/extensions.html#adjust-a-mounted-extension">overlays</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><p>Continue with these pages:</p><ul><li><a href="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: where parked asks get approved</li></ul>`,21)])])}const u=e(o,[["render",i]]);export{c as __pageData,u as default};

package/dist/docs/assets/guides_grokbot-agents.md.WBZIOvkz.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as s,a3 as n}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,t,h,l,d,p){return s(),a("div",null,[...t[0]||(t[0]=[n("",21)])])}const u=e(o,[["render",i]]);export{c as __pageData,u as default};

package/dist/docs/assets/guides_improve.md.BKaDuKKK.js

@@ -1,14 +0,0 @@
-import{_ as t,c as s,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Self-improvement","description":"Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens.","frontmatter":{"title":"Self-improvement","description":"Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(h,e,r,l,p,d){return a(),s("div",null,[...e[0]||(e[0]=[i(`<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 lets an agent change how it behaves by changing its own source. Someone asks it to answer more briefly, to stop reaching for a tool, or to learn a procedure. The agent writes a brief, a one-off Cursor cloud agent makes the change on a branch and opens a pull request, and the agent reports that pull request. Nothing changes until a person reviews it and deploys.</p><p>The tree the agent runs from is never edited; nothing changed there survives a deploy. The pull request is the only path.</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>The extension ships with <code>@cursor/july</code>. It relies on a <a href="./cloud-agents.html"><code>cursor-cloud-agents</code></a> mount beside it, with the agent&#39;s own repository among its <code>cloud.repos</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;">// agent/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/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </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;">, startingRef: </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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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;">// agent/extensions/improve.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> improve </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions/improve&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;"> improve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<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;">});</span></span></code></pre></div><p><code>repo</code> is the repository that holds the agent&#39;s source and <code>path</code> is the agent&#39;s directory in it, the same values <code>agent-sdk deploy --repo</code> and <code>--path</code> take. Mount it as <code>improve</code>: the skill then reads <code>improve__yourself</code>, which is what a person asks for.</p><p>An agent on the <a href="./../reference/agent-config.html#choose-a-runtime">cloud runtime</a> already runs each turn on a VM with the repository checked out. It mounts <code>improve</code> alone, and the skill has it branch in that checkout instead of launching a second agent.</p><h2 id="what-the-agent-does" tabindex="-1">What the agent does <a class="header-anchor" href="#what-the-agent-does" aria-label="Permalink to &quot;What the agent does&quot;">​</a></h2><p>With the extension mounted, &quot;change how you work&quot; becomes a procedure:</p><ul><li><strong>Locate the change.</strong> The skill maps the ask onto the Agent SDK tree: instructions for the always-on prompt, a skill for a procedure, a tool for behavior that must be right every time, <code>agent.ts</code> for the model.</li><li><strong>Brief a cloud agent.</strong> The agent writes a self-contained brief: who is asking and why, the repository, ref, and path, the files it expects to change, your notes about the tree, and the rules. Follow the repository&#39;s conventions, keep the diff to the change, run the repository&#39;s checks, open a pull request against the deployed ref, never merge.</li><li><strong>Follow up and report.</strong> It gives the person the cloud agent&#39;s URL, checks on the run, reads the pull request before repeating its claims, and reports the pull request, not the delegation. It says the change takes effect at the next deploy, never that it has changed already.</li></ul><p>Ask it directly. &quot;Improve yourself: stop opening with a summary&quot; is enough.</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><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>repo</code></td><td>The repository holding the agent&#39;s source. One of the cloud mount&#39;s <code>cloud.repos</code>.</td></tr><tr><td><code>path</code></td><td>The agent&#39;s directory in the repository, as <code>agent-sdk deploy --path</code> names it.</td></tr><tr><td><code>ref</code></td><td>The ref the deployment tracks. Branches start there and pull requests target it. Defaults to <code>main</code>.</td></tr><tr><td><code>notes</code></td><td>What a coding agent must know about this tree beyond the standard layout: a house skill format, a manifest that forces a reinstall, a pull request convention. Copied into every brief.</td></tr><tr><td><code>deploy</code></td><td>Who deploys a merged change and when it is live. Defaults to &quot;It takes effect at the next deploy.&quot;</td></tr></tbody></table><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><p>Continue with these pages:</p><ul><li><a href="./cloud-agents.html">Cursor cloud agents</a>: the mount that does the coding, and how to gate its launches</li><li><a href="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li><li><a href="./../deployment.html">Deployment</a>: how a merged change reaches the running agent</li></ul>`,18)])])}const g=t(n,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/guides_improve.md.BKaDuKKK.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Self-improvement","description":"Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens.","frontmatter":{"title":"Self-improvement","description":"Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(h,e,r,l,p,d){return a(),s("div",null,[...e[0]||(e[0]=[i("",18)])])}const g=t(n,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/guides_mcp-oauth.md.DMNMpXtO.js

@@ -1,28 +0,0 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function o(h,e,l,d,r,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="host-mcp-oauth" tabindex="-1">Host MCP OAuth <a class="header-anchor" href="#host-mcp-oauth" aria-label="Permalink to &quot;Host MCP OAuth&quot;">​</a></h1><p>Use host MCP OAuth when your agent talks to a remote MCP server that speaks OAuth, and you want credentials on the serve host (or the hosted engine) instead of a Cursor account connector. Local login writes tokens next to your Cursor credentials. <code>--store</code> copies those tokens onto the deployment as secrets so prod can reconnect after a redeploy. Hosted Connect lets the current process retry.</p><p>The companion skill is <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-can-host-mcp-oauth-do" tabindex="-1">What can host MCP OAuth do? <a class="header-anchor" href="#what-can-host-mcp-oauth-do" aria-label="Permalink to &quot;What can host MCP OAuth do?&quot;">​</a></h2><ul><li>Authorize <code>defineConnection({ url, oauth: true })</code> with a browser PKCE flow (<code>agent-sdk mcp oauth &lt;connection&gt;</code>)</li><li>Keep tokens in <code>mcp-auth.json</code> under the CLI config directory, bound to that connection&#39;s resource URL</li><li>Upsert deployment secrets with <code>--store</code> so the next deploy seeds the same tokens from env. Hosted Connect lets the current process retry.</li><li>Use <code>advertiseTools: true</code> when local turns should call the server by name. Host tools can still call it through <code>ctx.host.mcp</code>.</li></ul><p>Prefer a Cursor account MCP connection when the connector already lives in the signed-in account dashboard:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// every connected connector</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or servers: &quot;*&quot; / servers: [&quot;Linear&quot;]</span></span></code></pre></div><p>Use host OAuth when the server is yours (or private to your network) and the host must hold tokens.</p><h2 id="how-do-i-declare-a-host-oauth-connection" tabindex="-1">How do I declare a host-OAuth connection? <a class="header-anchor" href="#how-do-i-declare-a-host-oauth-connection" aria-label="Permalink to &quot;How do I declare a host-OAuth connection?&quot;">​</a></h2><p>Add one file under <code>agent/mcp-connections/</code> (model + host) or <code>agent/host-connections/</code> (host + <code>mcp oauth</code> only). The filename is the connection name you pass to the CLI and to <code>host.mcp</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;">// agent/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/july/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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  oauth: </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;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Inventory MCP.&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>Rules of the road:</p><ul><li><code>oauth: true</code> is required for <code>agent-sdk mcp oauth</code></li><li>A file under <code>mcp-connections/</code> is visible to the model and to <code>ctx.host.mcp</code>. A file under <code>host-connections/</code> stays on the host.</li><li>Declare expected secret names on the agent when you plan to <code>--store</code>:</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:#6A737D;--shiki-dark:#6A737D;">// agent/agent.ts</span></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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // …</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  hosting: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    secretNames: [</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;MCP_OAUTH_INVENTORY_ACCESS_TOKEN&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;MCP_OAUTH_INVENTORY_REFRESH_TOKEN&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;MCP_OAUTH_INVENTORY_CLIENT_ID&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // Hosted engines need an explicit allowlist for non-bootstrap hosts.</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp.example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Secret names follow <code>MCP_OAUTH_&lt;CONNECTION&gt;_*</code> where <code>&lt;CONNECTION&gt;</code> is the connection filename uppercased with non-alphanumerics turned into underscores (<code>inventory</code> → <code>MCP_OAUTH_INVENTORY_…</code>).</p><h2 id="how-do-i-authorize-locally" tabindex="-1">How do I authorize locally? <a class="header-anchor" href="#how-do-i-authorize-locally" aria-label="Permalink to &quot;How do I authorize locally?&quot;">​</a></h2><p>From the agent project (Node 22.13+, not Bun):</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span></span></code></pre></div><p>What happens:</p><ol><li>The Agent SDK loads the connection file and checks <code>oauth: true</code></li><li>It opens the authorization URL in your browser</li><li>The callback lands on <code>http://localhost:8787/callback</code></li><li>Tokens land in <code>mcp-auth.json</code> under the CLI config directory (override with <code>AGENT_SERVE_CONFIG_DIR</code>)</li></ol><p>If you&#39;re already authorized, the command prints that and exits. Re-run it after rotating tokens on the MCP server, or after you change the connection URL (tokens are bound to the resource URL).</p><h2 id="how-do-i-store-credentials-on-a-hosted-deployment" tabindex="-1">How do I store credentials on a hosted deployment? <a class="header-anchor" href="#how-do-i-store-credentials-on-a-hosted-deployment" aria-label="Permalink to &quot;How do I store credentials on a hosted deployment?&quot;">​</a></h2><p>Authorize once. Then get the tokens onto the deployment.</p><p>On a hosted engine, finishing Connect lets the current process retry. Self-hosted serve writes tokens locally only.</p><p><code>--store</code> from a signed-in laptop is the reliable way to put <code>MCP_OAUTH_*</code> on the next deploy. If <code>agent-sdk secrets list</code> is empty, run <code>--store</code> and redeploy.</p><p>From a laptop, push secrets with the CLI:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --store</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># optional:</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#   --slug my-agent</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#   --team &lt;cursor-team-id&gt;</span></span></code></pre></div><p><code>--store</code> upserts:</p><table tabindex="0"><thead><tr><th>Secret</th><th>Source</th></tr></thead><tbody><tr><td><code>MCP_OAUTH_&lt;NAME&gt;_ACCESS_TOKEN</code></td><td>access token (required)</td></tr><tr><td><code>MCP_OAUTH_&lt;NAME&gt;_REFRESH_TOKEN</code></td><td>refresh token when the server returns one</td></tr><tr><td><code>MCP_OAUTH_&lt;NAME&gt;_CLIENT_ID</code></td><td>dynamic client id when registration returned one</td></tr></tbody></table><p>You must be signed in (<code>agent-sdk login</code>) with permission to set secrets on that slug. Secrets apply on the <strong>next</strong> deploy. Run <code>agent-sdk deploy</code> after <code>--store</code>. A fresh pod sees <code>MCP_OAUTH_*</code> only after that deploy.</p><p>On the engine, when <code>mcp-auth.json</code> is empty, serve seeds the OAuth provider from those env vars so host MCP calls work without a browser on the pod.</p><p>These secrets are deployment-wide. Anyone who can list or set secrets on that slug, and the hosted engine&#39;s runtime env, can use them. That is the same blast radius as <code>--store</code>. They are not scoped to the caller who clicked Connect. <code>cursorAccount: true</code> tokens stay on the Cursor backend for the deployment service account and do not use <code>MCP_OAUTH_*</code>.</p><h2 id="how-do-host-tools-call-the-server" tabindex="-1">How do host tools call the server? <a class="header-anchor" href="#how-do-host-tools-call-the-server" aria-label="Permalink to &quot;How do host tools call the server?&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;list_warehouses&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  { region: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;us-east&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>The model can call the same server. Use a host tool when the write needs an allowlist or other deterministic gate.</p><h2 id="what-if-authorization-fails" tabindex="-1">What if authorization fails? <a class="header-anchor" href="#what-if-authorization-fails" aria-label="Permalink to &quot;What if authorization fails?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>Add <code>oauth: true</code> on that connection, or pick the right connection name</td></tr><tr><td>Callback never completes</td><td>Keep port <code>8787</code> free; finish the browser login on this machine</td></tr><tr><td>Hosted calls unauthorized after Connect or <code>--store</code></td><td>Confirm secrets with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy</td></tr><tr><td>Tokens ignored after URL change</td><td>Expected: resource URL binding drops stale entries. Re-run <code>mcp oauth</code></td></tr></tbody></table><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/connections.html">MCP connections</a>: transports, account MCP</li><li><a href="./../reference/cli.html#mcp-oauth">CLI</a>: full flag list for <code>mcp oauth</code></li><li><a href="./../deployment.html">Deployment</a>: secrets, egress, and hosted engines</li><li><a href="./../troubleshooting.html">Fix common agent problems</a>: more symptom → fix tables</li></ul>`,39)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_mcp-oauth.md.DMNMpXtO.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function o(h,e,l,d,r,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",39)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};