@cursor/july 0.1.99 → 0.1.101

package/dist/docs/assets/{guides_slack.md.VDXQV3ja.js → guides_slack.md.9oHPye9o.js}

@@ -1,10 +1,26 @@
-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,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 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/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>
+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 h(l,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>
 <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="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><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;">  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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      reasoning: </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;">      tools: </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;">      idle: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Checking the monorepo…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Poking Datadog…&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:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>idle</code> is the rotation Slack cycles through when nothing more specific is known, up to 5 lines of 50 characters. Pass a function to <code>tools</code> to write your own line from the calls in flight.</p><h3 id="stream-live-text-with-cards" tabindex="-1"><code>stream</code>: live text, with cards <a class="header-anchor" href="#stream-live-text-with-cards" aria-label="Permalink to &quot;\`stream\`: live text, with cards&quot;">​</a></h3><p>The answer streams into one message as the model writes it. Slack owns the chip for the duration, so live feedback inside the message comes from cards. Both are off unless you turn them on.</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;stream&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    reasoningCard: </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;">    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:#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>). 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>
@@ -19,4 +35,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>`,50)])])}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="./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",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{guides_slack.md.VDXQV3ja.lean.js → guides_slack.md.9oHPye9o.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,d,r){return i(),e("div",null,[...s[0]||(s[0]=[t("",50)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};
+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 h(l,s,o,p,r,d){return i(),e("div",null,[...s[0]||(s[0]=[t("",66)])])}const g=a(n,[["render",h]]);export{c as __pageData,g as default};

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

@@ -0,0 +1,4 @@
+import{_ as t,c as i,o as a,ag as l}from"./chunks/framework.BCISBCiQ.js";const m=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"}'),o={name:"hillclimbing.md"};function n(r,e,s,h,d,c){return a(),i("div",null,[...e[0]||(e[0]=[l(`<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><div class="language-mermaid vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">mermaid</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;">flowchart LR</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  measure[Measure] --&gt; change[Change one lever]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  change --&gt; remeasure[Remeasure]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  remeasure --&gt; measure</span></span></code></pre></div><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.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.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.html"><code>skills/evals/SKILL.md</code></a></td></tr><tr><td>Repeatable GitHub webhook inputs</td><td><a href="./skills/github.html"><code>skills/github/SKILL.md</code></a></td></tr><tr><td>A run that misbehaves</td><td><a href="./skills/debug.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, an <code>action.result</code> count 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">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>`,31)])])}const p=t(o,[["render",n]]);export{m as __pageData,p as default};

package/dist/docs/assets/{index.md.CVeRUOeZ.js → index.md.Bb4k8kUm.js}

@@ -2,4 +2,4 @@ import{_ as t,c as a,o as i,ag as s}from"./chunks/framework.BCISBCiQ.js";const p
 <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><p>If <code>agent-sdk</code> isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><p>Open the docs locally:</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;"> docs</span></span></code></pre></div><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to the Agent SDK</td><td><a href="./quickstart.html">Quickstart</a> (PR reviewer), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Turning a Cursor Automation into a project</td><td><a href="./guides/convert-automation.html">Convert a Cursor Automation</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Starting from a packaged template</td><td><a href="./templates/demo.html">Demo</a>, <a href="./templates/code-wiki.html">Code wiki</a>, <a href="./templates/agents-md.html">Living AGENTS.md</a>, <a href="./templates/security-reviewer.html">Security reviewer</a>, <a href="./templates/security-help.html">Security help</a>, <a href="./templates/triage.html">Triage</a>, or <a href="./templates/agentic-owners.html">Agentic Owners</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Driving PRs from a cloud VM</td><td><a href="./templates/pr-autofixer.html">PR autofixer template</a></td></tr><tr><td>Driving an agent from Linear (or another tracker)</td><td><a href="./guides/webhooks.html#example-linear-as-the-control-plane">Webhooks guide: Linear example</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR reviewer that classifies changes by complexity and handles GitHub webhook events.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./guides/convert-automation.html">Convert a Cursor Automation</a>: export a dashboard Automation into an Agent SDK project.</li><li><a href="./concepts.html">Concepts</a>: agent discovery, sessions, channels, runtimes, and observability.</li></ul><p><strong>Templates</strong></p><ul><li><a href="./templates/demo.html">Record a walkthrough from a collected PR</a>: host collects the PR, the model records, then comments.</li><li><a href="./templates/code-wiki.html">Keep a code wiki current after merge</a>: update in-repo <code>wiki/</code> pages when a pull request merges.</li><li><a href="./templates/agents-md.html">Keep AGENTS.md current from last week&#39;s work</a>: pull rules out of merged PRs and Slack, then open a follow-up PR.</li><li><a href="./templates/security-reviewer.html">Security reviewer</a>: review pull requests for exploitable bugs and post one comment.</li><li><a href="./templates/security-help.html">Answer security questions in Slack</a>: answer from your skills, or take a first look at a pasted PR.</li><li><a href="./templates/triage.html">Triage Linear or Jira issues in place</a>: classify existing tickets and comment on them.</li><li><a href="./templates/agentic-owners.html">Review pull requests with owners policies</a>: request owners and approve changes allowed by repository policy.</li><li><a href="./templates/pr-autofixer.html">Fix pull requests on a Cursor cloud VM</a></li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./storage.html">Storage</a>: point durable storage at a backend you own with <code>defineStorage</code>.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: measure and improve an agent iteratively.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: trigger the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and persist them on hosted deployments (<code>--store</code>).</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li><li><a href="./guides/opentelemetry.html">OpenTelemetry</a>: push session, turn, and tool traces to an OTLP collector you run.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: diagnose common failures by symptom.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>Docs use <code>agent-sdk &lt;command&gt;</code>. If it isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Sign in to Cursor or set <code>CURSOR_API_KEY</code>:</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>Confirm <code>agent-sdk whoami</code> shows the expected account.</p><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><ul><li>Package reference: <a href="./../README.html"><code>README.md</code></a></li><li>Coding-agent workflows: <a href="./../skills/"><code>skills/</code></a></li></ul>`,31)])])}const m=t(r,[["render",n]]);export{p as __pageData,m as default};
+<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>Confirm <code>agent-sdk whoami</code> shows the expected account.</p><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><ul><li>Package reference: <a href="./../README.html"><code>README.md</code></a></li><li>Coding-agent workflows: <a href="./skills/"><code>skills/</code></a></li></ul>`,31)])])}const m=t(r,[["render",n]]);export{p as __pageData,m as default};

package/dist/docs/assets/{quickstart.md.Nj_LjW_a.js → quickstart.md.DdQOF7Y8.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),t={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="build-your-first-pr-reviewer" tabindex="-1">Build your first PR reviewer <a class="header-anchor" href="#build-your-first-pr-reviewer" aria-label="Permalink to &quot;Build your first PR reviewer&quot;">​</a></h1><p>Build a GitHub PR reviewer that classifies changes as <code>trivial</code>, <code>moderate</code>, or <code>large</code>, then approves safe changes or requests human review. Add GitHub event handling so pull requests can trigger reviews.</p><h2 id="getting-started" tabindex="-1">Getting started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting started&quot;">​</a></h2><ul><li><strong>Get started with an agent in Cursor:</strong> follow <a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a> and ask Cursor to read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a>.</li><li><strong>Get started in the CLI:</strong> continue below.</li></ul><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li>Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Run commands as <code>agent-sdk &lt;command&gt;</code>, or use <code>npx @cursor/july &lt;command&gt;</code> when the CLI isn&#39;t on <code>PATH</code>. See <a href="/docs/#run-the-cli">Run the CLI</a> if <code>agent-sdk</code> is not on <code>PATH</code>.</li><li>A Cursor credential for model turns. Sign in once:</li></ul><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></code></pre></div><p>You can also set <code>CURSOR_API_KEY</code> instead of signing in.</p><ul><li>Authenticate with <code>gh auth login</code> or <code>GITHUB_TOKEN</code>. You can read public pull requests. Posting reviews requires repository write access.</li></ul><h2 id="create-and-run-the-project" tabindex="-1">Create and run the project <a class="header-anchor" href="#create-and-run-the-project" aria-label="Permalink to &quot;Create and run the project&quot;">​</a></h2><p>Initialize the project and start the development server:</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;"> ./sdk-pr-reviewer</span></span>
+import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),t={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="build-your-first-pr-reviewer" tabindex="-1">Build your first PR reviewer <a class="header-anchor" href="#build-your-first-pr-reviewer" aria-label="Permalink to &quot;Build your first PR reviewer&quot;">​</a></h1><p>Build a GitHub PR reviewer that classifies changes as <code>trivial</code>, <code>moderate</code>, or <code>large</code>, then approves safe changes or requests human review. Add GitHub event handling so pull requests can trigger reviews.</p><h2 id="getting-started" tabindex="-1">Getting started <a class="header-anchor" href="#getting-started" aria-label="Permalink to &quot;Getting started&quot;">​</a></h2><ul><li><strong>Get started with an agent in Cursor:</strong> follow <a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a> and ask Cursor to read <a href="./skills/create-agent.html"><code>skills/create-agent/SKILL.md</code></a>.</li><li><strong>Get started in the CLI:</strong> continue below.</li></ul><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li>Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Run commands as <code>agent-sdk &lt;command&gt;</code>, or use <code>npx @cursor/july &lt;command&gt;</code> when the CLI isn&#39;t on <code>PATH</code>. See <a href="/docs/#run-the-cli">Run the CLI</a> if <code>agent-sdk</code> is not on <code>PATH</code>.</li><li>A Cursor credential for model turns. Sign in once:</li></ul><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></code></pre></div><p>You can also set <code>CURSOR_API_KEY</code> instead of signing in.</p><ul><li>Authenticate with <code>gh auth login</code> or <code>GITHUB_TOKEN</code>. You can read public pull requests. Posting reviews requires repository write access.</li></ul><h2 id="create-and-run-the-project" tabindex="-1">Create and run the project <a class="header-anchor" href="#create-and-run-the-project" aria-label="Permalink to &quot;Create and run the project&quot;">​</a></h2><p>Initialize the project and start the development server:</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;"> ./sdk-pr-reviewer</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sdk-pr-reviewer</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><p>Keep <code>agent-sdk dev</code> running. In a second terminal, run:</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;"> run</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;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p>Confirm the agent replies.</p><h2 id="add-review-instructions" tabindex="-1">Add review instructions <a class="header-anchor" href="#add-review-instructions" aria-label="Permalink to &quot;Add review instructions&quot;">​</a></h2><p>Replace <code>agent/instructions.md</code>:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR reviewer</span></span>
 <span class="line"></span>

package/dist/docs/assets/{reference_connections.md.DxldvyIB.js → reference_connections.md.Di6jJAXF.js}

@@ -8,7 +8,7 @@ import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.BCISBCiQ.js";const c
 <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;">});</span></span></code></pre></div><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:#6A737D;--shiki-dark:#6A737D;">           # browser PKCE → local mcp-auth.json</span></span>
 <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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # also upsert deployment secrets</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Hosted Connect retries this process. Self-hosted stays file-only.</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><p>Account MCP (<code>cursorAccount: true</code>) is the right choice for connectors already linked in the Cursor dashboard. Omit <code>servers</code> (or pass <code>&quot;*&quot;</code>) to forward every connected connector. If the model should call those tools by name on local turns, set <code>advertiseTools: true</code>.</p><h2 id="per-session-auth-auth" tabindex="-1">Per-session auth (<code>auth</code>) <a class="header-anchor" href="#per-session-auth-auth" aria-label="Permalink to &quot;Per-session auth (\`auth\`)&quot;">​</a></h2><p>For http/sse connections whose credential depends on <strong>who the session is for</strong> (a multi-tenant agent asserting the tenant it is acting for), declare an <code>auth</code> callback instead of static headers. It runs host-side at turn-build time with the session&#39;s <code>SessionInfo</code> and returns headers merged over the static ones:</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;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Hosted Connect retries this process. Self-hosted stays file-only.</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../skills/mcp-auth.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><p>Account MCP (<code>cursorAccount: true</code>) is the right choice for connectors already linked in the Cursor dashboard. Omit <code>servers</code> (or pass <code>&quot;*&quot;</code>) to forward every connected connector. If the model should call those tools by name on local turns, set <code>advertiseTools: true</code>.</p><h2 id="per-session-auth-auth" tabindex="-1">Per-session auth (<code>auth</code>) <a class="header-anchor" href="#per-session-auth-auth" aria-label="Permalink to &quot;Per-session auth (\`auth\`)&quot;">​</a></h2><p>For http/sse connections whose credential depends on <strong>who the session is for</strong> (a multi-tenant agent asserting the tenant it is acting for), declare an <code>auth</code> callback instead of static headers. It runs host-side at turn-build time with the session&#39;s <code>SessionInfo</code> and returns headers merged over the static ones:</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;"> 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://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> grantFor</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">(</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">)</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
@@ -18,7 +18,17 @@ import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</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;"> ({ headers: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tenantHeaders</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(session) }),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </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>A listing failure, invalid tool name, or name collision fails the turn. Advertised tools follow the same runtime support as server tools. They cannot be called through the direct tool API.</p><p>In a dry-run session, MCP tools marked read-only run normally. Tools marked as writes are stubbed. Tools without effect annotations are unavailable.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</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;"> defineConnection</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>A listing failure, invalid tool name, or name collision fails the turn. Advertised tools follow the same runtime support as server tools. They cannot be called through the direct tool API.</p><p>In a dry-run session, MCP tools marked read-only run normally. Tools marked as writes are stubbed. Tools without effect annotations are unavailable.</p><h2 id="restrict-which-tools-a-connection-serves" tabindex="-1">Restrict which tools a connection serves <a class="header-anchor" href="#restrict-which-tools-a-connection-serves" aria-label="Permalink to &quot;Restrict which tools a connection serves&quot;">​</a></h2><p>Use <code>tools</code> the same way you allowlist harness tools on the agent. When set, the connection serves only those names. Use <code>disallowedTools</code> to drop names instead. The two combine as deny-wins, same as the Cursor SDK. The model and <code>host.mcp</code> only see what remains. On a model-visible connection, set <code>advertiseTools: true</code> so the raw server is not attached.</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;"> 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;">  advertiseTools: </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;">  tools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search_skus&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;get_stock&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">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;">  advertiseTools: </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;">  disallowedTools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;place_order&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;delete_sku&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>Names are the server&#39;s <code>tools/list</code> names. Unknown names are omitted. A filter that matches nothing on the server fails the turn. Combine with <code>effects: &quot;read&quot;</code> to keep only the listed tools the server classifies as reads.</p><p>A list of names is an allowlist. An object of handlers authors TypeScript tools. On <code>host-connections/</code>, a name list restricts <code>host.mcp</code> without advertising.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</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;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--import&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;tsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp/units-server.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // env, cwd</span></span>
@@ -62,4 +72,4 @@ import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.BCISBCiQ.js";const c
 <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;"> host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {});</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result);</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></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</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="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, Connect, <code>--store</code></li><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,49)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</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="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, Connect, <code>--store</code></li><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,54)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_connections.md.DxldvyIB.lean.js → reference_connections.md.Di6jJAXF.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[n("",49)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
+import{_ as i,c as a,o as e,ag as n}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[n("",54)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_http-api.md.BEJx9XVj.js → reference_http-api.md.oySXBO8o.js}

@@ -2,7 +2,7 @@ import{_ as t,c as s,o,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON
 <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;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tools declaring <code>timeArgs</code> refuse calls not bounded at or before it. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</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;"> -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/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tool calls with relative, later-than-<code>asOf</code>, or omitted schema-declared time bounds are refused. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</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;"> -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/session/ses_…</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;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends.</p><p>Expect <code>409</code> on a stale token or a task session. Task sessions do not accept follow-ups. Expect <code>403</code> when the caller is not the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</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;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#which-events-can-i-stream">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="session-cost" tabindex="-1">Session cost <a class="header-anchor" href="#session-cost" aria-label="Permalink to &quot;Session cost&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/cost</code> returns the session&#39;s cost report: per-turn token usage and the engine&#39;s estimated cost, folded from <code>turn.completed</code> events. It runs the same owner check as the other session routes and returns <code>404</code> for an unknown session. The <a href="./cli.html#cost"><code>agent-sdk cost</code></a> command reports the same data.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#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/tools/inspect_pr</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>

package/dist/docs/assets/scaffolding-agents.md.em43xlY1.js

@@ -0,0 +1 @@
+import{_ as o,c as a,o as t,ag as l}from"./chunks/framework.BCISBCiQ.js";const f=JSON.parse('{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent.","frontmatter":{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent."},"headers":[],"relativePath":"scaffolding-agents.md","filePath":"scaffolding-agents.md"}'),s={name:"scaffolding-agents.md"};function i(r,e,n,d,c,h){return t(),a("div",null,[...e[0]||(e[0]=[l('<h1 id="scaffold-an-agent-with-cursor" tabindex="-1">Scaffold an agent with Cursor <a class="header-anchor" href="#scaffold-an-agent-with-cursor" aria-label="Permalink to &quot;Scaffold an agent with Cursor&quot;">​</a></h1><p>Turn an idea into a verified agent while Cursor guides you through each decision.</p><h2 id="what-does-the-create-agent-skill-do" tabindex="-1">What does the create-agent skill do? <a class="header-anchor" href="#what-does-the-create-agent-skill-do" aria-label="Permalink to &quot;What does the create-agent skill do?&quot;">​</a></h2><p>The bundled <a href="./skills/create-agent.html"><code>create-agent</code> skill</a> turns your goal into a small working project. Have Cursor read that file and follow it.</p><p>Where to find the file depends on how you got the package:</p><ul><li>Installing <code>@cursor/july</code> (<code>npm install</code>, <code>npx @cursor/july</code>, a version bump) copies every package skill into <code>~/.cursor/skills/agentsdk/</code> with <code>alwaysApply: true</code>, so Cursor injects the skill body into context instead of waiting for the model to pick it from the catalog. The <code>/</code> menu lists them as <code>/agentsdk-create-agent</code>, <code>/agentsdk-hillclimb</code>, and the rest. Re-installing overwrites those copies with the package version.</li><li>Installed <code>@cursor/july</code> as a dependency? The skill also ships inside the package at <code>node_modules/@cursor/july/skills/create-agent/SKILL.md</code>.</li><li>Working from this package&#39;s source? The skill is at <a href="./skills/create-agent.html"><code>skills/create-agent/SKILL.md</code></a>. Run <code>agent-sdk install-skills</code> if you want the same copies in <code>~/.cursor/skills/agentsdk/</code> (the package postinstall skips the source checkout).</li></ul><p>Cursor will:</p><ul><li>Ask only for choices missing from your prompt</li><li>Recommend defaults based on what you want to build</li><li>Show you the plan and file tree before writing files</li><li>Create the agent after you confirm the plan</li><li>Run structural checks, a real turn, and a smoke eval</li></ul><p>Use this skill for a new agent. Use <a href="./guides/convert-automation.html">convert-automation</a> when the starting point is a Cursor Automation in the dashboard. Use <a href="./hillclimbing.html"><code>hillclimb</code></a> (<code>skills/hillclimb/SKILL.md</code>) when an existing agent works but needs better results.</p><h2 id="how-do-i-start-a-guided-scaffold" tabindex="-1">How do I start a guided scaffold? <a class="header-anchor" href="#how-do-i-start-a-guided-scaffold" aria-label="Permalink to &quot;How do I start a guided scaffold?&quot;">​</a></h2><p>Describe the outcome and any constraints you already know:</p><blockquote><p>Build a local weather agent for the playground. Give it one tool for current conditions and add a smoke eval. Guide me through the remaining decisions.</p></blockquote><p>More detail means fewer questions. Include a channel, runtime, model, or required integration when those choices are fixed.</p><h2 id="which-choices-will-cursor-ask-me-to-make" tabindex="-1">Which choices will Cursor ask me to make? <a class="header-anchor" href="#which-choices-will-cursor-ask-me-to-make" aria-label="Permalink to &quot;Which choices will Cursor ask me to make?&quot;">​</a></h2><p>Cursor fills gaps in two short rounds:</p><ul><li><strong>Identity:</strong> purpose, project name, and location</li><li><strong>Runtime:</strong> local or cloud</li><li><strong>Model:</strong> the default model or another Cursor model</li><li><strong>Channels:</strong> playground and HTTP, Slack, GitHub, a webhook, or a schedule</li><li><strong>MCP connections:</strong> remote or local MCP servers</li><li><strong>Capabilities:</strong> tools, skills, subagents, hooks, seed files, approvals, and evals</li></ul><p>Questions adapt to your goal. A playground chat agent won&#39;t get cloud-repository questions. A local agent won&#39;t get cloud setup questions.</p><h2 id="what-happens-before-cursor-writes-files" tabindex="-1">What happens before Cursor writes files? <a class="header-anchor" href="#what-happens-before-cursor-writes-files" aria-label="Permalink to &quot;What happens before Cursor writes files?&quot;">​</a></h2><p>Cursor shows one plan with the choices it made and the folders it will create. Choose <strong>Scaffold it</strong> to continue or <strong>Adjust something</strong> to change the plan.</p><p>No files change before you approve this step.</p><h2 id="what-will-cursor-create" tabindex="-1">What will Cursor create? <a class="header-anchor" href="#what-will-cursor-create" aria-label="Permalink to &quot;What will Cursor create?&quot;">​</a></h2><p>A first version usually includes:</p><ul><li><code>AGENTS.md</code>, <code>.gitignore</code>, <code>package.json</code>, and <code>tsconfig.json</code></li><li><code>agent/agent.ts</code> for the model and runtime</li><li><code>agent/instructions.md</code> for the always-on prompt</li><li><code>agent/hooks/memory.ts</code> for memory guidance</li><li>One or two tools under <code>agent/tools/</code></li><li>Any channels or MCP connections you selected</li><li><code>evals/evals.config.ts</code> and one smoke eval</li></ul><p>Cursor keeps the first version small. Side-effecting server tools use <code>needsApproval</code>. Deterministic setup, such as fetching a pull request, stays in host code instead of model instructions.</p><p>See <a href="./reference/project-layout.html">Project layout</a> for every supported folder.</p><h2 id="how-does-cursor-verify-the-scaffold" tabindex="-1">How does Cursor verify the scaffold? <a class="header-anchor" href="#how-does-cursor-verify-the-scaffold" aria-label="Permalink to &quot;How does Cursor verify the scaffold?&quot;">​</a></h2><p>Cursor checks the project in this order:</p><ol><li>Run <code>agent-sdk validate</code> and fix every error</li><li>Inspect the discovered surface with <code>info --json</code></li><li>Call each server tool directly with validated sample input</li><li>Run one end-to-end model turn</li><li>Run the smoke eval</li><li>Run the project&#39;s TypeScript check</li></ol><p>Validation, discovery, direct server-tool calls, and server startup work without a Cursor credential. Model turns and evals need <code>CURSOR_API_KEY</code> or a saved <code>agent-sdk login</code>.</p><h2 id="what-happens-after-the-first-agent-works" tabindex="-1">What happens after the first agent works? <a class="header-anchor" href="#what-happens-after-the-first-agent-works" aria-label="Permalink to &quot;What happens after the first agent works?&quot;">​</a></h2><p>Choose one to three fixed inputs, define what should improve, and name what must stay unchanged. Then have Cursor follow <a href="./skills/hillclimb.html"><code>skills/hillclimb/SKILL.md</code></a>.</p><p>The hillclimb skill measures a baseline, changes one lever, runs the same inputs again, and adds an eval for each improvement you keep.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Build your first PR reviewer</a></li><li><a href="./guides/convert-automation.html">Convert a Cursor Automation</a></li><li><a href="./building-with-agents.html">Building agents with agents</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/project-layout.html">Project layout</a></li></ul>',34)])])}const p=o(s,[["render",i]]);export{f as __pageData,p as default};

package/dist/docs/assets/skills_ab.md.CsFNatVx.js

@@ -0,0 +1,26 @@
+import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.BCISBCiQ.js";const o=JSON.parse('{"title":"Agent SDK A/B metrics (defineAB)","description":"Author defineAB live A/B metrics under agent/ab. Sticky variants and onSample on live runs. Not a test runner. Use when comparing variants on traffic; use defineEval for regression gates.","frontmatter":{"name":"agentsdk-ab","description":"Author defineAB live A/B metrics under agent/ab. Sticky variants and onSample on live runs. Not a test runner. Use when comparing variants on traffic; use defineEval for regression gates."},"headers":[],"relativePath":"../skills/ab/SKILL.md","filePath":"../skills/ab/SKILL.md"}'),e={name:"../skills/ab/SKILL.md"};function l(p,s,h,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="agent-sdk-a-b-metrics-defineab" tabindex="-1">Agent SDK A/B metrics (<code>defineAB</code>) <a class="header-anchor" href="#agent-sdk-a-b-metrics-defineab" aria-label="Permalink to &quot;Agent SDK A/B metrics (\`defineAB\`)&quot;">​</a></h1><p>Live metrics plug-in. No <code>agent-sdk ab</code> CLI. No assertion API. Reference: <code>docs/ab.md</code>.</p><table tabindex="0"><thead><tr><th></th><th><code>defineEval</code></th><th><code>defineAB</code></th></tr></thead><tbody><tr><td>Job</td><td>Gates on frozen fixtures</td><td>Metrics on live runs</td></tr><tr><td>Location</td><td><code>evals/**/*.eval.ts</code></td><td><code>agent/ab.ts</code> or <code>agent/ab/&lt;name&gt;.ts</code></td></tr><tr><td>How it runs</td><td><code>agent-sdk eval</code></td><td>Under <code>serve</code> / <code>run</code></td></tr></tbody></table><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;"> { defineAB, splitBySessionHash } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/ab&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;"> defineAB</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;concise-instructions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  variants: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    control: { label: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Baseline&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    treatment: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      label: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Shorter&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      instructions: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Keep replies to one short paragraph.&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:#24292E;--shiki-dark:#E1E4E8;">  split: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">splitBySessionHash</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ holdout: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  derive: {</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    weatherCalls</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      event.type </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;action.result&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &amp;&amp;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.toolName </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;get_weather&quot;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        ?</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        :</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onSample</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">sample</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(sample.variant, sample.metrics.toolCalls, sample.metrics.wallTimeMs);</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:#24292E;--shiki-dark:#E1E4E8;">async </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(input, ctx) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.abs?.[</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;concise-instructions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;treatment&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // treatment-specific behavior</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>Enrollment is at session creation. Eval sessions skip it. Do not use <code>splitIf</code> to filter evals. Split helpers and <code>onSample</code> fields: <code>docs/ab.md</code>.</p><p>Pick a name, arm labels, a split, and a real <code>onSample</code> sink. Do not invent credentials.</p>`,7)])])}const c=i(e,[["render",l]]);export{o as __pageData,c as default};

package/dist/docs/assets/skills_ab.md.CsFNatVx.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,ag as t}from"./chunks/framework.BCISBCiQ.js";const o=JSON.parse('{"title":"Agent SDK A/B metrics (defineAB)","description":"Author defineAB live A/B metrics under agent/ab. Sticky variants and onSample on live runs. Not a test runner. Use when comparing variants on traffic; use defineEval for regression gates.","frontmatter":{"name":"agentsdk-ab","description":"Author defineAB live A/B metrics under agent/ab. Sticky variants and onSample on live runs. Not a test runner. Use when comparing variants on traffic; use defineEval for regression gates."},"headers":[],"relativePath":"../skills/ab/SKILL.md","filePath":"../skills/ab/SKILL.md"}'),e={name:"../skills/ab/SKILL.md"};function l(p,s,h,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[t("",7)])])}const c=i(e,[["render",l]]);export{o as __pageData,c as default};

package/dist/docs/assets/skills_create-agent.md.BVoWPcan.js

@@ -0,0 +1,8 @@
+import{_ as t,c as s,o as i,ag as a}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Create an Agent SDK agent","description":"Scaffold a new Agent SDK agent: short AskQuestion interview, then verify a turn and hand off to hillclimb. Use when creating a new agent. Ask only what the invoking message left open.","frontmatter":{"name":"agentsdk-create-agent","description":"Scaffold a new Agent SDK agent: short AskQuestion interview, then verify a turn and hand off to hillclimb. Use when creating a new agent. Ask only what the invoking message left open."},"headers":[],"relativePath":"../skills/create-agent/SKILL.md","filePath":"../skills/create-agent/SKILL.md"}'),o={name:"../skills/create-agent/SKILL.md"};function n(d,e,l,h,r,c){return i(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="create-an-agent-sdk-agent" tabindex="-1">Create an Agent SDK agent <a class="header-anchor" href="#create-an-agent-sdk-agent" aria-label="Permalink to &quot;Create an Agent SDK agent&quot;">​</a></h1><ol><li><strong>Interview.</strong> Two <code>AskQuestion</code> rounds, then a plan gate.</li><li><strong>Scaffold.</strong> <code>agent-sdk init</code>, then shape the files.</li><li><strong>Verify.</strong> <code>validate</code> / <code>info</code> / <code>call</code>, then a model turn.</li><li><strong>Channels.</strong> Slack, GitHub, webhook, or schedule as chosen.</li><li><strong>Hillclimb.</strong> <code>skills/hillclimb/SKILL.md</code>.</li></ol><p>Read <code>skills/framework-map/SKILL.md</code> if you have not. CLI is <code>agent-sdk</code>. Public docs: <code>node_modules/@cursor/july/dist/docs/llms.txt</code> or <code>/docs/llms.txt</code> on a running host.</p><h2 id="interview" tabindex="-1">Interview <a class="header-anchor" href="#interview" aria-label="Permalink to &quot;Interview&quot;">​</a></h2><p><code>AskQuestion</code>: batched, recommended option first and labeled <code>(recommended)</code>.</p><ul><li>Mine the invoking message. Target: two rounds, then files.</li><li>Round 1 is identity. Round 2 is the surface, tailored by round 1.</li><li>Multi-select for channels, MCP, capabilities. Other where a custom answer is plausible.</li><li>Ask decisions, not how to build it. File layout, tool names, env prefix, and eval shape are yours.</li><li>If <code>AskQuestion</code> is missing or the user skips, state defaults in one list and proceed.</li></ul><h3 id="round-1-identity" tabindex="-1">Round 1: identity <a class="header-anchor" href="#round-1-identity" aria-label="Permalink to &quot;Round 1: identity&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Question</th><th>Options</th></tr></thead><tbody><tr><td><strong>Purpose</strong></td><td>chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other</td></tr><tr><td><strong>Name</strong></td><td>2–3 slugs from the purpose + Other. Directory: <code>[A-Za-z0-9][A-Za-z0-9_-]*</code>, not <code>v1</code>/<code>playground</code>/<code>docs</code></td></tr><tr><td><strong>Location</strong></td><td><code>./&lt;slug&gt;</code> (default) · another directory</td></tr></tbody></table><h3 id="round-2-surface" tabindex="-1">Round 2: surface <a class="header-anchor" href="#round-2-surface" aria-label="Permalink to &quot;Round 2: surface&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Question</th><th>Options</th><th>Guidance</th></tr></thead><tbody><tr><td><strong>Runtime</strong></td><td><code>local</code> (default) · <code>cloud</code></td><td>Cloud needs <code>cloud.repos</code>. Approvals and sandbox seeds are local only. Recommend local unless the job needs a cloud checkout.</td></tr><tr><td><strong>Model</strong></td><td><code>grok-4.5</code> + <code>effort=high</code>, <code>fast=true</code> · Other id</td><td>Params, not id suffixes: <code>{ id: &quot;grok-4.5&quot;, params: [{ id: &quot;effort&quot;, value: &quot;high&quot; }, { id: &quot;fast&quot;, value: &quot;true&quot; }] }</code></td></tr><tr><td><strong>Channels</strong> (multi)</td><td>playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule</td><td>Slack: <code>skills/setup-slack/SKILL.md</code>. GitHub: <code>skills/github/SKILL.md</code>. No Discord/Teams pack; offer custom webhook.</td></tr><tr><td><strong>MCP</strong> (multi)</td><td>none · remote URL · local stdio · Cursor account connectors · Other</td><td>One file under <code>agent/mcp-connections/</code>. Account file is <code>account.ts</code>, never <code>cursor.ts</code>. Named local tools need <code>advertiseTools: true</code>. Privileged servers go in <code>agent/host-connections/</code>.</td></tr><tr><td><strong>Capabilities</strong> (multi)</td><td>server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend)</td><td>Always recommend one smoke eval.</td></tr></tbody></table><p>Close with the plan and file tree, then &quot;Scaffold it&quot; / &quot;Adjust something&quot;. Write files only after approval.</p><h2 id="fill-the-blanks" tabindex="-1">Fill the blanks <a class="header-anchor" href="#fill-the-blanks" aria-label="Permalink to &quot;Fill the blanks&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Purpose</th><th>Shape</th></tr></thead><tbody><tr><td>Slack chat</td><td><code>slackChannel({ envPrefix })</code> + suggested prompts. <code>agent-sdk slack create</code> mints the bot. Prefix: <code>skills/setup-slack/SKILL.md</code></td></tr><tr><td>PR review with host prep</td><td>Channel <code>callTool</code> into a trimmed workspace <code>pr/</code> tree</td></tr><tr><td>GitHub automation</td><td><code>githubChannel()</code> hooks, replay fixtures</td></tr><tr><td>Domain assistant</td><td>Server tools + one MCP connection + a skill</td></tr><tr><td>Wrap an existing pipeline</td><td>GitHub <code>{ task }</code> over a thin <code>agent/lib/</code> loop</td></tr></tbody></table><p>Defaults:</p><ul><li>Instructions + 1–2 tools + chosen channels + one smoke eval.</li><li><code>local.cwd</code> stays outside a monorepo checkout (default: a cache directory under <code>~/.cache</code>) unless the agent must inherit that tree.</li><li><code>agent/instructions.md</code>: identity, when to use which tool, output shape.</li><li>One tool per file. Prefer <code>execution: &quot;server&quot;</code> + zod <code>inputSchema</code>. Gate side effects with <code>needsApproval: true</code>.</li><li>Long prompts: <code>prompt\\</code>…\`<code>/</code>prompt.lines\`…\`<code>from</code>@cursor/july\`.</li><li>Host prep is for evidence (<code>callTool</code>, <code>workspaceFiles</code>), not judgment, formatting, or replies.</li></ul><h3 id="deterministic-path-budget" tabindex="-1">Deterministic-path budget <a class="header-anchor" href="#deterministic-path-budget" aria-label="Permalink to &quot;Deterministic-path budget&quot;">​</a></h3><p>Default to instructions and skills. Promote to TypeScript only when it earns the left column:</p><table tabindex="0"><thead><tr><th>Code owns</th><th>Model owns</th></tr></thead><tbody><tr><td>Side-effect gates (approve, deploy, post)</td><td>Human-facing output to a stated shape</td></tr><tr><td>Dedupe of external writes</td><td>Summarizing, classifying, wording</td></tr><tr><td>Auth and signature checks</td><td>What to do next from ground truth</td></tr><tr><td>Evidence seeding</td><td>Soft-failure retries</td></tr><tr><td>Hard API caps</td><td>Formatting under those caps</td></tr></tbody></table><p>Smells: prose builders in <code>.ts</code> (write <code>.md</code>); <code>agent/lib/</code> + <code>tools/</code> dwarfing instructions + skills on a first cut.</p><h2 id="scaffold" tabindex="-1">Scaffold <a class="header-anchor" href="#scaffold" aria-label="Permalink to &quot;Scaffold&quot;">​</a></h2><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;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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></code></pre></div><p><code>init</code> writes the project, runs <code>npm install</code>, and may wait on <code>login</code>. Then shape it:</p><ol><li><code>defineAgent</code> with the chosen model/runtime. Add <code>cloud: { repos: [...] }</code> for cloud.</li><li>Real <code>instructions.md</code>. Replace <code>echo.ts</code>.</li><li>Chosen <code>channels/</code>, <code>mcp-connections/</code>, <code>skills/</code>, <code>subagents/&lt;id&gt;/</code> (needs <code>description</code>), <code>schedules/</code>, <code>hooks/</code>. Slack: <code>agent-sdk slack create --dir ./&lt;slug&gt; --name &quot;&lt;Name&gt;&quot;</code>, not a hand-written channel. Manual Slack app: <code>agent-sdk slack init --manual</code> (Slack CLI, or paste at api.slack.com).</li><li><code>evals/evals.config.ts</code> with <code>maxConcurrency: 20</code> (required; cap 200) plus <code>evals/**/*.eval.ts</code>. Assert <code>t.succeeded()</code> + <code>t.calledTool(...)</code>. API: <code>skills/evals/SKILL.md</code>.</li></ol><p>Stay on deps the Agent SDK already ships (<code>zod</code>, <code>@modelcontextprotocol/sdk</code>, <code>tsx</code>).</p><h2 id="verify" tabindex="-1">Verify <a class="header-anchor" href="#verify" aria-label="Permalink to &quot;Verify&quot;">​</a></h2><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 style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">too</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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:#005CC5;--shiki-dark:#79B8FF;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{…}&#39;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsc</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --noEmit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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></code></pre></div><p>tsx does not typecheck. Tool <code>execute</code> must return JSON-shaped values: object literals or <code>type</code> aliases, not <code>interface</code> types.</p><p>Model turns need <code>CURSOR_API_KEY</code>. Without one, finish the key-free checks, confirm <code>run</code> fails with only the API-key error, and hand these over:</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;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;fixture prompt&gt;&quot;</span></span>
+<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:#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:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> single</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># http://127.0.0.1:3000/playground</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</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></code></pre></div><p>Serve only this agent&#39;s directory. Session files land in the project state directory (<code>--state-root</code>). That is not harness cwd.</p><h2 id="channel-setup" tabindex="-1">Channel setup <a class="header-anchor" href="#channel-setup" aria-label="Permalink to &quot;Channel setup&quot;">​</a></h2><ul><li><strong>Slack.</strong> <code>skills/setup-slack/SKILL.md</code></li><li><strong>GitHub.</strong> <code>skills/github/SKILL.md</code></li><li><strong>Custom webhook.</strong> <code>POST /v1/channels/&lt;id&gt;/&lt;route&gt;</code>. Loopback-only until you add <code>bearerAuth(...)</code>.</li><li><strong>Schedules.</strong> Never auto-fire under <code>--dev</code>. <code>POST /v1/dev/schedules/&lt;id&gt;</code>.</li></ul><h2 id="hillclimb-handoff" tabindex="-1">Hillclimb handoff <a class="header-anchor" href="#hillclimb-handoff" aria-label="Permalink to &quot;Hillclimb handoff&quot;">​</a></h2><p>Once a smoke turn passes, agree fixtures, success criteria, and a freeze line, then follow <code>skills/hillclimb/SKILL.md</code>. Seed from the smoke session under the project state directory. GitHub: snapshot <code>agent-sdk github replay ... --dry-run --out fixtures/github</code>.</p><p>Do not deploy or post to real Slack/GitHub beyond the smoke the user asked for. If the plan grows past ~10 files, cut scope. Re-check the budget at hand-off.</p>`,35)])])}const g=t(o,[["render",n]]);export{k as __pageData,g as default};

package/dist/docs/assets/skills_create-agent.md.BVoWPcan.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as s,o as i,ag as a}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Create an Agent SDK agent","description":"Scaffold a new Agent SDK agent: short AskQuestion interview, then verify a turn and hand off to hillclimb. Use when creating a new agent. Ask only what the invoking message left open.","frontmatter":{"name":"agentsdk-create-agent","description":"Scaffold a new Agent SDK agent: short AskQuestion interview, then verify a turn and hand off to hillclimb. Use when creating a new agent. Ask only what the invoking message left open."},"headers":[],"relativePath":"../skills/create-agent/SKILL.md","filePath":"../skills/create-agent/SKILL.md"}'),o={name:"../skills/create-agent/SKILL.md"};function n(d,e,l,h,r,c){return i(),s("div",null,[...e[0]||(e[0]=[a("",35)])])}const g=t(o,[["render",n]]);export{k as __pageData,g as default};

package/dist/docs/assets/skills_debug.md.CDbPhHfg.js

@@ -0,0 +1 @@
+import{_ as t,c as d,o,ag as r}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Debugging the Agent SDK locally","description":"Diagnose a misbehaving local Agent SDK agent: blank playground, missing sessions, failed reads, webhook 401s, 403/409, lost approvals. Use when a project runs but behaves wrong locally.","frontmatter":{"name":"agentsdk-debug","description":"Diagnose a misbehaving local Agent SDK agent: blank playground, missing sessions, failed reads, webhook 401s, 403/409, lost approvals. Use when a project runs but behaves wrong locally."},"headers":[],"relativePath":"../skills/debug/SKILL.md","filePath":"../skills/debug/SKILL.md"}'),s={name:"../skills/debug/SKILL.md"};function c(a,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r('<h1 id="debugging-the-agent-sdk-locally" tabindex="-1">Debugging the Agent SDK locally <a class="header-anchor" href="#debugging-the-agent-sdk-locally" aria-label="Permalink to &quot;Debugging the Agent SDK locally&quot;">​</a></h1><p>Local <code>agent-sdk serve</code>. Hosted start or health failures: <code>docs/troubleshooting.md</code> and <code>docs/deployment.md</code>.</p><ol><li><strong>Validate.</strong> <code>agent-sdk validate --dir &lt;project&gt;</code></li><li><strong>Info.</strong> <code>curl -s http://127.0.0.1:3000/&lt;slug&gt;/v1/info | jq .</code></li><li><strong>Trace.</strong> Session events under the project state directory. Then match the table.</li></ol><table tabindex="0"><thead><tr><th>Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>Playground blank / &quot;no agents&quot;</td><td>Start <code>serve</code>. A built SPA with no backend serves nothing.</td></tr><tr><td>Playground UI edits do not show</td><td>Open the URL <code>serve --dev</code> prints as <code>playground</code>, not <code>:3000</code>.</td></tr><tr><td>Sessions on disk, empty playground list</td><td>List is the calling principal. <code>--dev</code> or <code>--allow-anonymous</code> shows all. Or <code>?sessionId=ses_...</code>.</td></tr><tr><td>Built-in read/grep fail; retry loops</td><td>Bun. Rerun under Node. The tell is <code>NGHTTP2_FRAME_SIZE_ERROR</code>.</td></tr><tr><td><code>github forward</code> 401s; hook created</td><td>Blank <code>GITHUB_TOKEN</code>/<code>GH_TOKEN</code>. Relay uses <code>gh</code> login.</td></tr><tr><td><code>Hook already exists</code></td><td>One forwarder per repo. <code>forward --dir &lt;parent&gt;</code>.</td></tr><tr><td>Answers cite ancestor <code>AGENTS.md</code></td><td>Nested checkout. Default <code>local.cwd</code> is a cache directory under <code>~/.cache</code>.</td></tr><tr><td>Model lists IDE <code>cursor</code> tools, never MCP</td><td><code>advertiseTools: true</code>. Check <code>GET /v1/info</code>.</td></tr><tr><td>Port 3000 in use</td><td><code>lsof -iTCP:3000 -sTCP:LISTEN</code> and kill that pid.</td></tr><tr><td>Approval vanished after restart</td><td>Parked calls do not survive restart. Re-run.</td></tr><tr><td>Schedule / reminder silent under <code>--dev</code></td><td>Dev never auto-fires. <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code>.</td></tr><tr><td><code>409</code> on follow-up</td><td>Stale <code>continuationToken</code>, busy session, or a task session.</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>Wait, or drop <code>--session</code>.</td></tr><tr><td><code>403</code> on stream</td><td>Wrong principal. Same auth as create; beyond loopback send <code>--bearer-token</code>.</td></tr><tr><td>Works on loopback, blocked via tunnel</td><td><code>localDevStrict()</code> rejects forwarded headers. Use <code>--bearer-token</code>. Never <code>--allow-anonymous</code> with account MCP.</td></tr><tr><td>Slack <code>channel idle … missing credentials</code></td><td>Expected. <code>slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td>Immediate API-key error</td><td>Model turns need <code>CURSOR_API_KEY</code>.</td></tr><tr><td>Approvals or sandbox seeds missing</td><td><code>runtime: &quot;cloud&quot;</code>. Those are local only. <code>validate</code> warns.</td></tr><tr><td><code>validate</code> clean, CI typecheck fails</td><td>tsx skipped types. JSON-shaped returns; <code>type</code> not <code>interface</code>.</td></tr></tbody></table><p>Count <code>action.result</code> by <code>toolName</code> before blaming latency. <code>turn.failed</code> + <code>&quot;turn interrupted&quot;</code> is a follow-up or stop, not a crash. <code>agent-sdk trajectory --events &lt;file&gt;</code> renders a saved trace.</p>',5)])])}const h=t(s,[["render",c]]);export{p as __pageData,h as default};

package/dist/docs/assets/skills_debug.md.CDbPhHfg.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as d,o,ag as r}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Debugging the Agent SDK locally","description":"Diagnose a misbehaving local Agent SDK agent: blank playground, missing sessions, failed reads, webhook 401s, 403/409, lost approvals. Use when a project runs but behaves wrong locally.","frontmatter":{"name":"agentsdk-debug","description":"Diagnose a misbehaving local Agent SDK agent: blank playground, missing sessions, failed reads, webhook 401s, 403/409, lost approvals. Use when a project runs but behaves wrong locally."},"headers":[],"relativePath":"../skills/debug/SKILL.md","filePath":"../skills/debug/SKILL.md"}'),s={name:"../skills/debug/SKILL.md"};function c(a,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r("",5)])])}const h=t(s,[["render",c]]);export{p as __pageData,h as default};