@cursor/july 0.1.108 → 0.1.111

package/dist/docs/assets/{guides_slack.md.D4RVMM4G.js → guides_slack.md.DdT8rmsj.js}

@@ -1,10 +1,10 @@
-import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;">​</a></h1><p>The Slack channel is a Socket Mode bot. The app connects out, so you don&#39;t need a public Request URL. Mentions and DMs start a thread. Replies stream there, with thinking steps and suggested prompts.</p><p>Use <code>agent-sdk slack create</code> when Cursor should own the Slack app. Use <code>agent-sdk slack init --manual</code> when you own it. Commands and flags live in the <a href="./../reference/cli.html#slack">CLI reference</a>. Coding agents should follow <a href="./../skills/setup-slack.html"><code>skills/setup-slack/SKILL.md</code></a>.</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/slack.ts</code> with <code>slackChannel()</code> from <code>@cursor/july/channels/slack</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;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/slack&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;">​</a></h1><p>The Slack channel is a Socket Mode bot. The app connects out, so you don&#39;t need a public Request URL. Mentions and DMs start a thread. Replies land in that thread. You choose the status chip, a live stream, or agent-owned posts.</p><p>Use <code>agent-sdk slack create</code> when Cursor should own the Slack app. Use <code>agent-sdk slack init --manual</code> when you own it. Commands and flags live in the <a href="./../reference/cli.html#slack">CLI reference</a>. Coding agents should follow <a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>.</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/slack.ts</code> with <code>slackChannel()</code> from <code>@cursor/july/channels/slack</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;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/slack&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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p><code>slackChannel()</code> reads <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. Pass <code>envPrefix: &quot;WEATHER_AGENT&quot;</code> to read <code>WEATHER_AGENT_SLACK_BOT_TOKEN</code> and <code>WEATHER_AGENT_SLACK_APP_TOKEN</code> instead. Use a prefix when one host serves several Slack bots.</p><p>A thread is one conversation. The bot answers mentions and DMs. It refuses Slack Connect users, guests, and people from other workspaces. Missing tokens leave this channel idle. The rest of <code>serve</code> still starts.</p><h2 id="control-who-can-message-the-agent" tabindex="-1">Control who can message the agent <a class="header-anchor" href="#control-who-can-message-the-agent" aria-label="Permalink to &quot;Control who can message the agent&quot;">​</a></h2><p>External senders are blocked. Set <code>blockExternals: false</code> only when people outside your org should reach the agent:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { blockExternals: </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;">});</span></span></code></pre></div><p>Anyone in the thread can continue it. Restrict follow-ups to the person who started the session with <code>respondTo: &quot;author&quot;</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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { respondTo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;author&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><h2 id="choose-how-the-reply-arrives" tabindex="-1">Choose how the reply arrives <a class="header-anchor" href="#choose-how-the-reply-arrives" aria-label="Permalink to &quot;Choose how the reply arrives&quot;">​</a></h2><p>Slack gives an agent two places to show progress while a turn runs: the status chip under the thread (&quot;Running grep…&quot;) and the reply message itself. It won&#39;t fill both at once. While a message is streaming, Slack shows its own &quot;is working…&quot; chip and hides any status text you set. Cards only exist inside a streamed message. <code>reply.mode</code> picks which one you get.</p><h3 id="post-default-status-chip-then-one-message" tabindex="-1"><code>post</code> (default): status chip, then one message <a class="header-anchor" href="#post-default-status-chip-then-one-message" aria-label="Permalink to &quot;\`post\` (default): status chip, then one message&quot;">​</a></h3><p>Tool calls and the first line of each reasoning block show in the chip as they happen. The answer lands as a single message when the turn finishes.</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;"> slackChannel</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><h2 id="choose-how-the-reply-arrives" tabindex="-1">Choose how the reply arrives <a class="header-anchor" href="#choose-how-the-reply-arrives" aria-label="Permalink to &quot;Choose how the reply arrives&quot;">​</a></h2><p>Slack gives an agent two places to show progress while a turn runs: the status chip under the thread (&quot;Running grep…&quot;) and the reply message itself. It won&#39;t fill both at once. While a message is streaming, Slack shows its own &quot;is working…&quot; chip and hides any status text you set. Cards only exist inside a streamed message. <code>reply.mode</code> picks the path.</p><h3 id="post-default-status-chip-then-one-message" tabindex="-1"><code>post</code> (default): status chip, then one message <a class="header-anchor" href="#post-default-status-chip-then-one-message" aria-label="Permalink to &quot;\`post\` (default): status chip, then one message&quot;">​</a></h3><p>Tool calls and the first line of each reasoning block show in the chip as they happen. The answer lands as a single message when the turn finishes.</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;post&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    status: {</span></span>
@@ -20,7 +20,15 @@ import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    toolCards: { group: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;per-tool&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;">  toolLabels: { grep: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Searching code&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, read: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Reading files&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 reasoning card is one task card, titled &quot;Thinking&quot;, that receives the model&#39;s reasoning as it streams and completes when the answer text starts. <code>maxChars</code> (default 1500) caps how much it collects. Slack caps a streamed message near 12k characters including cards; when an answer outgrows that, the streamed message closes where it stands and the rest continues in a new message.</p><p>Tool cards default to one card per tool name with a call count in the title (<code>grep ×3</code>), updated in place as calls finish. <code>group: &quot;per-call&quot;</code> shows one card per call instead.</p><p>Cards are collapsible by default: each call adds one line under the title, the same summary the playground shows in a tool&#39;s header (the grep pattern, the file path, the shell command), and the group expands the same way the reasoning card does. <code>collapsible: false</code> keeps cards to their titles. On a collapsible card, <code>details(call)</code> returns the line to add when a call starts and <code>output(result)</code> the text to add when it finishes.</p><p><code>toolLabels</code> renames tools everywhere they appear: the chip, card titles, and the default <code>Running …</code> line.</p><h3 id="migrating-from-streaming-and-thinkingsteps" tabindex="-1">Migrating from <code>streaming</code> and <code>thinkingSteps</code> <a class="header-anchor" href="#migrating-from-streaming-and-thinkingsteps" aria-label="Permalink to &quot;Migrating from \`streaming\` and \`thinkingSteps\`&quot;">​</a></h3><p><code>streaming: false</code> is <code>reply: { mode: &quot;post&quot; }</code>. <code>streaming: true</code> is <code>reply: { mode: &quot;stream&quot;, toolCards: { group: &quot;per-call&quot;, collapsible: false } }</code>, the title-only cards it used to show. <code>loadingMessages</code> moves to <code>reply.status.idle</code>. The old options still work and <code>agent-sdk validate</code> prints the rewrite for each one.</p><p>A channel that set none of these used to stream. It now posts. Set <code>reply: { mode: &quot;stream&quot; }</code> to keep streaming.</p><h2 id="set-it-up" tabindex="-1">Set it up <a class="header-anchor" href="#set-it-up" aria-label="Permalink to &quot;Set it up&quot;">​</a></h2><p><code>slack create</code> opens the Cursor dashboard wizard. Finish Slack consent and the bot name there. The CLI writes tokens to <code>.env.local</code> and never prints them. Skip the wizard if those tokens are already set, unless you want a Cursor-managed app.</p><h3 id="provision-with-the-cli" tabindex="-1">Provision with the CLI <a class="header-anchor" href="#provision-with-the-cli" aria-label="Permalink to &quot;Provision with the CLI&quot;">​</a></h3><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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</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:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The reasoning card is one task card, titled &quot;Thinking&quot;, that receives the model&#39;s reasoning as it streams and completes when the answer text starts. <code>maxChars</code> (default 1500) caps how much it collects. Slack caps a streamed message near 12k characters including cards; when an answer outgrows that, the streamed message closes where it stands and the rest continues in a new message.</p><p>Tool cards default to one card per tool name with a call count in the title (<code>grep ×3</code>), updated in place as calls finish. <code>group: &quot;per-call&quot;</code> shows one card per call instead.</p><p>Cards are collapsible by default: each call adds one line under the title, the same summary the playground shows in a tool&#39;s header (the grep pattern, the file path, the shell command), and the group expands the same way the reasoning card does. <code>collapsible: false</code> keeps cards to their titles. On a collapsible card, <code>details(call)</code> returns the line to add when a call starts and <code>output(result)</code> the text to add when it finishes.</p><p><code>toolLabels</code> renames tools everywhere they appear: the chip, card titles, and the default <code>Running …</code> line.</p><h3 id="agentic-the-agent-posts" tabindex="-1"><code>agentic</code>: the agent posts <a class="header-anchor" href="#agentic-the-agent-posts" aria-label="Permalink to &quot;\`agentic\`: the agent posts&quot;">​</a></h3><p>Opt in when the agent should own every message in the thread. Mentions and DMs still start turns. The channel does not write the status chip, tool cards, reasoning cards, or assistant text. Approval cards still post if you set <code>toolApprovals</code>.</p><p>Mount <code>@cursor/july/extensions/slack-communication</code> so the agent can talk. The extension adds typed tools and the <code>slack-voice</code> skill. The channel watches those tool names (bare or <code>&lt;namespace&gt;__&lt;name&gt;</code>) and calls Slack through the channel client after a successful result. A rejected call, a dry-run stub, or a turn that never calls <code>post-update</code> stays silent. The framework does not also finalize assistant text.</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/slack.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> slackCommunication </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions/slack-communication&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;"> slackCommunication</span><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/channels/slack.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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agentic&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><table tabindex="0"><thead><tr><th>Tool</th><th>What it writes</th><th>Scope</th></tr></thead><tbody><tr><td><code>post-update</code></td><td>Mid-turn progress and the final reply (<code>chat.postMessage</code> / <code>chat.update</code>)</td><td><code>chat:write</code></td></tr><tr><td><code>post-card</code></td><td>Collapsible task card (<code>chat.startStream</code> / <code>chat.appendStream</code>)</td><td><code>chat:write</code></td></tr><tr><td><code>post-file</code></td><td>Workspace file on the reply (<code>files.getUploadURLExternal</code>)</td><td><code>files:write</code></td></tr><tr><td><code>react</code></td><td>Emoji on a message <code>ts</code> (<code>reactions.add</code>). Omit <code>ts</code> for the thread root.</td><td><code>reactions:write</code></td></tr><tr><td><code>set-status</code></td><td>Subtitle chip (<code>assistant.threads.setStatus</code>). Empty string clears it.</td><td><code>assistant:write</code></td></tr></tbody></table><p><code>agent-sdk slack create</code> already grants those scopes. Do not add a freeform Slack method tool.</p><p>Pass <code>tone</code> to add agent-specific voice without forking the tools:</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;"> slackCommunication</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tone: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Lead with the merge decision. Name the risk next.&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><h3 id="migrating-from-streaming-and-thinkingsteps" tabindex="-1">Migrating from <code>streaming</code> and <code>thinkingSteps</code> <a class="header-anchor" href="#migrating-from-streaming-and-thinkingsteps" aria-label="Permalink to &quot;Migrating from \`streaming\` and \`thinkingSteps\`&quot;">​</a></h3><p><code>streaming: false</code> is <code>reply: { mode: &quot;post&quot; }</code>. <code>streaming: true</code> is <code>reply: { mode: &quot;stream&quot;, toolCards: { group: &quot;per-call&quot;, collapsible: false } }</code>, the title-only cards it used to show. <code>loadingMessages</code> moves to <code>reply.status.idle</code>. The old options still work and <code>agent-sdk validate</code> prints the rewrite for each one.</p><p>A channel that set none of these used to stream. It now posts. Set <code>reply: { mode: &quot;stream&quot; }</code> to keep streaming.</p><h2 id="set-it-up" tabindex="-1">Set it up <a class="header-anchor" href="#set-it-up" aria-label="Permalink to &quot;Set it up&quot;">​</a></h2><p><code>slack create</code> opens the Cursor dashboard wizard. Finish Slack consent and the bot name there. The CLI writes tokens to <code>.env.local</code> and never prints them. Skip the wizard if those tokens are already set, unless you want a Cursor-managed app.</p><h3 id="provision-with-the-cli" tabindex="-1">Provision with the CLI <a class="header-anchor" href="#provision-with-the-cli" aria-label="Permalink to &quot;Provision with the CLI&quot;">​</a></h3><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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</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;"> --prod</span></span></code></pre></div><p>Sign in first (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). A team service-account key cannot create Slack apps. Finish <strong>Add Slack to this agent</strong> as the same Cursor account. Then run <code>agent-sdk slack doctor --prefix MY_AGENT</code> and serve:</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;"> --dev</span></span></code></pre></div><p>Invite the bot and mention it, or DM it. Expect a Thinking status, then a threaded streaming reply.</p><p>If Slack needs a workspace admin, keep the CLI running. Open the <strong>Request approval</strong> link it prints. After an admin approves, click <strong>Retry</strong> in the wizard.</p><p><code>slack destroy</code> deletes the Cursor-managed app. <code>slack icon</code> updates its icon. A second <code>slack create</code> for the same agent and environment replaces that app&#39;s manifest and tokens.</p><h3 id="provision-from-the-dashboard" tabindex="-1">Provision from the dashboard <a class="header-anchor" href="#provision-from-the-dashboard" aria-label="Permalink to &quot;Provision from the dashboard&quot;">​</a></h3><p>The same wizard is on <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">Deployed Agents</a>. Open <strong>Integrations</strong> and click <strong>Add Slack to this agent</strong>.</p><p>Local <code>agent-sdk serve</code> reads <code>.env.local</code>. The next deploy injects the stored secrets.</p><p>If Slack needs admin approval, click <strong>Request approval</strong>, then <strong>Retry</strong> after an admin approves.</p><p>The app row&#39;s menu covers rename, icon, token rotation, removal, and workspace disconnect.</p><h3 id="create-your-own-slack-app" tabindex="-1">Create your own Slack app <a class="header-anchor" href="#create-your-own-slack-app" aria-label="Permalink to &quot;Create your own Slack app&quot;">​</a></h3><p><code>slack init --manual</code> is for an app you own. It writes the channel file and Slack manifests. When Slack CLI (<code>~/.slack/bin/slack</code>) is logged in, it installs the app. When it isn&#39;t, install the app yourself.</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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --manual</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;"> --name</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;My Agent&quot;</span></span></code></pre></div><p>Install Slack CLI if you need it:</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;"> -fsSL</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://downloads.slack-edge.com/slack-cli/install.sh</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bash</span></span></code></pre></div><p>Log in with <code>slack login --no-prompt</code>. In Slack, send <code>/slackauthticket &lt;ticket&gt;</code>, then <code>slack login --ticket &lt;ticket&gt; --challenge &lt;code&gt;</code>. Install the workspace app with <code>slack app install</code>. Create a separate production app the same way.</p><p>Or paste <code>.slack/manifest.dev.json</code> at <a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">api.slack.com/apps</a> (<strong>Create New App</strong> → <strong>From a manifest</strong>). Repeat with <code>.slack/manifest.prod.json</code>. Dev and prod are separate Slack apps.</p><p>Then put a bot token (<code>xoxb-...</code>) and an app-level token with <code>connections:write</code> (<code>xapp-...</code>) in <code>.env.local</code>. Use the names <code>slack init --manual</code> printed. Run <code>slack doctor</code> and serve as above.</p><p>Serve this app with Agent SDK. Do not run <code>slack deploy</code>.</p><h2 id="choose-when-the-agent-engages" tabindex="-1">Choose when the agent engages <a class="header-anchor" href="#choose-when-the-agent-engages" aria-label="Permalink to &quot;Choose when the agent engages&quot;">​</a></h2><p>Mentions and DMs are on. Watching channel posts without a mention is opt-in:</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TRIAGE&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  engagement: {</span></span>
@@ -35,4 +43,4 @@ import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Pass <code>--channel-posts</code> on <code>slack create</code> or <code>slack init --manual</code> so the Slack app receives those events. The bot must be in each watched channel. <code>allow: [&quot;*&quot;]</code> watches every joined channel.</p><p>Set <code>includeBotPosts: true</code> for alert feeds and other bots. This app never wakes on its own posts.</p><h2 id="prepare-work-on-the-host" tabindex="-1">Prepare work on the host <a class="header-anchor" href="#prepare-work-on-the-host" aria-label="Permalink to &quot;Prepare work on the host&quot;">​</a></h2><p>Mention and DM handlers may return a prepared <code>message</code>, <code>workspaceFiles</code>, or <code>cloud</code> block. Use the same host-prep pattern as <a href="./webhooks.html#prepare-on-the-host-then-hand-off">custom channels</a>.</p><p>Slack file uploads attach automatically. Images become vision input. Supported documents become workspace files for the turn.</p><h2 id="add-approval-buttons" tabindex="-1">Add approval buttons <a class="header-anchor" href="#add-approval-buttons" aria-label="Permalink to &quot;Add approval buttons&quot;">​</a></h2><p>Tools with <code>needsApproval</code> park until a person decides. Post those decisions in Slack with one flag:</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  toolApprovals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The Slack app needs interactivity. Recreate it with <code>slack create</code> if clicks do nothing. Cards show redacted, truncated arguments. Execution still uses the full input, so review sensitive tools in the playground when the card may hide fields. The lifecycle is in <a href="./human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="run-several-agents-on-one-host" tabindex="-1">Run several agents on one host <a class="header-anchor" href="#run-several-agents-on-one-host" aria-label="Permalink to &quot;Run several agents on one host&quot;">​</a></h2><p>Give each agent its own Slack app and token pair. Set <code>envPrefix</code> so the names don&#39;t collide (<code>WEATHER_AGENT_SLACK_*</code>, <code>TRIAGE_SLACK_*</code>). Agents without tokens stay idle. The others still serve.</p>`,66)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The Slack app needs interactivity. Recreate it with <code>slack create</code> if clicks do nothing. Cards show redacted, truncated arguments. Execution still uses the full input, so review sensitive tools in the playground when the card may hide fields. The lifecycle is in <a href="./../reference/tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>.</p><h2 id="run-several-agents-on-one-host" tabindex="-1">Run several agents on one host <a class="header-anchor" href="#run-several-agents-on-one-host" aria-label="Permalink to &quot;Run several agents on one host&quot;">​</a></h2><p>Give each agent its own Slack app and token pair. Set <code>envPrefix</code> so the names don&#39;t collide (<code>WEATHER_AGENT_SLACK_*</code>, <code>TRIAGE_SLACK_*</code>). Agents without tokens stay idle. The others still serve.</p>`,75)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/{guides_slack.md.D4RVMM4G.lean.js → guides_slack.md.DdT8rmsj.lean.js}

@@ -1 +1 @@
-import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t("",66)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[t("",75)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/{guides_webhooks.md.DKdA43Qm.js → guides_webhooks.md.aQW10HRe.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function e(k,s,l,p,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="webhooks-and-custom-channels" tabindex="-1">Webhooks and custom channels <a class="header-anchor" href="#webhooks-and-custom-channels" aria-label="Permalink to &quot;Webhooks and custom channels&quot;">​</a></h1><p>A custom channel gives the agent its own HTTP surface. You get routes with validated payloads, sessions keyed to something in your domain (a thread, a ticket, a PR), and replies delivered back to the caller. The <a href="./slack.html">Slack</a> and <a href="./github.html">GitHub</a> packs build on this mechanism. This page is the mechanism itself.</p><h2 id="what-you-already-have" tabindex="-1">What you already have <a class="header-anchor" href="#what-you-already-have" aria-label="Permalink to &quot;What you already have&quot;">​</a></h2><p>The built-in HTTP channel is always mounted (under <code>/&lt;slug&gt;</code> in the default multi-agent layout). <code>POST /v1/session</code> starts a conversation, <code>POST /v1/session/:id</code> follows up, and <code>GET /v1/session/:id/stream</code> streams NDJSON events, plus sessions, approvals, and tool routes. See the <a href="./../reference/http-api.html">HTTP API reference</a>.</p><p>Write a custom channel when that shape doesn&#39;t fit: a webhook with its own payload contract, a surface that keys sessions by a domain id, or a flow that does host-side work before (or instead of) a model turn.</p><h2 id="define-a-channel" tabindex="-1">Define a channel <a class="header-anchor" href="#define-a-channel" aria-label="Permalink to &quot;Define a channel&quot;">​</a></h2><p>Author <code>agent/channels/&lt;id&gt;.ts</code> with <code>defineChannel</code>. The filename is the channel id, and routes mount under <code>/v1/channels/&lt;id&gt;</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;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.dypDpWZ3.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function e(k,s,l,p,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="webhooks-and-custom-channels" tabindex="-1">Webhooks and custom channels <a class="header-anchor" href="#webhooks-and-custom-channels" aria-label="Permalink to &quot;Webhooks and custom channels&quot;">​</a></h1><p>A custom channel gives the agent its own HTTP surface. You get routes with validated payloads, sessions keyed to something in your domain (a thread, a ticket, a PR), and replies delivered back to the caller. The <a href="./slack.html">Slack</a> and <a href="./github.html">GitHub</a> packs build on this mechanism. The <a href="./gitlab.html">GitLab</a> and <a href="./bitbucket.html">Bitbucket</a> packs use it too. This page is the mechanism itself.</p><h2 id="what-you-already-have" tabindex="-1">What you already have <a class="header-anchor" href="#what-you-already-have" aria-label="Permalink to &quot;What you already have&quot;">​</a></h2><p>The built-in HTTP channel is always mounted (under <code>/&lt;slug&gt;</code> in the default multi-agent layout). <code>POST /v1/session</code> starts a conversation, <code>POST /v1/session/:id</code> follows up, and <code>GET /v1/session/:id/stream</code> streams NDJSON events, plus sessions, approvals, and tool routes. See the <a href="./../reference/http-api.html">HTTP API reference</a>.</p><p>Write a custom channel when that shape doesn&#39;t fit: a webhook with its own payload contract, a surface that keys sessions by a domain id, or a flow that does host-side work before (or instead of) a model turn.</p><h2 id="define-a-channel" tabindex="-1">Define a channel <a class="header-anchor" href="#define-a-channel" aria-label="Permalink to &quot;Define a channel&quot;">​</a></h2><p>Author <code>agent/channels/&lt;id&gt;.ts</code> with <code>defineChannel</code>. The filename is the channel id, and routes mount under <code>/v1/channels/&lt;id&gt;</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;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&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;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -174,7 +174,7 @@ import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const o
 <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:#6A737D;--shiki-dark:#6A737D;">// Uses the signed-in Cursor account&#39;s Linear connector.</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;"> 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;">, servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] });</span></span></code></pre></div><p>See <a href="./../reference/connections.html">MCP connections</a> for the direct <code>https://mcp.linear.app/mcp</code> form when the host isn&#39;t signed in to Cursor.</p><h3 id="production-linear-agents-expiring-oauth-tokens" tabindex="-1">Production Linear agents: expiring OAuth tokens <a class="header-anchor" href="#production-linear-agents-expiring-oauth-tokens" aria-label="Permalink to &quot;Production Linear agents: expiring OAuth tokens&quot;">​</a></h3><p>A plain API key fits a personal integration. A production Linear agent is an OAuth application: installing it in a workspace mints an access token with an expiry plus a refresh token. The serve host can be replaced at any time, so the pair can&#39;t live in process memory. Persist it in <a href="./../storage.html#author-kv-ctx-host-kv"><code>host.kv</code></a> instead. Route handlers receive <code>host</code> in their args, and event handlers get the same services on <code>ctx</code>.</p><p>Two prerequisites:</p><ul><li>Keep the OAuth client id and client secret in <a href="./../deployment.html">deployment secrets</a>. They&#39;re static, so deploy-time env vars fit them.</li><li>Back kv with durable storage. On Cursor-managed hosting, use <code>cursorHostedStorage</code> in <code>agent/storage.ts</code> (<a href="./../storage.html">Storage</a>). Without it, kv falls back to local disk and a host replacement drops the tokens.</li></ul><p>Save the pair when the install flow completes, then refresh on demand:</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:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { HostKvApi } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/kv&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</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;"> 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;">, servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] });</span></span></code></pre></div><p>See <a href="./../reference/connections.html">MCP connections</a> for the direct <code>https://mcp.linear.app/mcp</code> form when the host isn&#39;t signed in to Cursor.</p><h3 id="production-linear-agents-expiring-oauth-tokens" tabindex="-1">Production Linear agents: expiring OAuth tokens <a class="header-anchor" href="#production-linear-agents-expiring-oauth-tokens" aria-label="Permalink to &quot;Production Linear agents: expiring OAuth tokens&quot;">​</a></h3><p>A plain API key fits a personal integration. A production Linear agent is an OAuth application: installing it in a workspace mints an access token with an expiry plus a refresh token. The serve host can be replaced at any time, so the pair can&#39;t live in process memory. Persist it in <code>host.kv</code> instead. Route handlers receive <code>host</code> in their args, and event handlers get the same services on <code>ctx</code>.</p><p>Two prerequisites:</p><ul><li>Keep the OAuth client id and client secret in <a href="./../deployment.html">deployment secrets</a>. They&#39;re static, so deploy-time env vars fit them.</li><li>Back kv with durable storage. On Cursor-managed hosting, use <code>cursorHostedStorage</code> in <code>agent/storage.ts</code>. Without it, kv falls back to local disk and a host replacement drops the tokens.</li></ul><p>Save the pair when the install flow completes, then refresh on demand:</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:#D73A49;--shiki-dark:#F97583;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { HostKvApi } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/kv&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;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LinearTokens</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  accessToken</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -222,4 +222,4 @@ import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const o
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  .update(fs.readFileSync(&quot;fixtures/issue-create.json&quot;)).digest(&quot;hex&quot;))&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</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/linear/</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;"> -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;linear-signature: </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$SIG</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --data-binary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @fixtures/issue-create.json</span></span></code></pre></div><h2 id="test-a-channel" tabindex="-1">Test a channel <a class="header-anchor" href="#test-a-channel" aria-label="Permalink to &quot;Test a channel&quot;">​</a></h2><p>Start with curl and saved payloads under <code>fixtures/</code>. The playground&#39;s <strong>Try</strong> modal covers manual probes. It remembers your last body per endpoint, has Copy curl, and opens the created session on a successful Try. For regression coverage, drive the same behavior through an eval, or keep channel logic deterministic in <code>agent/lib/</code> and unit-test it there. When something looks wrong, inspect the session event stream. The stream is the record of what happened.</p><p>For GitHub specifically, don&#39;t hand-roll fixtures. <code>agent-sdk github replay</code> synthesizes real-shaped, signed payloads from any PR you can read. See the <a href="./github.html">GitHub guide</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/channels.html">Channels reference</a>: the full authoring API</li><li><a href="./github.html">GitHub</a> and <a href="./slack.html">Slack</a>: the packaged channels</li><li><a href="./../reference/sessions.html">Sessions and streaming</a>: events your channel can subscribe to</li></ul>`,60)])])}const g=i(t,[["render",e]]);export{o as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --data-binary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @fixtures/issue-create.json</span></span></code></pre></div><h2 id="test-a-channel" tabindex="-1">Test a channel <a class="header-anchor" href="#test-a-channel" aria-label="Permalink to &quot;Test a channel&quot;">​</a></h2><p>Start with curl and saved payloads under <code>fixtures/</code>. The playground&#39;s <strong>Try</strong> modal covers manual probes. It remembers your last body per endpoint, has Copy curl, and opens the created session on a successful Try. For regression coverage, drive the same behavior through an eval, or keep channel logic deterministic in <code>agent/lib/</code> and unit-test it there. When something looks wrong, inspect the session event stream. The stream is the record of what happened.</p><p>For GitHub specifically, don&#39;t hand-roll fixtures. <code>agent-sdk github replay</code> synthesizes real-shaped, signed payloads from any PR you can read. See the <a href="./github.html">GitHub guide</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/channels.html">Channels reference</a>: the full authoring API</li><li><a href="./github.html">GitHub</a>, <a href="./gitlab.html">GitLab</a>, <a href="./bitbucket.html">Bitbucket</a>, and <a href="./slack.html">Slack</a>: the packaged channels</li><li><a href="./../reference/sessions.html">Sessions and streaming</a>: events your channel can subscribe to</li></ul>`,60)])])}const g=i(t,[["render",e]]);export{o as __pageData,g as default};

package/dist/docs/assets/{guides_webhooks.md.DKdA43Qm.lean.js → guides_webhooks.md.aQW10HRe.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function e(k,s,l,p,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",60)])])}const g=i(t,[["render",e]]);export{o as __pageData,g as default};
+import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.dypDpWZ3.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function e(k,s,l,p,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",60)])])}const g=i(t,[["render",e]]);export{o as __pageData,g as default};

package/dist/docs/assets/hillclimbing.md.Dq4kkVIL.js

@@ -0,0 +1 @@
+import{_ as o,C as n,c as r,o as t,a3 as a,b as s,w as i,a as h,G as d,a4 as u}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Hillclimbing","description":"Improve an agent one measured round at a time, with the hillclimb skill running the loop with you.","frontmatter":{"title":"Hillclimbing","description":"Improve an agent one measured round at a time, with the hillclimb skill running the loop with you."},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),c={name:"hillclimbing.md"};function m(g,e,p,b,f,w){const l=n("Mermaid");return t(),r("div",null,[e[1]||(e[1]=a('<h1 id="hillclimbing" tabindex="-1">Hillclimbing <a class="header-anchor" href="#hillclimbing" aria-label="Permalink to &quot;Hillclimbing&quot;">​</a></h1><p>Make an agent better on fixed inputs: measure, change one lever, remeasure, and lock every kept win with an eval.</p><h2 id="what-is-hillclimbing" tabindex="-1">What is hillclimbing? <a class="header-anchor" href="#what-is-hillclimbing" aria-label="Permalink to &quot;What is hillclimbing?&quot;">​</a></h2><p>Hillclimbing is a measured improvement loop. You pin a few fixtures, name the one dominant problem in the run, change one lever, and check the same fixtures again. Keep only what helps. Every kept change lands an <a href="./evals.html">eval</a> so the win stays put.</p><p>You don&#39;t have to run the loop alone. The package ships a coding-agent skill that drives it with you.</p>',5)),(t(),s(u,null,{default:i(()=>[d(l,{id:"mermaid-15",class:"mermaid",graph:"flowchart%20LR%0A%20%20measure%5BMeasure%5D%20--%3E%20change%5BChange%20one%20lever%5D%0A%20%20change%20--%3E%20remeasure%5BRemeasure%5D%0A%20%20remeasure%20--%3E%20measure%0A"})]),fallback:i(()=>[...e[0]||(e[0]=[h(" Loading... ",-1)])]),_:1})),e[2]||(e[2]=a('<h2 id="how-do-i-hillclimb-an-agent-with-a-coding-agent" tabindex="-1">How do I hillclimb an agent with a coding agent? <a class="header-anchor" href="#how-do-i-hillclimb-an-agent-with-a-coding-agent" aria-label="Permalink to &quot;How do I hillclimb an agent with a coding agent?&quot;">​</a></h2><p>Have Cursor read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>.</p><p>Tell it:</p><ol><li><strong>Which agent</strong> you&#39;re improving (path or slug)</li><li><strong>One to three fixtures</strong> you&#39;ll reuse every round: a PR URL, a saved webhook body, or a canonical chat prompt</li><li><strong>What &quot;better&quot; means</strong> this round: correct tool choice, fewer tools, lower latency, or output quality. Name the freeze line too: API shape, public output, and existing evals that must stay green</li></ol><p>The skill serves the agent, hits your fixtures, reads the session trajectory, proposes one change, remeasures, and checks with you before the next round.</p><p>Other skills cover the edges:</p><table tabindex="0"><thead><tr><th>When you need…</th><th>Skill</th></tr></thead><tbody><tr><td>The measured improvement loop</td><td><a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a></td></tr><tr><td>An eval that locks a kept win</td><td><a href="./../skills/evals/SKILL.html"><code>skills/evals/SKILL.md</code></a></td></tr><tr><td>Repeatable GitHub webhook inputs</td><td><a href="./../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a></td></tr><tr><td>A run that misbehaves</td><td><a href="./../skills/debug/SKILL.html"><code>skills/debug/SKILL.md</code></a></td></tr></tbody></table><p>See <a href="./building-with-agents.html">Building agents with agents</a> for every framework skill and a good first prompt.</p><h2 id="what-do-i-need-before-a-hillclimb-round" tabindex="-1">What do I need before a hillclimb round? <a class="header-anchor" href="#what-do-i-need-before-a-hillclimb-round" aria-label="Permalink to &quot;What do I need before a hillclimb round?&quot;">​</a></h2><p>Agree on four things before you edit:</p><ol><li><strong>The target agent</strong>: the project you&#39;re improving</li><li><strong>Fixtures</strong>: one to three fixed inputs you can compare across runs</li><li><strong>Success criteria</strong>: what better means this round</li><li><strong>The freeze line</strong>: what must not change</li></ol><p>Pin the input first. A moving fixture is noise. For GitHub agents, use <code>agent-sdk github replay</code> (see the <a href="./guides/github.html">GitHub guide</a>). For a single tool without a model turn, use <code>agent-sdk call</code>. For a chat turn, use <code>agent-sdk run --dir . --message &quot;…&quot;</code>.</p><h2 id="how-do-i-run-one-hillclimb-round" tabindex="-1">How do I run one hillclimb round? <a class="header-anchor" href="#how-do-i-run-one-hillclimb-round" aria-label="Permalink to &quot;How do I run one hillclimb round?&quot;">​</a></h2><p><strong>Measure.</strong> Hit the agent the way a user would: playground, channel HTTP, or Slack in <code>--dev</code>. Or ask the hillclimb skill to do it. <code>agent-sdk run</code> returns a JSON trajectory and writes a trace under the project state directory.</p><p><strong>Reflect.</strong> Score the trajectory, not impressions. Was the answer right? Did the model thrash (too many tools, fat evidence, grep loops)? Did it invent work the host should have prepared? Name the single dominant problem for this round in one sentence. Example: &quot;Full-file dumps trigger grep loops.&quot;</p><p><strong>Change one lever.</strong> Prefer the smallest change that addresses that problem:</p><ol><li>Host prep: seed what the model needs so it doesn&#39;t hunt</li><li>Evidence shape: trim or reorder artifacts</li><li>Instructions and skills: tighten the procedure</li><li>Tool surface: remove or gate tools that invite wandering</li><li>Framework changes: only when the agent can&#39;t express the fix</li></ol><p><strong>Remeasure.</strong> Same fixtures. Diff tools, wall time, and quality side by side. Keep the change only if the target metric improves and the freeze line holds.</p><h2 id="how-do-i-lock-a-hillclimb-improvement-with-an-eval" tabindex="-1">How do I lock a hillclimb improvement with an eval? <a class="header-anchor" href="#how-do-i-lock-a-hillclimb-improvement-with-an-eval" aria-label="Permalink to &quot;How do I lock a hillclimb improvement with an eval?&quot;">​</a></h2><p>Every kept change needs an eval that would have failed before the change: a tool-choice gate, a <code>maxToolCalls</code> bound, or an output-shape check. Run <code>agent-sdk eval --dir . --json</code> between rounds. Never weaken an existing gate to pass the round.</p><p>Details live in <a href="./evals.html#keep-improvements-with-regression-evals">Keep improvements with regression evals</a>. The evals skill will author the case with you.</p><h2 id="what-habits-help-hillclimbing-stay-reliable" tabindex="-1">What habits help hillclimbing stay reliable? <a class="header-anchor" href="#what-habits-help-hillclimbing-stay-reliable" aria-label="Permalink to &quot;What habits help hillclimbing stay reliable?&quot;">​</a></h2><ul><li>One problem per round. Don&#39;t bundle &quot;trim evidence and rewrite instructions&quot; unless you chose that on purpose.</li><li>Keep fixtures fixed until you deliberately need a harder case.</li><li>Separate host work from model tools when you blame latency. Moving deterministic prep onto the host is often the biggest win. In one PR reviewer, host-prepared evidence cut turns from about 8 minutes to about 1 minute.</li><li>Spot-check quality on at least one fixture against a known-good answer. Efficiency-only climbs quietly drop findings.</li><li>Treat <code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> as expected when a follow-up or stop preempted the turn.</li><li>Don&#39;t deploy, post to real surfaces, or weaken evals as part of a climb.</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./evals.html">Evals</a></li><li><a href="./building-with-agents.html">Building agents with agents</a></li><li><a href="./guides/github.html">GitHub guide</a></li><li><a href="./troubleshooting.html">Fix common agent problems</a></li></ul>',25))])}const y=o(c,[["render",m]]);export{k as __pageData,y as default};

package/dist/docs/assets/hillclimbing.md.Dq4kkVIL.lean.js

@@ -0,0 +1 @@
+import{_ as o,C as n,c as r,o as t,a3 as a,b as s,w as i,a as h,G as d,a4 as u}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Hillclimbing","description":"Improve an agent one measured round at a time, with the hillclimb skill running the loop with you.","frontmatter":{"title":"Hillclimbing","description":"Improve an agent one measured round at a time, with the hillclimb skill running the loop with you."},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),c={name:"hillclimbing.md"};function m(g,e,p,b,f,w){const l=n("Mermaid");return t(),r("div",null,[e[1]||(e[1]=a("",5)),(t(),s(u,null,{default:i(()=>[d(l,{id:"mermaid-15",class:"mermaid",graph:"flowchart%20LR%0A%20%20measure%5BMeasure%5D%20--%3E%20change%5BChange%20one%20lever%5D%0A%20%20change%20--%3E%20remeasure%5BRemeasure%5D%0A%20%20remeasure%20--%3E%20measure%0A"})]),fallback:i(()=>[...e[0]||(e[0]=[h(" Loading... ",-1)])]),_:1})),e[2]||(e[2]=a("",25))])}const y=o(c,[["render",m]]);export{k as __pageData,y as default};

package/dist/docs/assets/index.md.BFVyY2KT.js

@@ -0,0 +1,17 @@
+import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const r="/docs/architecture.svg",g=JSON.parse(`{"title":"Agent SDK","description":"Build, test, and deploy agents as code on Cursor's agent harness.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy agents as code on Cursor's agent harness."},"headers":[],"relativePath":"index.md","filePath":"README.md"}`),o={name:"index.md"};function i(l,e,d,p,h,c){return a(),s("div",null,[...e[0]||(e[0]=[n('<h1 id="agent-sdk" tabindex="-1">Agent SDK <a class="header-anchor" href="#agent-sdk" aria-label="Permalink to &quot;Agent SDK&quot;">​</a></h1><p>The Agent SDK is how Cursor builds agents. It&#39;s the open-source version of the engine behind Bugbot, Security Review, and Approval Bot.</p><p>Agents are folders containing markdown and typescript, Cursor provides abstractions to give you the building blocks you need to make your agents available where you work: Source Control, Slack, Issue Tracking, and the Cursor apps.</p><p>Use any model and make each agent unique by building custom harnessses that combine the flexibility of deterministic TypeScript, and the expressiveness of agents.</p><h2 id="why-use-it" tabindex="-1">Why use it <a class="header-anchor" href="#why-use-it" aria-label="Permalink to &quot;Why use it&quot;">​</a></h2><ul><li><p><strong>Agent live in your repo.</strong> Instructions, tools, and evals are files you review, version, and ship like the rest of your code.</p></li><li><p><strong>Cursor runs the agent loop.</strong> You write the instructions and tools. Your agent gets Cursor&#39;s models, tool calling, skills, MCP, and subagents. Each turn runs on your host or on a Cursor cloud agent.</p></li><li><p><strong>Agents are available where you work.</strong> Trigger it from Source Control events, Slack threads, or write your own Webhooks and custom schedules.</p></li><li><p><strong>Easily testable and extendable.</strong> Write your evals, unit tests in normal TypeScript code.</p></li><li><p><strong>Easy to host.</strong> your Agents can be hosted and eval&#39;d on Cursor&#39;s battle tested infrastructure.</p></li></ul><h2 id="when-to-use-the-agent-sdk" tabindex="-1">When to use the Agent SDK <a class="header-anchor" href="#when-to-use-the-agent-sdk" aria-label="Permalink to &quot;When to use the Agent SDK&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Cursor Automations</th><th>Grok Bot</th><th>Agent SDK</th></tr></thead><tbody><tr><td><strong>Use for</strong></td><td>Repeatable jobs driven by a prompt and a trigger</td><td>Interactive agents that work with you in Cursor</td><td>Agents that need custom code, integrations, tests, or deployment choices</td></tr><tr><td><strong>You define</strong></td><td>A prompt, model, and trigger in the dashboard</td><td>Instructions, skills, and connected tools in the app</td><td>A versioned Markdown and TypeScript project</td></tr><tr><td><strong>Where it runs</strong></td><td>Cursor-managed</td><td>Cursor-managed</td><td>Cursor-managed hosting or your infrastructure</td></tr><tr><td><strong>Choose it when</strong></td><td>The job fits a schedule or event trigger</td><td>You want an agent you can configure and talk to without creating a software project</td><td>You want deterministic code around model judgment and a project your team can review and test</td></tr></tbody></table><h2 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h2><p>Agents are defined as code in your source control of choice, execution, inference and sandboxing runs on Cursor infrastructure or self-hosted.</p><p><img src="'+r+`" alt="Agent SDK architecture: you bring the agent as code, the platform provides triggers, runtime, integrations, and operations"></p><p>The next steps in this guide will help you build your first agent, or choose from one of the templates we offer.</p><h2 id="get-started" tabindex="-1">Get started <a class="header-anchor" href="#get-started" aria-label="Permalink to &quot;Get started&quot;">​</a></h2><ol><li>Install the Agent SDK</li></ol><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/agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</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><ol start="2"><li>Open Cursor</li></ol><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
+<span class="line"><span>├── package.json</span></span>
+<span class="line"><span>├── agent/</span></span>
+<span class="line"><span>│   ├── agent.ts               # model and runtime</span></span>
+<span class="line"><span>│   ├── instructions.md        # the system prompt</span></span>
+<span class="line"><span>│   ├── tools/</span></span>
+<span class="line"><span>│   │   └── approve_pr.ts      # one typed tool per file</span></span>
+<span class="line"><span>│   ├── skills/</span></span>
+<span class="line"><span>│   │   └── pr-review.md       # procedures the model loads on demand</span></span>
+<span class="line"><span>│   ├── mcp-connections/</span></span>
+<span class="line"><span>│   │   └── linear.ts          # tools from an MCP server</span></span>
+<span class="line"><span>│   └── channels/</span></span>
+<span class="line"><span>│       └── github.ts          # wake on pull requests, CI, and comments</span></span>
+<span class="line"><span>└── evals/</span></span>
+<span class="line"><span>    └── readiness.eval.ts      # regression checks</span></span></code></pre></div><ol start="3"><li>Describe your Agent Describe your Agent in the Cursor app, or edit the code yourself.</li></ol><h2 id="next-steps" tabindex="-1">Next steps <a class="header-anchor" href="#next-steps" aria-label="Permalink to &quot;Next steps&quot;">​</a></h2><ul><li><p><a href="./quickstart.html">Build your first PR reviewer</a>: a working GitHub reviewer, one step at a time.</p></li><li><p>Start from a template with <code>init --template</code>: <a href="./templates/security-reviewer.html">security reviewer</a>, <a href="./templates/agentic-owners.html">owners-policy approver</a>, <a href="./templates/pr-autofixer.html">PR autofixer</a>, or <a href="./templates/triage.html">issue triager</a>.</p></li><li><p><a href="./guides/convert-automation.html">Convert a Cursor Automation</a>: export an Automation from the dashboard into a project you own.</p></li><li><p><a href="./building-with-agents.html">Build agents with agents</a>: hand the build to a coding agent with the package&#39;s bundled skills.</p></li><li><p><a href="./reference/project-layout.html">Project layout</a> and <a href="./reference/cli.html">CLI</a>: every folder and every command.</p></li></ul>`,20)])])}const m=t(o,[["render",i]]);export{g as __pageData,m as default};

package/dist/docs/assets/index.md.BFVyY2KT.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const r="/docs/architecture.svg",g=JSON.parse(`{"title":"Agent SDK","description":"Build, test, and deploy agents as code on Cursor's agent harness.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy agents as code on Cursor's agent harness."},"headers":[],"relativePath":"index.md","filePath":"README.md"}`),o={name:"index.md"};function i(l,e,d,p,h,c){return a(),s("div",null,[...e[0]||(e[0]=[n("",20)])])}const m=t(o,[["render",i]]);export{g as __pageData,m as default};