@cursor/july 0.1.111 → 0.1.113

package/dist/docs/assets/guides_opentelemetry.md.BKDxQmmd.js

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

package/dist/docs/assets/guides_opentelemetry.md.BKDxQmmd.lean.js

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

package/dist/docs/assets/guides_slack.md.Bo96y42E.js

@@ -0,0 +1,70 @@
+import{_ as a,c as i,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),t={name:"guides/slack.md"};function l(h,s,p,k,o,r){return n(),i("div",null,[...s[0]||(s[0]=[e(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;">​</a></h1><p>A Slack agent wakes when someone mentions it, sends it a DM, or posts in a channel it watches. From there, it keeps the conversation in one thread and can reply all at once, stream the answer live, or decide for itself when to post updates.</p><p>Run <code>agent-sdk slack create --dir .</code>, then <code>agent-sdk slack doctor</code>.</p><h2 id="answer-a-mention-or-dm" tabindex="-1">Answer a mention or DM <a class="header-anchor" href="#answer-a-mention-or-dm" aria-label="Permalink to &quot;Answer a mention or DM&quot;">​</a></h2><p>Mention the bot in a channel or send it a DM, and it will answer in a thread on that message. Any follow-up in the same thread continues the conversation where it left off.</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/slack.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/slack&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // TRIAGE_SLACK_BOT_TOKEN and TRIAGE_SLACK_APP_TOKEN</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TRIAGE&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="post-one-reply-with-a-status-chip" tabindex="-1">Post one reply with a status chip <a class="header-anchor" href="#post-one-reply-with-a-status-chip" aria-label="Permalink to &quot;Post one reply with a status chip&quot;">​</a></h2><p>By default, Slack shows a status chip beneath the thread while the turn runs, cycling through idle messages until reasoning or tool activity gives it something more specific to show. When the turn finishes, the chip disappears and one complete reply lands in the thread.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;post&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    status: {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // First line of each reasoning block on the chip.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      reasoning: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // Tool names as they start (&quot;Running grep, glob...&quot;).</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      tools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      idle: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Checking the monorepo...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Poking Datadog...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="stream-a-live-reply" tabindex="-1">Stream a live reply <a class="header-anchor" href="#stream-a-live-reply" aria-label="Permalink to &quot;Stream a live reply&quot;">​</a></h2><p>In stream mode, the reply appears immediately and grows as the model writes. Slack shows its generic &quot;is working...&quot; state until the stream ends, while optional reasoning and tool cards keep progress inside the same message.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stream&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // Thinking card inside the streamed message.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    reasoningCard: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // One card per tool in that same message.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    toolCards: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="let-the-agent-own-every-message" tabindex="-1">Let the agent own every message <a class="header-anchor" href="#let-the-agent-own-every-message" aria-label="Permalink to &quot;Let the agent own every message&quot;">​</a></h2><p>Use agentic mode when the agent should decide how to communicate, not only what to say. The bot reacts to the parent message with eyes and shows a thinking chip, then the agent chooses when to post progress and how to deliver the final reply.</p><p><code>slack-communication</code> gives those posts a Slack-aware voice by default: lead with the result, share progress when the picture changes, and keep tool chatter off the thread. Use <code>tone</code> for the rest of the communication contract, including voice, level of detail, formatting, and how updates should be structured.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/slack.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> slackCommunication </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions/slack-communication&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackCommunication</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tone:</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;Be concise but warm. Use bullets for evidence and end with the next action.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // \`post-update\` writes mid-turn progress and the final reply.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agentic&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="wake-on-a-channel-post" tabindex="-1">Wake on a channel post <a class="header-anchor" href="#wake-on-a-channel-post" aria-label="Permalink to &quot;Wake on a channel post&quot;">​</a></h2><p>This example watches <code>#triage-alerts</code>, so any substantial top-level message starts a thread even when nobody mentions the bot. The length guard filters out short posts before they can start a turn.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  engagement: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channelPosts: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;#triage-alerts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      posts: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;top-level&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      debounceMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">15_000</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:#6F42C1;--shiki-dark:#B392F0;">  onChannelPost</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (message.markdown.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // \`{}\` starts a model turn as the sender.</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:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>When you create the app, pass <code>--channel-posts</code> and invite the bot to every channel in the allowlist.</p><h2 id="control-who-can-message" tabindex="-1">Control who can message <a class="header-anchor" href="#control-who-can-message" aria-label="Permalink to &quot;Control who can message&quot;">​</a></h2><p>By default, people outside your workspace get no reply. This matters most in Slack Connect channels, where external collaborators share the channel and can mention or reply to bots installed by your organization. Keeping <code>blockExternals</code> on prevents them from starting or steering an agent session and, through it, directing any tools available to the agent.</p><p>Set <code>blockExternals: false</code> only when external collaborators are intended users of the agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Let external collaborators start and continue agent sessions.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { blockExternals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Anyone in a thread can continue its session by default. If the conversation should stay between the agent and its original author, set <code>respondTo: &quot;author&quot;</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { respondTo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;author&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>Mentions and DMs wake the agent automatically, while <code>onChannelPost</code> runs for messages in watched channels. Declare <code>onAppMention</code> or <code>onDirectMessage</code> when you need to filter those default wakes; each handler returns <code>{}</code> to start a turn or <code>null</code> to skip it.</p><p>For example, this handler only starts a turn for DMs prefixed with <code>triage:</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:#6F42C1;--shiki-dark:#B392F0;">onDirectMessage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message.markdown.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;triage:&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // \`{}\` starts a model turn as the sender.</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></code></pre></div><h2 id="thread-affinity" tabindex="-1">Thread affinity <a class="header-anchor" href="#thread-affinity" aria-label="Permalink to &quot;Thread affinity&quot;">​</a></h2><p>A Slack thread maps to one agent session, so every follow-up in that thread resumes the same conversation.</p><h2 id="call-slack-from-deterministic-code-via-ctx" tabindex="-1">Call Slack from deterministic code via <code>ctx</code> <a class="header-anchor" href="#call-slack-from-deterministic-code-via-ctx" aria-label="Permalink to &quot;Call Slack from deterministic code via \`ctx\`&quot;">​</a></h2><p>Channel hooks can post before starting the model turn, which is useful for deterministic acknowledgements such as <code>Looking at this now.</code> The same bot credential also lets tools call Slack later in the turn:</p><ul><li><p>Channel hooks: <code>ctx.thread.post()</code>, <code>ctx.slack.channelId</code>, <code>ctx.slack.threadTs</code></p></li><li><p>Tools: <code>ctx.host.slack.getClient()</code></p></li></ul><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onAppMention</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (message.markdown.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">trim</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;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.thread.</span><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;Looking at this now.&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></code></pre></div><p>Use the IDs on the hook <code>ctx</code> when handling an event, and <code>ctx.host.slack.getClient()</code> when a tool needs the Slack Web API.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to &quot;Connect&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span></code></pre></div><p>After you sign in, <code>slack create</code> opens <strong>Add Slack to this agent</strong> in the browser and writes the resulting tokens to <code>.env.local</code> without printing them. You can open the same wizard from <strong>Integrations</strong> on <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>If you already own the Slack app, initialize it with <code>agent-sdk slack init --manual --dir . --name &quot;Triage&quot;</code> and follow the <a href="./../../skills/setup-slack/SKILL.html">Slack setup skill</a> for installation and tokens.</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 <code>doctor</code> first to catch missing credentials, then start the agent and send it the same mention or DM a teammate would.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;">​</a></h2><ul><li><p>If the tokens are missing, the Slack channel stays idle while the rest of <code>serve</code> starts normally.</p></li><li><p>Keep <code>channelPosts.allow</code> narrow because each qualifying post can start a model turn.</p></li><li><p>Set <code>envPrefix</code> when two Slack bots share a host so the token names do not collide.</p></li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../reference/cli.html#slack">CLI reference</a>: <code>slack create</code>, <code>doctor</code>, <code>init --manual</code></li><li><a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>: the companion skill for coding agents</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: host prep on mention and DM handlers</li><li><a href="./../evals.html">Evals</a>: freeze a mention as a regression check</li></ul>`,49)])])}const E=a(t,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/guides_slack.md.Bo96y42E.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as i,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),t={name:"guides/slack.md"};function l(h,s,p,k,o,r){return n(),i("div",null,[...s[0]||(s[0]=[e("",49)])])}const E=a(t,[["render",l]]);export{c as __pageData,E as default};

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};