@cursor/july 0.1.111 → 0.1.112

package/dist/docs/assets/guides_webhooks.md.1A72_VEE.js

@@ -0,0 +1,92 @@
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Receive provider events, keep one conversation per domain object, and deliver agent replies back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Receive provider events, keep one conversation per domain object, and deliver agent replies back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function h(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="webhook-agents" tabindex="-1">Webhook agents <a class="header-anchor" href="#webhook-agents" aria-label="Permalink to &quot;Webhook agents&quot;">​</a></h1><p>A custom channel turns an event from another system into an agent conversation, then sends the result back to the system that started it. Use one when the built-in <a href="./../reference/http-api.html">HTTP API</a> does not match the provider&#39;s payload, conversation key, or reply path.</p><p>Author <code>agent/channels/&lt;id&gt;.ts</code>. Its routes mount under <code>/&lt;slug&gt;/v1/channels/&lt;id&gt;</code>.</p><h2 id="receive-a-webhook-and-send-the-answer-back" tabindex="-1">Receive a webhook and send the answer back <a class="header-anchor" href="#receive-a-webhook-and-send-the-answer-back" aria-label="Permalink to &quot;Receive a webhook and send the answer back&quot;">​</a></h2><p>When a ticket system sends a new message, this endpoint responds with <code>202 Accepted</code> right away. The agent keeps working after the HTTP request ends, and its completed answer appears as a comment on the ticket.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/channels/tickets.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { postTicketComment } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/tickets.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> TicketState</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">  ticketId</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<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;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">TicketState</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  state: { ticketId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes: [</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/ticket&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Answer a new ticket message&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      bodySchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        ticketId: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        message: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</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;">      handler</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;">_request</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">body</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:#6F42C1;--shiki-dark:#B392F0;">        waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">          send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(body.message, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            state: { ticketId: body.ticketId },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Ticket \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          })</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        );</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ accepted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;message.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">channel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.data.finishReason </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;tool_call&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.text </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> postTicketComment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(channel.state.ticketId, event.data.text);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>postTicketComment</code> is a small wrapper around the ticket provider&#39;s SDK. Keeping that write in the event handler means the webhook request does not stay open while the model works.</p><h2 id="keep-one-conversation-per-ticket" tabindex="-1">Keep one conversation per ticket <a class="header-anchor" href="#keep-one-conversation-per-ticket" aria-label="Permalink to &quot;Keep one conversation per ticket&quot;">​</a></h2><p>Without a conversation key, every delivery creates a new session. Add the ticket ID as the <code>continuationToken</code> so the opening message and all later comments resume the same conversation, while a different ticket starts its own.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(body.message, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`ticket:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    state: { ticketId: body.ticketId },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Ticket \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  })</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>The channel owns this key. Callers only need to send the domain ID they already know.</p><h2 id="prepare-evidence-before-the-turn" tabindex="-1">Prepare evidence before the turn <a class="header-anchor" href="#prepare-evidence-before-the-turn" aria-label="Permalink to &quot;Prepare evidence before the turn&quot;">​</a></h2><p>Webhook payloads often contain little more than an object ID. This handler fetches the full ticket through a deterministic tool and writes the result to <code>ticket.json</code>, so the model begins with a stable snapshot instead of spending the turn looking for context.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">handler</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;">_request</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prepared</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</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;prepare_ticket&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ticketId: body.ticketId,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  });</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (prepared.isError) {</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;">(</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      { error: prepared.errorMessage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Could not prepare ticket&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 style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">502</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>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Read ticket.json, then draft the reply.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`ticket:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      state: { ticketId: body.ticketId },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      workspaceFiles: {</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">        &quot;ticket.json&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stringify</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(prepared.result, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</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;null&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>
+<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;">({ accepted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</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 same <code>message.completed</code> handler from the first example delivers the answer back to the ticket.</p><h2 id="routes-receive-events-deliver" tabindex="-1">Routes receive, events deliver <a class="header-anchor" href="#routes-receive-events-deliver" aria-label="Permalink to &quot;Routes receive, events deliver&quot;">​</a></h2><p>Routes own inbound HTTP. A route validates the request, decides whether to start or resume a turn, and responds to the caller. The channel&#39;s <code>events</code> handlers receive session events later, which is where you deliver the model&#39;s answer or report a failure to the originating system.</p><h2 id="validate-payloads-with-zod" tabindex="-1">Validate payloads with Zod <a class="header-anchor" href="#validate-payloads-with-zod" aria-label="Permalink to &quot;Validate payloads with Zod&quot;">​</a></h2><p><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> routes require a Zod <code>bodySchema</code>; <code>GET</code> requires a <code>querySchema</code>. Validation runs before the handler, and the parsed value arrives as typed <code>body</code> or <code>query</code>. Use <code>z.unknown()</code> when the provider controls a variable payload and your own parser will narrow it.</p><p>The route description and schema also appear in <code>GET /v1/info</code>. The playground uses them to add a <strong>Try</strong> action and a matching slash command, so you can exercise the same handler without building a separate test UI.</p><h2 id="use-handler-context" tabindex="-1">Use handler context <a class="header-anchor" href="#use-handler-context" aria-label="Permalink to &quot;Use handler context&quot;">​</a></h2><p>The handler context keeps deterministic setup and model work in one route:</p><ul><li><p><code>send</code> starts or resumes the agent conversation.</p></li><li><p><code>callTool</code> runs an authored server tool without starting a model turn.</p></li><li><p><code>waitUntil</code> keeps background work alive after the HTTP response. Await <code>send</code> when the caller needs the session handle, then call <code>session.waitForCompletion()</code> if it also needs the turn outcome.</p></li><li><p><code>host</code> provides authenticated services for API calls made by channel code.</p></li></ul><p>The full handler API lives in the <a href="./../reference/channels.html#handler-arguments">Channels reference</a>.</p><h2 id="protect-public-webhooks" tabindex="-1">Protect public webhooks <a class="header-anchor" href="#protect-public-webhooks" aria-label="Permalink to &quot;Protect public webhooks&quot;">​</a></h2><p>Custom routes accept direct loopback requests by default. They reject forwarded requests, so a tunnel or reverse proxy does not silently turn a local development endpoint into a public one.</p><p>Before accepting remote traffic, choose an explicit boundary. <code>bearerAuth()</code> works when the sender can attach an authorization header. On managed hosting, webhook providers often cannot attach the agent alias token, so <code>publicEndpoint()</code> lets that custom channel bypass it. That opens the route to every caller; verify the provider signature before starting a turn or calling a tool.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST, publicEndpoint } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { verifyProviderSignature } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/tickets.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  auth: [</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">publicEndpoint</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes: [</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Signed ticket webhook&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      bodySchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">unknown</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      handler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> request</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> rawBody</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;"> request.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> signature</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> request.headers.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;x-provider-signature&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">verifyProviderSignature</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rawBody, signature)) {</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;">({ ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">401</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        }</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">        // Parse and dispatch only after the signature passes.</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;">({ ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
+<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>publicEndpoint()</code> only opens this channel&#39;s routes. The built-in session and tool APIs stay private. See <a href="./../reference/channels.html#auth-policies">Auth policies</a> for bearer tokens and the complete policy reference.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><p>Run the agent in development mode, then replay the same payload the provider will send. The response should return immediately, and the resulting session should appear in the playground while the reply is delivered.</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>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -sS</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:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/channels/tickets/ticket</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;ticketId&quot;:&quot;ENG-142&quot;,&quot;message&quot;:&quot;CSV export returns 500&quot;}&#39;</span></span></code></pre></div><p>Keep representative payloads under <code>fixtures/</code> and pass them with <code>--data-binary @fixtures/&lt;event&gt;.json</code>. You can also open the route&#39;s <strong>Try</strong> action in the playground for manual probes.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../reference/channels.html">Channels reference</a>: route methods, handler arguments, events, state, and auth policies</li><li><a href="./../templates/triage.html">Triage Linear or Jira issues</a>: a complete signed tracker webhook with reply delivery</li><li><a href="./../reference/http-api.html">HTTP API</a>: built-in session, follow-up, stream, and tool routes</li><li><a href="./../deployment.html#use-the-hosted-agent">Deployment</a>: stable hosted URLs and alias-token behavior</li><li><a href="./../evals.html">Evals</a>: turn saved payloads into regression fixtures</li></ul>`,35)])])}const c=i(t,[["render",h]]);export{o as __pageData,c as default};

package/dist/docs/assets/guides_webhooks.md.1A72_VEE.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Webhooks & custom channels","description":"Receive provider events, keep one conversation per domain object, and deliver agent replies back out.","frontmatter":{"title":"Webhooks & custom channels","description":"Receive provider events, keep one conversation per domain object, and deliver agent replies back out."},"headers":[],"relativePath":"guides/webhooks.md","filePath":"guides/webhooks.md"}'),t={name:"guides/webhooks.md"};function h(l,s,p,k,r,d){return n(),a("div",null,[...s[0]||(s[0]=[e("",35)])])}const c=i(t,[["render",h]]);export{o as __pageData,c as default};

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

@@ -0,0 +1,7 @@
+import{_ as a,c as i,o as t,a3 as s}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval.","frontmatter":{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval."},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),n={name:"hillclimbing.md"};function o(l,e,r,h,c,p){return t(),i("div",null,[...e[0]||(e[0]=[s(`<h1 id="hillclimbing" tabindex="-1">Hillclimbing <a class="header-anchor" href="#hillclimbing" aria-label="Permalink to &quot;Hillclimbing&quot;">​</a></h1><p>Hillclimbing improves an agent through controlled before-and-after comparisons. Keep the inputs fixed, name one failure, change one lever, and retain the change only when the same run gets better without crossing the freeze line.</p><p>The companion <a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code> skill</a> can run this loop with you.</p><h2 id="correct-a-wrong-tool-choice" tabindex="-1">Correct a wrong tool choice <a class="header-anchor" href="#correct-a-wrong-tool-choice" aria-label="Permalink to &quot;Correct a wrong tool choice&quot;">​</a></h2><p>Suppose a PR reviewer calls <code>approve_pr</code> before <code>inspect_pr</code>. Pin one PR fixture, record the original tool order, then tighten the instruction that owns the decision. The improved run should inspect first and leave approval untouched.</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;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is https://github.com/acme/checkout/pull/42 ready?&quot;</span></span></code></pre></div><p>Lock the result with the intended and tempting-wrong paths:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notCalledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approve_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Do not change the tool implementation, prompt, and evidence together. If tool choice improves, you should know which edit caused it.</p><h2 id="reduce-wandering-or-latency" tabindex="-1">Reduce wandering or latency <a class="header-anchor" href="#reduce-wandering-or-latency" aria-label="Permalink to &quot;Reduce wandering or latency&quot;">​</a></h2><p>A slow run often repeats reads, searches broad directories, or asks the model to discover evidence the host already has. Compare the trajectory by tool name and wall time, then move deterministic preparation ahead of the turn or trim the evidence shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>before: 14 tool calls, 92 seconds, 6 repeated reads</span></span>
+<span class="line"><span>after:   5 tool calls, 31 seconds, 0 repeated reads</span></span></code></pre></div><p>Keep the change only if the answer still finds the same known issue. Efficiency without a quality check can make an agent fast by making it incomplete.</p><h2 id="improve-quality-without-changing-the-contract" tabindex="-1">Improve quality without changing the contract <a class="header-anchor" href="#improve-quality-without-changing-the-contract" aria-label="Permalink to &quot;Improve quality without changing the contract&quot;">​</a></h2><p>For answer quality, freeze the public shape before editing: required sections, API fields, side effects, and existing evals. Compare both runs against a known-good answer or a small set of gold findings, then change the instructions or skill that owns the missing judgment.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>fixture: saved checkout PR diff</span></span>
+<span class="line"><span>success: report both gold findings with file paths</span></span>
+<span class="line"><span>freeze:  findings JSON shape; no review post; existing smoke evals</span></span></code></pre></div><p>A wording change is not a win by itself. Keep it when correctness rises and every frozen behavior remains intact.</p><h2 id="run-one-measured-round" tabindex="-1">Run one measured round <a class="header-anchor" href="#run-one-measured-round" aria-label="Permalink to &quot;Run one measured round&quot;">​</a></h2><p>Agree on four inputs before editing:</p><ol><li><strong>Target:</strong> the agent path or slug.</li><li><strong>Fixtures:</strong> one to three prompts, saved payloads, or pinned PRs.</li><li><strong>Success:</strong> the metric or decision that should improve.</li><li><strong>Freeze line:</strong> behavior that must not move.</li></ol><p>Then run one loop:</p><ol><li>Exercise the agent through the same surface a user would.</li><li>Read the trajectory and name the dominant failure in one sentence.</li><li>Change one lever.</li><li>Rerun the same fixtures.</li><li>Compare correctness, efficiency, and contract fit.</li><li>Keep, revert, or narrow the change.</li></ol><p>Do not replace a fixture mid-round. A moving input makes the comparison meaningless.</p><h2 id="choose-the-smallest-lever" tabindex="-1">Choose the smallest lever <a class="header-anchor" href="#choose-the-smallest-lever" aria-label="Permalink to &quot;Choose the smallest lever&quot;">​</a></h2><p>Start with the earliest place that can remove the failure:</p><ol><li><strong>Host preparation:</strong> fetch deterministic evidence before the turn.</li><li><strong>Evidence shape:</strong> trim, order, or label what the model receives.</li><li><strong>Instructions or skills:</strong> clarify the decision procedure.</li><li><strong>Tool surface:</strong> remove or gate tools that invite wandering.</li><li><strong>Framework:</strong> change it only when the agent cannot express the fix.</li></ol><p>Changing the host or evidence often improves both quality and latency because the model spends less time searching for ground truth.</p><h2 id="lock-every-kept-win" tabindex="-1">Lock every kept win <a class="header-anchor" href="#lock-every-kept-win" aria-label="Permalink to &quot;Lock every kept win&quot;">​</a></h2><p>Each retained change needs an eval that would have failed before it. Use a tool-choice assertion, <code>maxToolCalls</code> bound, output-shape check, or quality score that captures the measured improvement.</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;"> 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:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span></span></code></pre></div><p>Never weaken an existing gate to make the round pass. The eval is the record that the improvement survived after the fixture and source change leave your working memory.</p><h2 id="run-the-loop-with-a-coding-agent" tabindex="-1">Run the loop with a coding agent <a class="header-anchor" href="#run-the-loop-with-a-coding-agent" aria-label="Permalink to &quot;Run the loop with a coding agent&quot;">​</a></h2><p>Ask the coding agent to read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>, then give it the target, fixtures, success criterion, and freeze line. It will measure the current run, propose one change, remeasure, and ask before starting another round.</p><p>Use saved or local surfaces during a climb. Do not deploy or post to a real external channel unless that side effect is part of an explicitly approved fixture.</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="./evals.html">Evals</a>: author the regression check for a kept win</li><li><a href="./reference/evals.html">Evals reference</a>: trajectory assertions and scores</li><li><a href="./building-with-agents.html">Building agents with agents</a>: delegate creation and verification to a coding agent</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: diagnose a run that is broken instead of underperforming</li></ul>`,36)])])}const u=a(n,[["render",o]]);export{g as __pageData,u as default};

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

@@ -0,0 +1 @@
+import{_ as a,c as i,o as t,a3 as s}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval.","frontmatter":{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval."},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),n={name:"hillclimbing.md"};function o(l,e,r,h,c,p){return t(),i("div",null,[...e[0]||(e[0]=[s("",36)])])}const u=a(n,[["render",o]]);export{g as __pageData,u as default};

package/dist/docs/assets/{index.md.BFVyY2KT.js → index.md.C-t81M5J.js}

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

package/dist/docs/assets/{index.md.BFVyY2KT.lean.js → index.md.C-t81M5J.lean.js}

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

package/dist/docs/assets/{quickstart.md.D3MjSZN-.js → quickstart.md.DAvVhuuU.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.dypDpWZ3.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a 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,k,e,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="build-a-pr-reviewer" tabindex="-1">Build a PR reviewer <a class="header-anchor" href="#build-a-pr-reviewer" aria-label="Permalink to &quot;Build a 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.</p><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.</li><li>agent-sdk cli</li></ul><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npm install -g @cursor/agent-sdk</span></span></code></pre></div><ul><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><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/agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-reviewer</span></span>
+import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a 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,k,e,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h(`<h1 id="build-a-pr-reviewer" tabindex="-1">Build a PR reviewer <a class="header-anchor" href="#build-a-pr-reviewer" aria-label="Permalink to &quot;Build a 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.</p><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.</li><li>agent-sdk cli</li></ul><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npm install -g @cursor/agent-sdk</span></span></code></pre></div><ul><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><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/agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./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;"> 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/{quickstart.md.D3MjSZN-.lean.js → quickstart.md.DAvVhuuU.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.dypDpWZ3.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a 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,k,e,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",47)])])}const y=i(t,[["render",l]]);export{g as __pageData,y as default};
+import{_ as i,c as a,o as n,a3 as h}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a 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,k,e,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",47)])])}const y=i(t,[["render",l]]);export{g as __pageData,y as default};

package/dist/docs/assets/{reference_agent-config.md.CfVA-LZJ.js → reference_agent-config.md.DGPyw7ms.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (\`agent/agent.ts\`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root 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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (\`agent/agent.ts\`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root 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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  model: {</span></span>

package/dist/docs/assets/{reference_agent-config.md.CfVA-LZJ.lean.js → reference_agent-config.md.DGPyw7ms.lean.js}

@@ -1 +1 @@
-import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a("",50)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a("",50)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_artifacts.md.Vf7qyIZ-.js → reference_artifacts.md.Bu_4HmsD.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP.","frontmatter":{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."},"headers":[],"relativePath":"reference/artifacts.md","filePath":"reference/artifacts.md"}'),n={name:"reference/artifacts.md"};function d(o,s,r,l,h,p){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="artifacts" tabindex="-1">Artifacts <a class="header-anchor" href="#artifacts" aria-label="Permalink to &quot;Artifacts&quot;">​</a></h1><p>An artifact marks a durable output the agent produced: a reviewed PR URL, a generated report, a decision record. Sessions come and go; artifacts persist across them, capped and listable, so the people supervising an agent see what it shipped without replaying event streams.</p><h2 id="declare-kinds" tabindex="-1">Declare kinds <a class="header-anchor" href="#declare-kinds" aria-label="Permalink to &quot;Declare kinds&quot;">​</a></h2><p>Author <code>agent/artifacts.ts</code> with <code>defineArtifacts</code> from <code>@cursor/july/artifacts</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;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP.","frontmatter":{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."},"headers":[],"relativePath":"reference/artifacts.md","filePath":"reference/artifacts.md"}'),n={name:"reference/artifacts.md"};function d(o,s,r,l,h,p){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="artifacts" tabindex="-1">Artifacts <a class="header-anchor" href="#artifacts" aria-label="Permalink to &quot;Artifacts&quot;">​</a></h1><p>An artifact marks a durable output the agent produced: a reviewed PR URL, a generated report, a decision record. Sessions come and go; artifacts persist across them, capped and listable, so the people supervising an agent see what it shipped without replaying event streams.</p><h2 id="declare-kinds" tabindex="-1">Declare kinds <a class="header-anchor" href="#declare-kinds" aria-label="Permalink to &quot;Declare kinds&quot;">​</a></h2><p>Author <code>agent/artifacts.ts</code> with <code>defineArtifacts</code> from <code>@cursor/july/artifacts</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;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineArtifacts } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/artifacts&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;"> defineArtifacts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{reference_artifacts.md.Vf7qyIZ-.lean.js → reference_artifacts.md.Bu_4HmsD.lean.js}

@@ -1 +1 @@
-import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP.","frontmatter":{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."},"headers":[],"relativePath":"reference/artifacts.md","filePath":"reference/artifacts.md"}'),n={name:"reference/artifacts.md"};function d(o,s,r,l,h,p){return i(),e("div",null,[...s[0]||(s[0]=[t("",23)])])}const g=a(n,[["render",d]]);export{k as __pageData,g as default};
+import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP.","frontmatter":{"title":"Artifacts","description":"Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."},"headers":[],"relativePath":"reference/artifacts.md","filePath":"reference/artifacts.md"}'),n={name:"reference/artifacts.md"};function d(o,s,r,l,h,p){return i(),e("div",null,[...s[0]||(s[0]=[t("",23)])])}const g=a(n,[["render",d]]);export{k as __pageData,g as default};

package/dist/docs/assets/{reference_channels.md.icqLKcTc.js → reference_channels.md.nFWbzAic.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function o(h,e,l,r,d,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="channels" tabindex="-1">Channels <a class="header-anchor" href="#channels" aria-label="Permalink to &quot;Channels&quot;">​</a></h1><p>A channel is the surface an agent lives on. The built-in HTTP session channel is always mounted. Custom channels declare their own routes under <code>/v1/channels/&lt;id&gt;</code>. The Slack and GitHub packs are prebuilt channels with platform transports. GitLab and Bitbucket packs cover their hosted and self-managed products. This page is the authoring reference; for the walkthrough, see the <a href="./../guides/webhooks.html">Webhooks guide</a>.</p><h2 id="built-in-http-channel" tabindex="-1">Built-in HTTP channel <a class="header-anchor" href="#built-in-http-channel" aria-label="Permalink to &quot;Built-in HTTP channel&quot;">​</a></h2><p>It&#39;s always mounted, under <code>/&lt;slug&gt;</code> in the default multi-agent layout: session create, follow-up, stream, stop, the sessions list, approvals, deterministic tool calls, health, and info. For the route-by-route contract, see the <a href="./http-api.html">HTTP API reference</a>.</p><h2 id="define-a-custom-channel" tabindex="-1">Define a custom channel <a class="header-anchor" href="#define-a-custom-channel" aria-label="Permalink to &quot;Define a custom channel&quot;">​</a></h2><p>Author <code>agent/channels/&lt;id&gt;.ts</code>. The filename is the channel id and the route prefix:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function o(h,e,l,r,d,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="channels" tabindex="-1">Channels <a class="header-anchor" href="#channels" aria-label="Permalink to &quot;Channels&quot;">​</a></h1><p>A channel is the surface an agent lives on. The built-in HTTP session channel is always mounted. Custom channels declare their own routes under <code>/v1/channels/&lt;id&gt;</code>. The Slack and GitHub packs are prebuilt channels with platform transports. GitLab and Bitbucket packs cover their hosted and self-managed products. This page is the authoring reference; for the walkthrough, see the <a href="./../guides/webhooks.html">Webhooks guide</a>.</p><h2 id="built-in-http-channel" tabindex="-1">Built-in HTTP channel <a class="header-anchor" href="#built-in-http-channel" aria-label="Permalink to &quot;Built-in HTTP channel&quot;">​</a></h2><p>It&#39;s always mounted, under <code>/&lt;slug&gt;</code> in the default multi-agent layout: session create, follow-up, stream, stop, the sessions list, approvals, deterministic tool calls, health, and info. For the route-by-route contract, see the <a href="./http-api.html">HTTP API reference</a>.</p><h2 id="define-a-custom-channel" tabindex="-1">Define a custom channel <a class="header-anchor" href="#define-a-custom-channel" aria-label="Permalink to &quot;Define a custom channel&quot;">​</a></h2><p>Author <code>agent/channels/&lt;id&gt;.ts</code>. The filename is the channel id and the route prefix:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{reference_channels.md.icqLKcTc.lean.js → reference_channels.md.nFWbzAic.lean.js}

@@ -1 +1 @@
-import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function o(h,e,l,r,d,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",43)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function o(h,e,l,r,d,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",43)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_cli.md.B2dBL6L8.js → reference_cli.md.DLWDz9ij.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs one command, <code>agent-sdk</code>; <code>npx @cursor/july &lt;cmd&gt;</code> runs it. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved event stream</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh coding-agent skills (<code>npm install</code> already copies them)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#delete"><code>delete</code></a></td><td>Delete a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
+import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs one command, <code>agent-sdk</code>; <code>npx @cursor/july &lt;cmd&gt;</code> runs it. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved event stream</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh coding-agent skills (<code>npm install</code> already copies them)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#delete"><code>delete</code></a></td><td>Delete a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--mode multi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">single] [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key</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;">                  [--state-root </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --allow-anonymous]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--allow-anonymous-cursor-github]</span></span>
@@ -47,6 +47,8 @@ import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c
 <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;"> ./code-wiki</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> code-wiki</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # keep wiki pages current after merge</span></span>
 <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;"> ./agents-md</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agents-md</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # keep AGENTS.md current from last week&#39;s PRs and Slack</span></span>
 <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;"> ./my-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> security-reviewer</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # review PRs for security bugs</span></span>
+<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;"> ./thermo-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-review</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # review PRs for bugs and breakage</span></span>
+<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;"> ./thermo-quality</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-quality-review</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # review PRs for code quality</span></span>
 <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;"> ./security-help</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> security-help</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # answer security questions in Slack</span></span>
 <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;"> ./my-triage</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-linear</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # comment on Linear issues</span></span>
 <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;"> ./my-triage</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-jira</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # comment on Jira issues</span></span>

package/dist/docs/assets/{reference_cli.md.B2dBL6L8.lean.js → reference_cli.md.DLWDz9ij.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",197)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",197)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_connections.md.Cb3U_c8n.js → reference_connections.md.CmyrlXfY.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.dypDpWZ3.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(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><p>Put a server in <code>agent/host-connections/</code> when host tools should call it and the model should not. Same <code>defineConnection</code> shape. <code>agent-sdk mcp oauth</code> still works. The playground and the turn&#39;s MCP servers never see those files.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</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;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.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(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><p>Put a server in <code>agent/host-connections/</code> when host tools should call it and the model should not. Same <code>defineConnection</code> shape. <code>agent-sdk mcp oauth</code> still works. The playground and the turn&#39;s MCP servers never see those files.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</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;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.linear.app/mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>

package/dist/docs/assets/{reference_connections.md.Cb3U_c8n.lean.js → reference_connections.md.CmyrlXfY.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.dypDpWZ3.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};
+import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.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};