@cursor/july 0.1.90 → 0.1.91

package/dist/docs/assets/{example-agents_slack-agent.md.06jQXTAI.lean.js → example-agents_slack-agent.md.D7Kdj5BV.lean.js}

@@ -1 +1 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel.","frontmatter":{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel."},"headers":[],"relativePath":"example-agents/slack-agent.md","filePath":"example-agents/slack-agent.md"}'),i={name:"example-agents/slack-agent.md"};function l(o,e,h,r,d,c){return s(),t("div",null,[...e[0]||(e[0]=[n("",42)])])}const g=a(i,[["render",l]]);export{k as __pageData,g as default};
+import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel.","frontmatter":{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel."},"headers":[],"relativePath":"example-agents/slack-agent.md","filePath":"example-agents/slack-agent.md"}'),i={name:"example-agents/slack-agent.md"};function l(o,e,h,r,d,c){return s(),t("div",null,[...e[0]||(e[0]=[n("",42)])])}const g=a(i,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/{example-agents_weather-agent.md.DC3lINjo.js → example-agents_weather-agent.md.lVEAbWFf.js}

@@ -1,13 +1,13 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function o(h,e,l,r,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="explore-the-full-agent-sdk-surface-with-a-weather-agent" tabindex="-1">Explore the full Agent SDK surface with a weather agent <a class="header-anchor" href="#explore-the-full-agent-sdk-surface-with-a-weather-agent" aria-label="Permalink to &quot;Explore the full Agent SDK surface with a weather agent&quot;">​</a></h1><p>The weather agent is the broadest small example in the repository. It fetches live conditions and forecasts, converts units through MCP, writes notes in a session workspace, and pauses an alert tool for human approval. The same agent also runs from HTTP, Slack, a schedule, and the MCP endpoint.</p><p>Use this project when you want to see how the Agent SDK&#39;s filesystem pieces fit together before you design a larger agent.</p><p><a href="./../../examples/weather-agent/">Browse the weather agent source.</a></p><h2 id="see-the-runtime-features-together" tabindex="-1">See the runtime features together <a class="header-anchor" href="#see-the-runtime-features-together" aria-label="Permalink to &quot;See the runtime features together&quot;">​</a></h2><p>Most examples focus on one architecture. Weather agent puts the major runtime features side by side:</p><table tabindex="0"><thead><tr><th>Capability</th><th>Source</th><th>Role</th></tr></thead><tbody><tr><td>Root config and instructions</td><td><a href="../../examples/weather-agent/agent/agent.ts"><code>agent/agent.ts</code></a>, <a href="./../../examples/weather-agent/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Select the cloud runtime and route each request.</td></tr><tr><td>Server tools</td><td><a href="./../../examples/weather-agent/agent/tools/"><code>agent/tools/</code></a></td><td>Execute on the Agent SDK host through authenticated HTTP MCP, fetch Open-Meteo data, call MCP, and model an approval-gated action.</td></tr><tr><td>Agent tool</td><td><a href="../../examples/weather-agent/agent/tools/save_weather_note.ts"><code>save_weather_note.ts</code></a></td><td>Run a Python script inside the session workspace.</td></tr><tr><td>Stdio MCP</td><td><a href="../../examples/weather-agent/agent/mcp-connections/units.ts"><code>units.ts</code></a>, <a href="../../examples/weather-agent/agent/mcp-connections/probe.ts"><code>probe.ts</code></a></td><td>Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript <code>execute</code> functions.</td></tr><tr><td>Custom HTTP</td><td><a href="../../examples/weather-agent/agent/channels/webhook.ts"><code>webhook.ts</code></a></td><td>Start a turn or call MCP without a model turn.</td></tr><tr><td>Slack</td><td><a href="../../examples/weather-agent/agent/channels/slack.ts"><code>slack.ts</code></a>, <a href="../../examples/weather-agent/agent/channels/slack-app.ts"><code>slack-app.ts</code></a></td><td>Compare account-linked chat with a dedicated app offering approval buttons.</td></tr><tr><td>Skill and subagent</td><td><a href="./../../examples/weather-agent/agent/skills/forecast.html"><code>forecast.md</code></a>, <a href="./../../examples/weather-agent/agent/subagents/researcher/"><code>researcher/</code></a></td><td>Load a procedure on demand or delegate broad research.</td></tr><tr><td>Schedule and hook</td><td><a href="./../../examples/weather-agent/agent/schedules/heartbeat.html"><code>heartbeat.md</code></a>, <a href="../../examples/weather-agent/agent/hooks/audit.ts"><code>audit.ts</code></a></td><td>Start recurring task sessions and observe completed turns.</td></tr><tr><td>A/B and evals</td><td><a href="../../examples/weather-agent/agent/ab.ts"><code>agent/ab.ts</code></a>, <a href="./../../examples/weather-agent/evals/"><code>evals/</code></a></td><td>Compare a sticky variant and protect tool routing with regression cases.</td></tr></tbody></table><h2 id="follow-one-request" tabindex="-1">Follow one request <a class="header-anchor" href="#follow-one-request" aria-label="Permalink to &quot;Follow one request&quot;">​</a></h2><p>A current-weather question takes this path:</p><ol><li>The built-in HTTP channel, Slack, or the custom <code>/report</code> route creates a durable session.</li><li><code>instructions.md</code> tells the model to call <code>get_weather</code> instead of guessing.</li><li>The server tool geocodes the city, fetches Open-Meteo, validates the response, and returns normalized fields.</li><li>The agent writes a short answer. The Agent SDK records every event in the session stream.</li><li>The audit hook observes <code>turn.completed</code>. If the session joined the A/B experiment, the collector updates its metrics too.</li></ol><p>Forecasts route to <code>get_forecast</code>. Unit conversions route to <code>convert_temperature</code>, which calls the <code>units</code> MCP server through <code>ctx.host.mcp</code>. Climate history and broad comparisons route to the <code>researcher</code> subagent.</p><h2 id="prepare-the-example" tabindex="-1">Prepare the example <a class="header-anchor" href="#prepare-the-example" aria-label="Permalink to &quot;Prepare the example&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential.</li><li>Network access to Open-Meteo.</li><li>Python 3 for <code>save_weather_note</code>.</li></ul><p>The project mounts an account-linked Slack channel. The Agent SDK checks the connection at startup, so sign in even when you plan to call a deterministic tool.</p><p>The optional approval-enabled Slack app also needs a token pair. <code>agent-sdk slack create --dir examples/weather-agent</code> provisions the app and writes the tokens for you (see the <a href="./../guides/slack.html#set-it-up">Slack guide</a>); with hand-minted tokens, export them instead:</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;"> WEATHER_AGENT_SLACK_BOT_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">xoxb-...</span></span>
+import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function h(o,e,l,r,d,p){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="explore-the-full-agent-sdk-surface-with-a-weather-agent" tabindex="-1">Explore the full Agent SDK surface with a weather agent <a class="header-anchor" href="#explore-the-full-agent-sdk-surface-with-a-weather-agent" aria-label="Permalink to &quot;Explore the full Agent SDK surface with a weather agent&quot;">​</a></h1><p>The weather agent is the broadest small example in the repository. It fetches live conditions and forecasts, converts units through MCP, writes notes in a session workspace, and runs from HTTP, Slack, a schedule, and the MCP endpoint.</p><p>Use this project when you want to see how the Agent SDK&#39;s filesystem pieces fit together before you design a larger agent.</p><p><a href="./../../examples/weather-agent/">Browse the weather agent source.</a></p><h2 id="see-the-runtime-features-together" tabindex="-1">See the runtime features together <a class="header-anchor" href="#see-the-runtime-features-together" aria-label="Permalink to &quot;See the runtime features together&quot;">​</a></h2><p>Most examples focus on one feature. Weather agent puts the major runtime features side by side:</p><table tabindex="0"><thead><tr><th>Capability</th><th>Source</th><th>Role</th></tr></thead><tbody><tr><td>Root config and instructions</td><td><a href="../../examples/weather-agent/agent/agent.ts"><code>agent/agent.ts</code></a>, <a href="./../../examples/weather-agent/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Select the cloud runtime and route each request.</td></tr><tr><td>Server tools</td><td><a href="./../../examples/weather-agent/agent/tools/"><code>agent/tools/</code></a></td><td>Fetch Open-Meteo data and call MCP from the serve host.</td></tr><tr><td>Agent tool</td><td><a href="../../examples/weather-agent/agent/tools/save_weather_note.ts"><code>save_weather_note.ts</code></a></td><td>Run a Python script inside the session workspace.</td></tr><tr><td>Stdio MCP</td><td><a href="../../examples/weather-agent/agent/mcp-connections/units.ts"><code>units.ts</code></a>, <a href="../../examples/weather-agent/agent/mcp-connections/probe.ts"><code>probe.ts</code></a></td><td>Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript <code>execute</code> functions.</td></tr><tr><td>Custom HTTP</td><td><a href="../../examples/weather-agent/agent/channels/webhook.ts"><code>webhook.ts</code></a></td><td>Start a turn or call MCP without a model turn.</td></tr><tr><td>Slack</td><td><a href="../../examples/weather-agent/agent/channels/slack.ts"><code>slack.ts</code></a>, <a href="../../examples/weather-agent/agent/channels/slack-app.ts"><code>slack-app.ts</code></a></td><td>Compare account-linked chat with a dedicated app.</td></tr><tr><td>Skill and subagent</td><td><a href="./../../examples/weather-agent/agent/skills/forecast.html"><code>forecast.md</code></a>, <a href="./../../examples/weather-agent/agent/subagents/researcher/"><code>researcher/</code></a></td><td>Load a procedure on demand or delegate broad research.</td></tr><tr><td>Schedule and hooks</td><td><a href="./../../examples/weather-agent/agent/schedules/heartbeat.html"><code>heartbeat.md</code></a>, <a href="../../examples/weather-agent/agent/hooks/audit.ts"><code>audit.ts</code></a>, <a href="../../examples/weather-agent/agent/hooks/journal.ts"><code>journal.ts</code></a></td><td>Start recurring tasks, log usage, and save turn summaries.</td></tr><tr><td>A/B and evals</td><td><a href="../../examples/weather-agent/agent/ab.ts"><code>agent/ab.ts</code></a>, <a href="./../../examples/weather-agent/evals/"><code>evals/</code></a></td><td>Compare a sticky variant and protect tool routing with regression cases.</td></tr></tbody></table><h2 id="follow-one-request" tabindex="-1">Follow one request <a class="header-anchor" href="#follow-one-request" aria-label="Permalink to &quot;Follow one request&quot;">​</a></h2><p>A current-weather question takes this path:</p><ol><li>The built-in HTTP channel, Slack, or the custom <code>/report</code> route creates a durable session.</li><li><code>instructions.md</code> tells the model to call <code>get_weather</code> instead of guessing.</li><li>The server tool geocodes the city, fetches Open-Meteo, validates the response, and returns normalized fields.</li><li>The agent writes a short answer. The Agent SDK records every event in the session stream.</li><li>The audit hook observes <code>turn.completed</code>. If the session joined the A/B experiment, the collector updates its metrics too.</li></ol><p>Forecasts route to <code>get_forecast</code>. Unit conversions route to <code>convert_temperature</code>, which calls the <code>units</code> MCP server through <code>ctx.host.mcp</code>. Climate history and broad comparisons route to the <code>researcher</code> subagent.</p><h2 id="prepare-the-example" tabindex="-1">Prepare the example <a class="header-anchor" href="#prepare-the-example" aria-label="Permalink to &quot;Prepare the example&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential.</li><li>Network access to Open-Meteo.</li><li>Python 3 for <code>save_weather_note</code>.</li></ul><p>The project mounts an account-linked Slack channel. The Agent SDK checks the connection at startup, so sign in even when you plan to call a deterministic tool.</p><p>The optional dedicated Slack app also needs a token pair. <code>agent-sdk slack create --dir examples/weather-agent</code> provisions the app and writes the tokens for you (see the <a href="./../guides/slack.html#set-it-up">Slack guide</a>); with hand-minted tokens, export them instead:</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;"> WEATHER_AGENT_SLACK_BOT_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">xoxb-...</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> WEATHER_AGENT_SLACK_APP_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">xapp-...</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;"> WEATHER_AGENT</span></span></code></pre></div><p>Without those two tokens, the dedicated channel stays idle. The account-linked channel still works.</p><h2 id="inspect-before-running" tabindex="-1">Inspect before running <a class="header-anchor" href="#inspect-before-running" aria-label="Permalink to &quot;Inspect before running&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-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;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p>The manifest should report eight tools, one skill, two MCP connections, one subagent, three authored channels, one schedule, one hook, and one A/B experiment. The eval listing should report eight cases.</p><h2 id="call-the-typed-tools" tabindex="-1">Call the typed tools <a class="header-anchor" href="#call-the-typed-tools" aria-label="Permalink to &quot;Call the typed tools&quot;">​</a></h2><p>Start with the current-weather server tool:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_weather</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p><code>validate</code> should pass. <code>info</code> and <code>eval --list</code> should match the capabilities described above.</p><h2 id="call-the-typed-tools" tabindex="-1">Call the typed tools <a class="header-anchor" href="#call-the-typed-tools" aria-label="Permalink to &quot;Call the typed tools&quot;">​</a></h2><p>Start with the current-weather server tool:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_weather</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;city&quot;:&quot;New York City&quot;}&#39;</span></span></code></pre></div><p><code>defineTool</code> gives the input a Zod schema. The Agent SDK validates the JSON before <code>execute</code> runs. The result includes the matched place, condition, temperature, humidity, wind, gusts, and precipitation.</p><p>Try the forecast:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_forecast</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;city&quot;:&quot;Lisbon&quot;,&quot;days&quot;:5}&#39;</span></span></code></pre></div><p>The tool accepts one to seven days. Shared Open-Meteo code lives under <code>agent/lib/</code>, so the Agent SDK imports it without discovering another tool.</p><h2 id="compare-server-and-agent-execution" tabindex="-1">Compare server and agent execution <a class="header-anchor" href="#compare-server-and-agent-execution" aria-label="Permalink to &quot;Compare server and agent execution&quot;">​</a></h2><p>Most weather tools use the default <code>execution: &quot;server&quot;</code>. Their TypeScript runs inside the serve host and can reach <code>ctx.host</code> services.</p><p><code>save_weather_note</code> uses <code>execution: &quot;agent&quot;</code> instead. The Agent SDK materializes its script into the agent environment. The script reads JSON from stdin and appends to <code>weather-notes.md</code> in that session&#39;s workspace:</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;"> examples/weather-agent</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;Save a note that Boston is cold and windy.&quot;</span></span></code></pre></div><p>Each session gets its own workspace. Saving a note doesn&#39;t edit the authored example.</p><p>This split matters on cloud. Server tools execute on the Agent SDK host through an authenticated HTTP MCP endpoint while retaining the active session context. For an agent tool, the Agent SDK includes its catalog and script body in the first prompt; the cloud model writes and invokes the script in its VM.</p><h2 id="verify-tool-execution-on-the-agent-vm" tabindex="-1">Verify tool execution on the agent VM <a class="header-anchor" href="#verify-tool-execution-on-the-agent-vm" aria-label="Permalink to &quot;Verify tool execution on the agent VM&quot;">​</a></h2><p>Ask the agent to call <code>probe_cloud_tool</code> on the <code>probe</code> MCP server. <code>agent/mcp-connections/probe.ts</code> authors that tool as TypeScript. The Agent SDK packages it as stdio MCP so a cloud VM with no checkout of this example can still run it. The model lists the server and calls the tool; it does not write a <code>.sh</code>.</p><p>A real call writes <code>vm-tool-observations/&lt;id&gt;.json</code> in the agent cwd and returns hostname, cwd, and pid. Stream events show <code>probe:probe_cloud_tool</code>, not <code>shell</code>.</p><p>A local <code>.agent-serve/tools/probe_cloud_tool.sh</code> or a marker under <code>probes/</code> means the model invented a substitute.</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;"> examples/weather-agent</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;Save a note that Boston is cold and windy.&quot;</span></span></code></pre></div><p>Each session gets its own workspace. Saving a note doesn&#39;t edit the authored example.</p><p>This split matters on cloud. Server tools stay on the Agent SDK host. Agent tools run inside the cloud workspace.</p><h2 id="verify-tool-execution-on-the-agent-vm" tabindex="-1">Verify tool execution on the agent VM <a class="header-anchor" href="#verify-tool-execution-on-the-agent-vm" aria-label="Permalink to &quot;Verify tool execution on the agent VM&quot;">​</a></h2><p>Ask the agent to call <code>probe_cloud_tool</code> on the <code>probe</code> MCP server. <code>agent/mcp-connections/probe.ts</code> authors that tool as TypeScript. The Agent SDK packages it as stdio MCP so a cloud VM with no checkout of this example can still run it. The model lists the server and calls the tool; it does not write a <code>.sh</code>.</p><p>A real call writes <code>vm-tool-observations/&lt;id&gt;.json</code> in the agent cwd and returns hostname, cwd, and pid. Stream events show <code>probe:probe_cloud_tool</code>, not <code>shell</code>.</p><p>A local <code>.agent-serve/tools/probe_cloud_tool.sh</code> or a marker under <code>probes/</code> means the model invented a substitute.</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;"> examples/weather-agent</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;Test custom tool execution from this cloud agent. Call probe_cloud_tool.&quot;</span></span></code></pre></div><h2 id="use-mcp-connections-in-three-places" tabindex="-1">Use MCP connections in three places <a class="header-anchor" href="#use-mcp-connections-in-three-places" aria-label="Permalink to &quot;Use MCP connections in three places&quot;">​</a></h2><p><code>agent/mcp-connections/units.ts</code> starts a local stdio server. The filename makes its server name <code>units</code>. The Agent SDK exposes it to:</p><ul><li>the model as MCP tools,</li><li>server tools through <code>ctx.host.mcp</code>, and</li><li>channel handlers through <code>host.mcp</code>.</li></ul><p><code>probe</code> is a second stdio connection. Its tools are TypeScript <code>execute</code> functions; the Agent SDK packages them so a cloud VM can spawn the server without this checkout. The model calls <code>probe_cloud_tool</code> directly; no host tool wraps it.</p><p><code>convert_temperature</code> demonstrates the server-tool path:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> convert_temperature</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;value&quot;:72,&quot;from&quot;:&quot;F&quot;}&#39;</span></span></code></pre></div><p>The custom channel demonstrates the handler path. Start the dev 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;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span></code></pre></div><p>Then call MCP deterministically through <code>/convert</code>:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
@@ -19,7 +19,7 @@ import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What is the weather in Paris?&quot;}&#39;</span></span></code></pre></div><p>The response includes a <code>key</code>. Send it back on the next request to continue the same session:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report</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;message&quot;:&quot;How about tomorrow?&quot;,&quot;key&quot;:&quot;&lt;key&gt;&quot;}&#39;</span></span></code></pre></div><p>This is the custom-channel version of a continuation token. See <a href="./../guides/webhooks.html">webhooks and custom channels</a> for route schemas, authentication, and asynchronous handlers.</p><h2 id="pause-a-tool-for-human-approval" tabindex="-1">Pause a tool for human approval <a class="header-anchor" href="#pause-a-tool-for-human-approval" aria-label="Permalink to &quot;Pause a tool for human approval&quot;">​</a></h2><p><code>post_weather_alert</code> sets <code>needsApproval: true</code>. Ask for an ops alert in the playground and the model&#39;s tool call parks before <code>execute</code>:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span></code></pre></div><p>Open the printed playground URL, ask:</p><blockquote><p>Alert ops that severe weather is approaching Boston.</p></blockquote><p>Approve or deny the call in the transcript. The dedicated Socket Mode Slack channel can show the same buttons when <code>toolApprovals: true</code> and Slack interactivity are configured.</p><p>The example tool returns a placeholder success object. It doesn&#39;t contact Slack, PagerDuty, or an ops board. Replace its <code>execute</code> body with your own sink before adapting it.</p><p>Use a model turn for this proof. A deterministic <code>agent-sdk call</code> runs the tool body directly and doesn&#39;t demonstrate the parked approval flow.</p><h2 id="load-procedures-and-delegate-research" tabindex="-1">Load procedures and delegate research <a class="header-anchor" href="#load-procedures-and-delegate-research" aria-label="Permalink to &quot;Load procedures and delegate research&quot;">​</a></h2><p>The forecast skill gives the root agent an on-demand procedure. The Agent SDK advertises the skill&#39;s description, then the harness loads its content when the request matches.</p><p>The <code>researcher</code> directory is an SDK subagent. Its description tells the parent when to delegate. It inherits the parent&#39;s execution surface, but gets its own instructions:</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;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;How about tomorrow?&quot;,&quot;key&quot;:&quot;&lt;key&gt;&quot;}&#39;</span></span></code></pre></div><p>This is the custom-channel version of a continuation token. See <a href="./../guides/webhooks.html">webhooks and custom channels</a> for route schemas, authentication, and asynchronous handlers.</p><h2 id="load-procedures-and-delegate-research" tabindex="-1">Load procedures and delegate research <a class="header-anchor" href="#load-procedures-and-delegate-research" aria-label="Permalink to &quot;Load procedures and delegate research&quot;">​</a></h2><p>The forecast skill gives the root agent an on-demand procedure. The Agent SDK advertises the skill&#39;s description, then the harness loads its content when the request matches.</p><p>The <code>researcher</code> directory is an SDK subagent. Its description tells the parent when to delegate. It inherits the parent&#39;s execution surface, but gets its own instructions:</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;"> examples/weather-agent</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;Compare record summer temperatures across Paris, London, and Rome.&quot;</span></span></code></pre></div><p>Use a skill when the same agent needs a procedure. Use a subagent when the parent should hand a bounded task to a specialist. The <a href="./../reference/subagents.html">subagents reference</a> explains the current inheritance limits.</p><h2 id="trigger-the-schedule-and-inspect-the-hook" tabindex="-1">Trigger the schedule and inspect the hook <a class="header-anchor" href="#trigger-the-schedule-and-inspect-the-hook" aria-label="Permalink to &quot;Trigger the schedule and inspect the hook&quot;">​</a></h2><p>The heartbeat schedule runs at 09:00 UTC on weekdays. Automatic schedule timers stay off under <code>--dev</code>, so dispatch it manually:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/dev/schedules/heartbeat</span></span></code></pre></div><p>It creates a task session to check San Francisco, New York, and London. The audit hook logs usage after each completed turn. Hooks observe recorded events; their failures don&#39;t fail the turn.</p><h2 id="measure-variants-and-regressions" tabindex="-1">Measure variants and regressions <a class="header-anchor" href="#measure-variants-and-regressions" aria-label="Permalink to &quot;Measure variants and regressions&quot;">​</a></h2><p>The <code>weather-tool-efficiency</code> A/B experiment assigns sessions by a sticky hash:</p><ul><li><code>control</code> returns current conditions in Fahrenheit.</li><li><code>treatment</code> adds a brief Celsius instruction and changes <code>get_weather</code> to return Celsius fields.</li></ul><p>Samples and aggregate snapshots persist under <code>.agent-serve/</code>. The treatment only changes current conditions; <code>get_forecast</code> still returns Fahrenheit. Treat the branch as an example of <code>ctx.session.abs</code>, not a complete unit policy.</p><p>List and run the evals:</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;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>Five cases cover current weather and forecasts against live Open-Meteo. Three more cover the local MCP converter, the workspace note tool, and the VM-side probe. Together they test model routing, external data, host MCP, agent-side execution, and stdio MCP in the agent environment.</p><h2 id="turn-the-weather-tour-into-your-own-agent" tabindex="-1">Turn the weather tour into your own agent <a class="header-anchor" href="#turn-the-weather-tour-into-your-own-agent" aria-label="Permalink to &quot;Turn the weather tour into your own agent&quot;">​</a></h2><p>Keep the architecture and replace the domain:</p><ul><li>Swap Open-Meteo tools for your typed service clients.</li><li>Keep deterministic transforms behind direct server tools or MCP.</li><li>Use an agent tool only when code must run in the agent workspace.</li><li>Gate side effects with <code>needsApproval</code>.</li><li>Put reusable procedures in skills and narrow specialist work into subagents.</li><li>Add a channel only when the external surface needs its own identity, continuation key, or delivery behavior.</li></ul><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/connections.html">MCP connections</a></li><li><a href="./../guides/human-in-the-loop.html">Human-in-the-loop approvals</a></li><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/schedules.html">Schedules and reminders</a></li><li><a href="./../evals.html">Evals</a></li><li><a href="./../ab.html">Live A/B metrics</a></li></ul>`,85)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
+<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;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The suite covers weather and forecast routing, the local converter, workspace notes, and the VM-side probe.</p><h2 id="turn-the-weather-tour-into-your-own-agent" tabindex="-1">Turn the weather tour into your own agent <a class="header-anchor" href="#turn-the-weather-tour-into-your-own-agent" aria-label="Permalink to &quot;Turn the weather tour into your own agent&quot;">​</a></h2><p>Keep the shape and replace the domain:</p><ul><li>Swap Open-Meteo tools for your typed service clients.</li><li>Keep deterministic transforms behind direct server tools or MCP.</li><li>Use an agent tool only when code must run in the agent workspace.</li><li>Put reusable procedures in skills and narrow specialist work into subagents.</li><li>Add a channel only when the external surface needs its own identity, continuation key, or delivery behavior.</li></ul><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/connections.html">MCP connections</a></li><li><a href="./../guides/human-in-the-loop.html">Human-in-the-loop approvals</a></li><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/schedules.html">Schedules and reminders</a></li><li><a href="./../evals.html">Evals</a></li><li><a href="./../ab.html">Live A/B metrics</a></li></ul>`,77)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_weather-agent.md.lVEAbWFf.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function h(o,e,l,r,d,p){return t(),a("div",null,[...e[0]||(e[0]=[i("",77)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/{guides_agent-to-agent.md.Bmbxy-FA.js → guides_agent-to-agent.md.BCeVdJRJ.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as s,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context.","frontmatter":{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."},"headers":[],"relativePath":"guides/agent-to-agent.md","filePath":"guides/agent-to-agent.md"}'),o={name:"guides/agent-to-agent.md"};function i(r,e,h,l,d,c){return a(),s("div",null,[...e[0]||(e[0]=[n(`<h1 id="agent-to-agent" tabindex="-1">Agent-to-agent <a class="header-anchor" href="#agent-to-agent" aria-label="Permalink to &quot;Agent-to-agent&quot;">​</a></h1><p>Every mounted agent is also an MCP server. So agents can delegate to each other without extra infrastructure. One agent hands a question to another, and the peer answers in its own session with its own instructions, tools, and context. Any external MCP client can do the same. A peer MCP connection makes the wiring one line.</p><p>This guide wires a <code>concierge</code> agent that delegates weather questions to a <code>weather-agent</code> peer mounted on the same host.</p><h2 id="the-mcp-endpoint" tabindex="-1">The MCP endpoint <a class="header-anchor" href="#the-mcp-endpoint" aria-label="Permalink to &quot;The MCP endpoint&quot;">​</a></h2><p>Each agent serves the Model Context Protocol over streamable HTTP at <code>/&lt;slug&gt;/v1/mcp</code> (or <code>/v1/mcp</code> in single mode). The surface is stateless (session identity travels in tool arguments) and runs the same route auth chain as the session API. It exposes three tools:</p><table tabindex="0"><thead><tr><th>Tool</th><th>Behavior</th></tr></thead><tbody><tr><td><code>ask</code></td><td>Send a message. Runs a model turn in this agent&#39;s own session and returns <code>{ status, sessionId, reply }</code>. Omit <code>sessionId</code> for a fresh session; pass it back to follow up.</td></tr><tr><td><code>check</code></td><td>Wait for or poll a running session (<code>waitSeconds: 0</code> polls without blocking).</td></tr><tr><td><code>call_tool</code></td><td>Call one of the agent&#39;s server tools directly, no model turn. Registered only when the agent has server tools.</td></tr></tbody></table><p>Waits are bounded at roughly 50 seconds, below typical MCP client request timeouts: a long turn returns <code>status: &quot;running&quot;</code> and the caller keeps waiting with <code>check</code>. Sessions created this way live on the <code>mcp</code> channel, bind to the calling principal, and show up in the playground and <code>GET /v1/sessions</code> like any other session.</p><p>Any MCP client can attach to this endpoint. It isn&#39;t only for other Agent SDK agents.</p><h2 id="wire-a-peer-mcp-connection" tabindex="-1">Wire a peer MCP connection <a class="header-anchor" href="#wire-a-peer-mcp-connection" aria-label="Permalink to &quot;Wire a peer MCP connection&quot;">​</a></h2><p>A peer MCP connection points one agent at another mounted on the same serve host. Author an MCP connection whose transport is the peer&#39;s slug:</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;">// agents/concierge/agent/mcp-connections/weather.ts</span></span>
+import{_ as t,c as s,o as a,ag as n}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context.","frontmatter":{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."},"headers":[],"relativePath":"guides/agent-to-agent.md","filePath":"guides/agent-to-agent.md"}'),o={name:"guides/agent-to-agent.md"};function i(r,e,h,l,d,c){return a(),s("div",null,[...e[0]||(e[0]=[n(`<h1 id="agent-to-agent" tabindex="-1">Agent-to-agent <a class="header-anchor" href="#agent-to-agent" aria-label="Permalink to &quot;Agent-to-agent&quot;">​</a></h1><p>Every mounted agent is also an MCP server. So agents can delegate to each other without extra infrastructure. One agent hands a question to another, and the peer answers in its own session with its own instructions, tools, and context. Any external MCP client can do the same. A peer MCP connection makes the wiring one line.</p><p>This guide wires a <code>concierge</code> agent that delegates weather questions to a <code>weather-agent</code> peer mounted on the same host.</p><h2 id="the-mcp-endpoint" tabindex="-1">The MCP endpoint <a class="header-anchor" href="#the-mcp-endpoint" aria-label="Permalink to &quot;The MCP endpoint&quot;">​</a></h2><p>Each agent serves the Model Context Protocol over streamable HTTP at <code>/&lt;slug&gt;/v1/mcp</code> (or <code>/v1/mcp</code> in single mode). The surface is stateless (session identity travels in tool arguments) and runs the same route auth chain as the session API. It exposes three tools:</p><table tabindex="0"><thead><tr><th>Tool</th><th>Behavior</th></tr></thead><tbody><tr><td><code>ask</code></td><td>Send a message. Runs a model turn in this agent&#39;s own session and returns <code>{ status, sessionId, reply }</code>. Omit <code>sessionId</code> for a fresh session; pass it back to follow up.</td></tr><tr><td><code>check</code></td><td>Wait for or poll a running session (<code>waitSeconds: 0</code> polls without blocking).</td></tr><tr><td><code>call_tool</code></td><td>Call one of the agent&#39;s server tools directly, no model turn. Registered only when the agent has server tools.</td></tr></tbody></table><p>Waits are bounded at roughly 50 seconds, below typical MCP client request timeouts: a long turn returns <code>status: &quot;running&quot;</code> and the caller keeps waiting with <code>check</code>. Sessions created this way live on the <code>mcp</code> channel, bind to the calling principal, and show up in the playground and <code>GET /v1/sessions</code> like any other session.</p><p>Any MCP client can attach to this endpoint. It isn&#39;t only for other Agent SDK agents.</p><h2 id="wire-a-peer-mcp-connection" tabindex="-1">Wire a peer MCP connection <a class="header-anchor" href="#wire-a-peer-mcp-connection" aria-label="Permalink to &quot;Wire a peer MCP connection&quot;">​</a></h2><p>A peer MCP connection points one agent at another mounted on the same serve host. Author an MCP connection whose transport is the peer&#39;s slug:</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;">// agents/concierge/agent/mcp-connections/weather.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{guides_agent-to-agent.md.Bmbxy-FA.lean.js → guides_agent-to-agent.md.BCeVdJRJ.lean.js}

@@ -1 +1 @@
-import{_ as t,c as s,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context.","frontmatter":{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."},"headers":[],"relativePath":"guides/agent-to-agent.md","filePath":"guides/agent-to-agent.md"}'),o={name:"guides/agent-to-agent.md"};function i(r,e,h,l,d,c){return a(),s("div",null,[...e[0]||(e[0]=[n("",26)])])}const u=t(o,[["render",i]]);export{g as __pageData,u as default};
+import{_ as t,c as s,o as a,ag as n}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context.","frontmatter":{"title":"Agent-to-agent","description":"Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."},"headers":[],"relativePath":"guides/agent-to-agent.md","filePath":"guides/agent-to-agent.md"}'),o={name:"guides/agent-to-agent.md"};function i(r,e,h,l,d,c){return a(),s("div",null,[...e[0]||(e[0]=[n("",26)])])}const u=t(o,[["render",i]]);export{g as __pageData,u as default};

package/dist/docs/assets/{guides_cloud-runtime.md.CbklWfzh.js → guides_cloud-runtime.md.BSMLIBHr.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return s(),o("div",null,[...e[0]||(e[0]=[a(`<h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return s(),o("div",null,[...e[0]||(e[0]=[a(`<h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cloud&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>

package/dist/docs/assets/{guides_cloud-runtime.md.CbklWfzh.lean.js → guides_cloud-runtime.md.BSMLIBHr.lean.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return s(),o("div",null,[...e[0]||(e[0]=[a("",29)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return s(),o("div",null,[...e[0]||(e[0]=[a("",29)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/{guides_convert-automation.md.BhMzTkE5.js → guides_convert-automation.md.D06eIzea.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o,ag as n}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.","frontmatter":{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it."},"headers":[],"relativePath":"guides/convert-automation.md","filePath":"guides/convert-automation.md"}'),s={name:"guides/convert-automation.md"};function i(r,e,d,c,l,h){return o(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="convert-a-cursor-automation" tabindex="-1">Convert a Cursor Automation <a class="header-anchor" href="#convert-a-cursor-automation" aria-label="Permalink to &quot;Convert a Cursor Automation&quot;">​</a></h1><p><code>convert-automation</code> exports a dashboard Automation into a local Agent SDK project. Use it when you need to edit, test, or deploy the Automation as code. Keep using the dashboard if you only need to change its prompt or trigger.</p><p>The converter refuses Cursor-managed Automations because their behavior lives in managed configuration. The <a href="./../reference/cli.html#convert-automation">CLI reference</a> lists flags and exit codes.</p><h2 id="run-the-conversion" tabindex="-1">Run the conversion <a class="header-anchor" href="#run-the-conversion" aria-label="Permalink to &quot;Run the conversion&quot;">​</a></h2><p>Sign in before converting. Unlike <code>init</code>, this command does not start a login flow.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
+import{_ as t,c as a,o,ag as n}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it.","frontmatter":{"title":"Convert a Cursor Automation","description":"Export a dashboard Automation into a local Agent SDK project, then review, validate, and run it."},"headers":[],"relativePath":"guides/convert-automation.md","filePath":"guides/convert-automation.md"}'),s={name:"guides/convert-automation.md"};function i(r,e,d,c,l,h){return o(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="convert-a-cursor-automation" tabindex="-1">Convert a Cursor Automation <a class="header-anchor" href="#convert-a-cursor-automation" aria-label="Permalink to &quot;Convert a Cursor Automation&quot;">​</a></h1><p><code>convert-automation</code> exports a dashboard Automation into a local Agent SDK project. Use it when you need to edit, test, or deploy the Automation as code. Keep using the dashboard if you only need to change its prompt or trigger.</p><p>The converter refuses Cursor-managed Automations because their behavior lives in managed configuration. The <a href="./../reference/cli.html#convert-automation">CLI reference</a> lists flags and exit codes.</p><h2 id="run-the-conversion" tabindex="-1">Run the conversion <a class="header-anchor" href="#run-the-conversion" aria-label="Permalink to &quot;Run the conversion&quot;">​</a></h2><p>Sign in before converting. Unlike <code>init</code>, this command does not start a login flow.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span></span></code></pre></div><p>Pass the Automation&#39;s dashboard URL or UUID. The URL must end with <code>/automations/&lt;uuid&gt;</code> or <code>/custom-agents/&lt;uuid&gt;</code>. Do not add path segments after the UUID.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> convert-automation</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555</span></span></code></pre></div><p>The summary prints the output directory. Change into it before running any setup command. For an Automation named &quot;Nightly triage&quot;:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nightly-triage</span></span></code></pre></div><p>The command fetches the Automation before writing files. A 404 means it was not found, you do not have access, or the <code>agent_serve_mvp</code> feature gate is off for your team. A 422 means it is Cursor-managed. The command writes nothing after either error.</p><p>The command runs <code>npm install</code> after writing the project. If the install fails, the files remain. Run <code>npm install</code> in the output directory before <code>dev</code>.</p><h2 id="what-the-project-contains" tabindex="-1">What the project contains <a class="header-anchor" href="#what-the-project-contains" aria-label="Permalink to &quot;What the project contains&quot;">​</a></h2><p>A cron Automation with a Linear MCP server might produce:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>nightly-triage/</span></span>
 <span class="line"><span>  package.json</span></span>

package/dist/docs/assets/{guides_convert-automation.md.BhMzTkE5.lean.js → guides_convert-automation.md.D06eIzea.lean.js}

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

package/dist/docs/assets/{guides_github.md.CLLQJKRB.js → guides_github.md.Cdt1s2QC.js}

@@ -1,11 +1,11 @@
-import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.","frontmatter":{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),n={name:"guides/github.md"};function h(o,s,l,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>Wake your agent from repository events without exposing a public webhook URL. Prefer <code>serve --cursor-events</code>: the host long-polls Cursor&#39;s SCM event stream for repos you&#39;ve connected to Cursor. You still declare a <code>githubChannel</code> so hooks decide what each event does.</p><p>The companion skill for coding agents is <a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>.</p><h2 id="pull-events-from-cursor" tabindex="-1">Pull events from Cursor <a class="header-anchor" href="#pull-events-from-cursor" aria-label="Permalink to &quot;Pull events from Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for the repositories you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). That gives your account access and lets Cursor receive the repo&#39;s webhooks. Sign the host in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>), then opt the channel into the Cursor account connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests.","frontmatter":{"title":"GitHub","description":"Wake your agent from pull requests, CI, and comments by pulling Cursor SCM events, with fixtures and replay for local tests."},"headers":[],"relativePath":"guides/github.md","filePath":"guides/github.md"}'),n={name:"guides/github.md"};function h(o,s,l,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="github-agents" tabindex="-1">GitHub agents <a class="header-anchor" href="#github-agents" aria-label="Permalink to &quot;GitHub agents&quot;">​</a></h1><p>Wake your agent from repository events without exposing a public webhook URL. Prefer <code>serve --cursor-events</code>: the host long-polls Cursor&#39;s SCM event stream for repos you&#39;ve connected to Cursor. You still declare a <code>githubChannel</code> so hooks decide what each event does.</p><p>The companion skill for coding agents is <a href="./../../skills/github/SKILL.html"><code>skills/github/SKILL.md</code></a>.</p><h2 id="pull-events-from-cursor" tabindex="-1">Pull events from Cursor <a class="header-anchor" href="#pull-events-from-cursor" aria-label="Permalink to &quot;Pull events from Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for the repositories you care about (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). That gives your account access and lets Cursor receive the repo&#39;s webhooks. Sign the host in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>), then opt the channel into the Cursor account connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // permissions?: &quot;read&quot; | &quot;pr-write&quot; | &quot;contents-write&quot;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // default &quot;pr-write&quot; (comments / PR writes, no contents:write)</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // hooks...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> starts the event relay and mints one short-lived GitHub credential scoped to those repositories. <code>ctx.github</code>, <code>ctx.host.github</code>, and child <code>gh</code> commands share it. The Agent SDK refreshes the credential before expiry. No GitHub App key, PAT, or separate <code>gh auth login</code> is needed on the host.</p><p>Choose <code>permissions</code> by what the agent needs:</p><table tabindex="0"><thead><tr><th><code>permissions</code></th><th>Use when</th></tr></thead><tbody><tr><td><code>&quot;read&quot;</code></td><td>Inspect PRs / issues / statuses only</td></tr><tr><td><code>&quot;pr-write&quot;</code> (default)</td><td>Comment, review, update PR/issue metadata</td></tr><tr><td><code>&quot;contents-write&quot;</code></td><td>Push code, or post merge-box checks</td></tr></tbody></table><p><code>contents-write</code> is an explicit opt-up. <code>progress.commitStatus</code> posts a GitHub check run (<code>checks:write</code>). Hosted <code>cursorAccount</code> mints that permission on <code>&quot;contents-write&quot;</code> tokens. Enabling <code>commitStatus</code> opts a <code>&quot;pr-write&quot;</code> channel up to that tier so github-proxy can post the check. <code>&quot;pr-write&quot;</code> without <code>commitStatus</code> is enough for comments and banners. Prefer <code>&quot;pr-write&quot;</code> unless the agent must push or post a merge-box check.</p><p>Selected repositories must share one GitHub owner (one App installation). Configuration that spans owners fails at startup / mint time.</p><p>To keep repository scope in deployment config instead, use <code>cursorAccount: true</code> and pass it at serve time:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Repeat <code>--repo</code> for each repository. The stream and credential are resolved as the signed-in Cursor principal. <code>serve</code> refuses to start signed out.</p><p>Offset and consumer id live under <code>&lt;state-root&gt;/cursor-events/</code>. <code>CURSOR_API_BASE_URL</code> overrides the backend. The stream carries event metadata, not full webhook bodies, so your agent should re-read the PR or checks from GitHub instead of trusting a snapshot in the wake.</p><p>This is the preferred production path: no public URL, no repo admin webhook, and no inbound network for GitHub deliveries.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code> from <code>@cursor/july/channels/github</code>. It mounts <code>POST /&lt;slug&gt;/v1/channels/github</code> and publishes the events it dispatches on. That event set comes from the hooks you declare, or you pin it with <code>webhookEvents</code>. Cursor event pull and local replay both use it.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>cursorAccount</code> starts the event relay and mints one short-lived GitHub credential scoped to those repositories. <code>ctx.github</code>, <code>ctx.host.github</code>, and child <code>gh</code> commands share it. The Agent SDK refreshes the credential before expiry. No GitHub App key, PAT, or separate <code>gh auth login</code> is needed on the host.</p><p>Choose <code>permissions</code> by what the agent needs:</p><table tabindex="0"><thead><tr><th><code>permissions</code></th><th>Use when</th></tr></thead><tbody><tr><td><code>&quot;read&quot;</code></td><td>Inspect PRs / issues / statuses only</td></tr><tr><td><code>&quot;pr-write&quot;</code> (default)</td><td>Comment, review, update PR/issue metadata</td></tr><tr><td><code>&quot;contents-write&quot;</code></td><td>Push code, or post merge-box checks</td></tr></tbody></table><p><code>contents-write</code> is an explicit opt-up. <code>progress.commitStatus</code> posts a GitHub check run (<code>checks:write</code>). Hosted <code>cursorAccount</code> mints that permission on <code>&quot;contents-write&quot;</code> tokens. Enabling <code>commitStatus</code> opts a <code>&quot;pr-write&quot;</code> channel up to that tier so github-proxy can post the check. <code>&quot;pr-write&quot;</code> without <code>commitStatus</code> is enough for comments and banners. Prefer <code>&quot;pr-write&quot;</code> unless the agent must push or post a merge-box check.</p><p>Set <code>checks: true</code> when channel code posts its own Checks API runs through <code>ctx.github.createCheck</code>. The flag grants access. It does not post a check.</p><p>Selected repositories must share one GitHub owner (one App installation). Configuration that spans owners fails at startup / mint time.</p><p>To keep repository scope in deployment config instead, use <code>cursorAccount: true</code> and pass it at serve time:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Repeat <code>--repo</code> for each repository. The stream and credential are resolved as the signed-in Cursor principal. <code>serve</code> refuses to start signed out.</p><p>Offset and consumer id live under <code>&lt;state-root&gt;/cursor-events/</code>. <code>CURSOR_API_BASE_URL</code> overrides the backend. The stream carries event metadata, not full webhook bodies, so your agent should re-read the PR or checks from GitHub instead of trusting a snapshot in the wake.</p><p>This is the preferred production path: no public URL, no repo admin webhook, and no inbound network for GitHub deliveries.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code> from <code>@cursor/july/channels/github</code>. It mounts <code>POST /&lt;slug&gt;/v1/channels/github</code> and publishes the events it dispatches on. That event set comes from the hooks you declare, or you pin it with <code>webhookEvents</code>. Cursor event pull and local replay both use it.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or GITHUB_APP_SLUG; used to ignore self-comments</span></span>
@@ -24,7 +24,7 @@ import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --conclusion</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> failure</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Inspect payloads without POSTing, and snapshot them as fixtures</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><p><code>--events</code> defaults to <code>pull_request</code>, and <code>&#39;*&#39;</code> means the channel&#39;s declared set. <code>--action</code>, <code>--conclusion</code>, <code>--comment</code>, and <code>--context</code> shape each synthesized event. <code>--secret</code> (or <code>GITHUB_WEBHOOK_SECRET</code>) signs them.</p><h2 id="receive-webhooks-directly" tabindex="-1">Receive webhooks directly <a class="header-anchor" href="#receive-webhooks-directly" aria-label="Permalink to &quot;Receive webhooks directly&quot;">​</a></h2><p>Most hosts should pull events from Cursor instead. Use the HTTP channel route when you already terminate GitHub webhooks yourself, or when you are POSTing fixtures and replay locally.</p><p>With a webhook secret configured, the route admits everyone (<code>allowAll()</code>) and the channel verifies <code>X-Hub-Signature-256</code> before parsing. The HMAC becomes the request principal. Without a secret, the route is loopback-only. The exception is <code>serve --dev</code>, which admits unsigned loopback deliveries so fixtures and replay work with zero config. Non-dev targets that accept real GitHub POSTs always need the secret, and the same value must live on the server and on whatever signs deliveries.</p><h2 id="handle-high-event-volume" tabindex="-1">Handle high event volume <a class="header-anchor" href="#handle-high-event-volume" aria-label="Permalink to &quot;Handle high event volume&quot;">​</a></h2><p>These patterns come from running a PR agent against real traffic:</p><ul><li>Debounce per PR (~3 seconds, latest event wins), and re-buffer while CI settles. Skip a flush when a turn for that PR is already running.</li><li>Persist the buffer in <code>host.kv</code> before you acknowledge a wake, and restore it on channel start. A restart must not drop buffered wakes.</li><li>Key sessions with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake resumes the PR&#39;s conversation. Cross-channel resume needs an affinity store mapping PR → SDK agent id; write it from an <code>agent.bound</code> hook with <code>ctx.host.kv</code>.</li><li>Keep payload details out of wake prompts. Send a generic &quot;re-check the PR&quot; and let the agent re-read source of truth instead of trusting a stale snapshot.</li><li>Cancel PR-scoped reminders on <code>pull_request.closed</code>.</li><li>Decide explicitly which repos the agent may act on. Without an allowlist the channel wakes for whatever deliveries reach it, and every wake spends real model budget.</li></ul><h2 id="show-pr-progress" tabindex="-1">Show PR progress <a class="header-anchor" href="#show-pr-progress" aria-label="Permalink to &quot;Show PR progress&quot;">​</a></h2><p>Autofix-style agents need a deterministic merge-box check and a sticky PR comment that converges when the turn ends. Configure that on the channel with <code>progress.commitStatus</code> and <code>progress.banner</code>. A hook can read and write <code>ctx.host.kv</code> and <code>ctx.host.files</code> after a turn. Use that for derived state. Keep GitHub check-run and banner writes on the channel.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><p><code>--events</code> defaults to <code>pull_request</code>. <code>&#39;*&#39;</code> replays the events the channel declares and the CLI can synthesize. <code>--action</code>, <code>--conclusion</code>, <code>--comment</code>, and <code>--context</code> shape each event. <code>--secret</code> or <code>GITHUB_WEBHOOK_SECRET</code> signs them.</p><h2 id="receive-webhooks-directly" tabindex="-1">Receive webhooks directly <a class="header-anchor" href="#receive-webhooks-directly" aria-label="Permalink to &quot;Receive webhooks directly&quot;">​</a></h2><p>Most hosts should pull events from Cursor instead. Use the HTTP channel route when you already terminate GitHub webhooks yourself, or when you are POSTing fixtures and replay locally.</p><p>With a webhook secret configured, the route admits everyone (<code>allowAll()</code>) and the channel verifies <code>X-Hub-Signature-256</code> before parsing. The HMAC becomes the request principal. Without a secret, the route is loopback-only. The exception is <code>serve --dev</code>, which admits unsigned loopback deliveries so fixtures and replay work with zero config. Non-dev targets that accept real GitHub POSTs always need the secret, and the same value must live on the server and on whatever signs deliveries.</p><h2 id="handle-high-event-volume" tabindex="-1">Handle high event volume <a class="header-anchor" href="#handle-high-event-volume" aria-label="Permalink to &quot;Handle high event volume&quot;">​</a></h2><p>These patterns come from running a PR agent against real traffic:</p><ul><li>Debounce per PR (~3 seconds, latest event wins), and re-buffer while CI settles. Skip a flush when a turn for that PR is already running.</li><li>Persist the buffer in <code>host.kv</code> before you acknowledge a wake, and restore it on channel start. A restart must not drop buffered wakes.</li><li>Key sessions with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake resumes the PR&#39;s conversation. Cross-channel resume needs an affinity store mapping PR → SDK agent id; write it from an <code>agent.bound</code> hook with <code>ctx.host.kv</code>.</li><li>Keep payload details out of wake prompts. Send a generic &quot;re-check the PR&quot; and let the agent re-read source of truth instead of trusting a stale snapshot.</li><li>Cancel PR-scoped reminders on <code>pull_request.closed</code>.</li><li>Decide explicitly which repos the agent may act on. Without an allowlist the channel wakes for whatever deliveries reach it, and every wake spends real model budget.</li></ul><h2 id="show-pr-progress" tabindex="-1">Show PR progress <a class="header-anchor" href="#show-pr-progress" aria-label="Permalink to &quot;Show PR progress&quot;">​</a></h2><p>Autofix-style agents need a deterministic merge-box check and a sticky PR comment that converges when the turn ends. Configure that on the channel with <code>progress.commitStatus</code> and <code>progress.banner</code>. A hook can read and write <code>ctx.host.kv</code> and <code>ctx.host.files</code> after a turn. Use that for derived state. Keep GitHub check-run and banner writes on the channel.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;autofix&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -51,4 +51,4 @@ import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    pr.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;opened&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Default stream events drive the lifecycle:</p><table tabindex="0"><thead><tr><th>Event</th><th>Check run</th><th>Banner</th></tr></thead><tbody><tr><td><code>turn.started</code></td><td><code>in_progress</code></td><td>create (or keep) the sticky comment</td></tr><tr><td><code>turn.completed</code></td><td><code>completed</code> / <code>success</code></td><td>PATCH the same comment</td></tr><tr><td><code>turn.failed</code> / <code>session.failed</code></td><td><code>completed</code> / <code>failure</code></td><td>PATCH the same comment</td></tr></tbody></table><p>Omit <code>commitStatus</code> / <code>banner</code>, or set them to <code>false</code>, to keep today&#39;s behavior. Reactions still default on; set <code>reactions: false</code> when the eyes emoji is noise. Descriptions are optional; defaults derive from <code>botName</code> or the check <code>context</code>.</p><p>The check run posts to <code>channel.state.headSha</code>. PR and CI wakes seed and refresh it (<code>refreshState</code> on continuation). A first wake that is only an <code>issue_comment</code> has no head SHA in the payload, so the check is skipped until a PR/CI wake stores one; the banner still posts. Review-comment wakes carry <code>pull_request.head.sha</code> when GitHub includes it.</p><p>The sticky comment id and latest check-run id live on durable <code>GitHubChannelState</code> (session record). Each wake also passes <code>refreshState</code> so <code>headSha</code> / refs update on continuation without wiping those ids. A later turn on the same SHA creates a new check run — GitHub cannot reopen a completed run. Persist other derived state with <code>ctx.host.kv</code> or <code>ctx.host.files</code>. <code>stateRoot</code> resets on hosted replace.</p><p>Override <code>events</code> when the mapping is custom. <a href="./../example-agents/approval-buddy.html">Approval Buddy</a> posts commit status from <code>turn.started</code> / <code>action.result</code> / <code>turn.failed</code> and stays never-red; that pattern still wins when you replace a default handler key. Handlers you author replace the matching defaults (same as <code>progress.reactions</code> composition today).</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./cloud-runtime.html">Cloud runtime</a>: attach PRs to cloud VMs</li><li><a href="./../reference/hooks.html">Hooks</a>: observe-only; use channel <code>progress</code> for GitHub surfaces</li></ul>`,51)])])}const u=e(n,[["render",h]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Default stream events drive the lifecycle:</p><table tabindex="0"><thead><tr><th>Event</th><th>Check run</th><th>Banner</th></tr></thead><tbody><tr><td><code>turn.started</code></td><td><code>in_progress</code></td><td>create (or keep) the sticky comment</td></tr><tr><td><code>turn.completed</code></td><td><code>completed</code> / <code>success</code></td><td>PATCH the same comment</td></tr><tr><td><code>turn.failed</code> / <code>session.failed</code></td><td><code>completed</code> / <code>failure</code></td><td>PATCH the same comment</td></tr></tbody></table><p>Omit <code>commitStatus</code> / <code>banner</code>, or set them to <code>false</code>, to keep today&#39;s behavior. Reactions still default on; set <code>reactions: false</code> when the eyes emoji is noise. Descriptions are optional; defaults derive from <code>botName</code> or the check <code>context</code>.</p><p>The check run posts to <code>channel.state.headSha</code>. PR and CI wakes seed and refresh it (<code>refreshState</code> on continuation). A first wake that is only an <code>issue_comment</code> has no head SHA in the payload, so the check is skipped until a PR/CI wake stores one; the banner still posts. Review-comment wakes carry <code>pull_request.head.sha</code> when GitHub includes it.</p><p>The sticky comment id and latest check-run id live on durable <code>GitHubChannelState</code> (session record). Each wake also passes <code>refreshState</code> so <code>headSha</code> / refs update on continuation without wiping those ids. A later turn on the same SHA creates a new check run — GitHub cannot reopen a completed run. Persist other derived state with <code>ctx.host.kv</code> or <code>ctx.host.files</code>. <code>stateRoot</code> resets on hosted replace.</p><p>Override <code>events</code> when the mapping is custom. <a href="./../example-agents/approval-buddy.html">Approval Buddy</a> posts commit status from <code>turn.started</code> / <code>action.result</code> / <code>turn.failed</code> and stays never-red; that pattern still wins when you replace a default handler key. Handlers you author replace the matching defaults (same as <code>progress.reactions</code> composition today).</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./webhooks.html">Webhooks and custom channels</a>: the HTTP mechanism under this pack</li><li><a href="./../evals.html">Evals</a>: turn replay snapshots into regression fixtures</li><li><a href="./cloud-runtime.html">Cloud runtime</a>: attach PRs to cloud VMs</li><li><a href="./../reference/hooks.html">Hooks</a>: observe-only; use channel <code>progress</code> for GitHub surfaces</li></ul>`,52)])])}const u=e(n,[["render",h]]);export{k as __pageData,u as default};

package/dist/docs/assets/{guides_github.md.CLLQJKRB.lean.js → guides_github.md.Cdt1s2QC.lean.js}

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

package/dist/docs/assets/{guides_human-in-the-loop.md.Cf8kIIqC.js → guides_human-in-the-loop.md.By1G2T3_.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.","frontmatter":{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."},"headers":[],"relativePath":"guides/human-in-the-loop.md","filePath":"guides/human-in-the-loop.md"}'),n={name:"guides/human-in-the-loop.md"};function l(p,s,h,o,r,k){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="human-in-the-loop-approvals" tabindex="-1">Human-in-the-loop approvals <a class="header-anchor" href="#human-in-the-loop-approvals" aria-label="Permalink to &quot;Human-in-the-loop approvals&quot;">​</a></h1><p>Some tools must wait for human review: promoting a build, approving a PR, spending money. Mark those tools <code>needsApproval</code> and the host parks the in-flight call until a person approves or denies it, from the playground, over HTTP, or with Slack buttons. The turn stays running; nothing executes until someone decides.</p><h2 id="gate-a-tool" tabindex="-1">Gate a tool <a class="header-anchor" href="#gate-a-tool" aria-label="Permalink to &quot;Gate a tool&quot;">​</a></h2><p>Mark the tool with <code>needsApproval</code> and export it like any other 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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.","frontmatter":{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."},"headers":[],"relativePath":"guides/human-in-the-loop.md","filePath":"guides/human-in-the-loop.md"}'),n={name:"guides/human-in-the-loop.md"};function l(p,s,h,o,r,k){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="human-in-the-loop-approvals" tabindex="-1">Human-in-the-loop approvals <a class="header-anchor" href="#human-in-the-loop-approvals" aria-label="Permalink to &quot;Human-in-the-loop approvals&quot;">​</a></h1><p>Some tools must wait for human review: promoting a build, approving a PR, spending money. Mark those tools <code>needsApproval</code> and the host parks the in-flight call until a person approves or denies it, from the playground, over HTTP, or with Slack buttons. The turn stays running; nothing executes until someone decides.</p><h2 id="gate-a-tool" tabindex="-1">Gate a tool <a class="header-anchor" href="#gate-a-tool" aria-label="Permalink to &quot;Gate a tool&quot;">​</a></h2><p>Mark the tool with <code>needsApproval</code> and export it like any other 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;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{guides_human-in-the-loop.md.Cf8kIIqC.lean.js → guides_human-in-the-loop.md.By1G2T3_.lean.js}

@@ -1 +1 @@
-import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.","frontmatter":{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."},"headers":[],"relativePath":"guides/human-in-the-loop.md","filePath":"guides/human-in-the-loop.md"}'),n={name:"guides/human-in-the-loop.md"};function l(p,s,h,o,r,k){return e(),i("div",null,[...s[0]||(s[0]=[t("",27)])])}const u=a(n,[["render",l]]);export{c as __pageData,u as default};
+import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout.","frontmatter":{"title":"Human-in-the-loop","description":"Gate a tool call on human approval: park it, resolve it from the playground, HTTP, or Slack, and keep the turn alive throughout."},"headers":[],"relativePath":"guides/human-in-the-loop.md","filePath":"guides/human-in-the-loop.md"}'),n={name:"guides/human-in-the-loop.md"};function l(p,s,h,o,r,k){return e(),i("div",null,[...s[0]||(s[0]=[t("",27)])])}const u=a(n,[["render",l]]);export{c as __pageData,u as default};

package/dist/docs/assets/{guides_mcp-oauth.md.CzEB6RaG.js → guides_mcp-oauth.md.Du0f7pGU.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function o(h,s,l,d,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="host-mcp-oauth" tabindex="-1">Host MCP OAuth <a class="header-anchor" href="#host-mcp-oauth" aria-label="Permalink to &quot;Host MCP OAuth&quot;">​</a></h1><p>Use host MCP OAuth when your agent talks to a remote MCP server that speaks OAuth, and you want credentials on the serve host (or the hosted engine) instead of a Cursor account connector. Local login writes tokens next to your Cursor credentials. <code>--store</code> copies them onto the deployment as secrets so prod can reconnect after a redeploy.</p><p>The companion skill is <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-can-host-mcp-oauth-do" tabindex="-1">What can host MCP OAuth do? <a class="header-anchor" href="#what-can-host-mcp-oauth-do" aria-label="Permalink to &quot;What can host MCP OAuth do?&quot;">​</a></h2><ul><li>Authorize <code>defineConnection({ url, oauth: true })</code> with a browser PKCE flow (<code>agent-sdk mcp oauth &lt;connection&gt;</code>)</li><li>Keep tokens in <code>~/.config/agent-serve/mcp-auth.json</code>, bound to that connection&#39;s resource URL</li><li>Upsert deployment secrets with <code>--store</code> so hosted engines seed the same tokens from env</li><li>Keep privileged servers off the model with <code>hostOnly: true</code> while tools still call them through <code>ctx.host.mcp</code>. Do not set <code>hostOnly</code> on connectors the playground or local chat should call. Use <code>advertiseTools: true</code> for those.</li></ul><p>Prefer a Cursor account MCP connection when the connector already lives in the signed-in account dashboard:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// every connected connector</span></span>
+import{_ as e,c as t,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize defineConnection({ url, oauth: true }) with agent-sdk mcp oauth, store tokens locally, and push MCP_OAUTH_* secrets to hosted deployments."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function o(h,s,l,d,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="host-mcp-oauth" tabindex="-1">Host MCP OAuth <a class="header-anchor" href="#host-mcp-oauth" aria-label="Permalink to &quot;Host MCP OAuth&quot;">​</a></h1><p>Use host MCP OAuth when your agent talks to a remote MCP server that speaks OAuth, and you want credentials on the serve host (or the hosted engine) instead of a Cursor account connector. Local login writes tokens next to your Cursor credentials. <code>--store</code> copies them onto the deployment as secrets so prod can reconnect after a redeploy.</p><p>The companion skill is <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-can-host-mcp-oauth-do" tabindex="-1">What can host MCP OAuth do? <a class="header-anchor" href="#what-can-host-mcp-oauth-do" aria-label="Permalink to &quot;What can host MCP OAuth do?&quot;">​</a></h2><ul><li>Authorize <code>defineConnection({ url, oauth: true })</code> with a browser PKCE flow (<code>agent-sdk mcp oauth &lt;connection&gt;</code>)</li><li>Keep tokens in <code>~/.config/agent-serve/mcp-auth.json</code>, bound to that connection&#39;s resource URL</li><li>Upsert deployment secrets with <code>--store</code> so hosted engines seed the same tokens from env</li><li>Keep privileged servers off the model with <code>hostOnly: true</code> while tools still call them through <code>ctx.host.mcp</code>. Do not set <code>hostOnly</code> on connectors the playground or local chat should call. Use <code>advertiseTools: true</code> for those.</li></ul><p>Prefer a Cursor account MCP connection when the connector already lives in the signed-in account dashboard:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// every connected connector</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or servers: &quot;*&quot; / servers: [&quot;Linear&quot;]</span></span></code></pre></div><p>Use host OAuth when the server is yours (or private to your network) and the host must hold tokens.</p><h2 id="how-do-i-declare-a-host-oauth-connection" tabindex="-1">How do I declare a host-OAuth connection? <a class="header-anchor" href="#how-do-i-declare-a-host-oauth-connection" aria-label="Permalink to &quot;How do I declare a host-OAuth connection?&quot;">​</a></h2><p>Add one file under <code>agent/mcp-connections/</code>. The filename is the connection name you pass to the CLI and to <code>host.mcp</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/mcp-connections/inventory.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>

package/dist/docs/assets/{guides_mcp-oauth.md.CzEB6RaG.lean.js → guides_mcp-oauth.md.Du0f7pGU.lean.js}

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

package/dist/docs/assets/{guides_opentelemetry.md.Csn7ZI25.js → guides_opentelemetry.md.bmPmkvJu.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to &quot;OpenTelemetry&quot;">​</a></h1><p>Agent SDK can push traces, metrics, and logs from the serve process to an OTLP collector you run. Point the process at the collector with standard <code>OTEL_EXPORTER_OTLP_*</code> env, or author <code>agent/otel.ts</code>. Traces cover the inbound request, the session, each turn, and every tool call.</p><p>Export is opt-in. Nothing leaves the process until you set an endpoint or a <code>defineOtel</code> config.</p><h2 id="what-does-agent-sdk-export" tabindex="-1">What does Agent SDK export? <a class="header-anchor" href="#what-does-agent-sdk-export" aria-label="Permalink to &quot;What does Agent SDK export?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Signal</th><th>Default</th><th>What you get</th></tr></thead><tbody><tr><td>Traces</td><td>on</td><td><code>agent_sdk.http</code> → <code>agent_sdk.session</code> → <code>agent_sdk.turn</code> → <code>agent_sdk.tool</code> / <code>agent_sdk.subagent</code></td></tr><tr><td>Metrics</td><td>on</td><td><code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, plus <code>agent_sdk.*</code> session and turn counts</td></tr><tr><td>Logs</td><td>off</td><td>Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in</td></tr></tbody></table><p>Turn off a signal with <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: false</code> on <code>defineOtel</code>. Logs also turn on when you set <code>OTEL_LOGS_EXPORTER</code> to anything other than <code>none</code>, or when you set the content flags below.</p><h2 id="how-do-i-turn-opentelemetry-export-on" tabindex="-1">How do I turn OpenTelemetry export on? <a class="header-anchor" href="#how-do-i-turn-opentelemetry-export-on" aria-label="Permalink to &quot;How do I turn OpenTelemetry export on?&quot;">​</a></h2><p>Set a collector URL in the serve process environment:</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>
+import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to &quot;OpenTelemetry&quot;">​</a></h1><p>Agent SDK can push traces, metrics, and logs from the serve process to an OTLP collector you run. Point the process at the collector with standard <code>OTEL_EXPORTER_OTLP_*</code> env, or author <code>agent/otel.ts</code>. Traces cover the inbound request, the session, each turn, and every tool call.</p><p>Export is opt-in. Nothing leaves the process until you set an endpoint or a <code>defineOtel</code> config.</p><h2 id="what-does-agent-sdk-export" tabindex="-1">What does Agent SDK export? <a class="header-anchor" href="#what-does-agent-sdk-export" aria-label="Permalink to &quot;What does Agent SDK export?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Signal</th><th>Default</th><th>What you get</th></tr></thead><tbody><tr><td>Traces</td><td>on</td><td><code>agent_sdk.http</code> → <code>agent_sdk.session</code> → <code>agent_sdk.turn</code> → <code>agent_sdk.tool</code> / <code>agent_sdk.subagent</code></td></tr><tr><td>Metrics</td><td>on</td><td><code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, plus <code>agent_sdk.*</code> session and turn counts</td></tr><tr><td>Logs</td><td>off</td><td>Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in</td></tr></tbody></table><p>Turn off a signal with <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: false</code> on <code>defineOtel</code>. Logs also turn on when you set <code>OTEL_LOGS_EXPORTER</code> to anything other than <code>none</code>, or when you set the content flags below.</p><h2 id="how-do-i-turn-opentelemetry-export-on" tabindex="-1">How do I turn OpenTelemetry export on? <a class="header-anchor" href="#how-do-i-turn-opentelemetry-export-on" aria-label="Permalink to &quot;How do I turn OpenTelemetry export on?&quot;">​</a></h2><p>Set a collector URL in the serve process environment:</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 …&quot;</span></span></code></pre></div><p>The default wire format is OTLP/HTTP protobuf. That matches <a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>. Set <code>OTEL_EXPORTER_OTLP_PROTOCOL=http/json</code> when your collector only accepts JSON. The runtime accepts <code>http/protobuf</code> and <code>http/json</code>. <code>grpc</code> falls back to protobuf and logs a warning.</p><p><code>OTEL_EXPORTER_OTLP_ENDPOINT</code> is the base URL. The runtime appends <code>/v1/traces</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>. If you pass a signal path, it is stripped back to the base first.</p><p>To send each signal to a different collector, omit the base URL and set the per-signal vars:</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_TRACES_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://traces.example.com/v1/traces</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_METRICS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://metrics.example.com/v1/metrics</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_LOGS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://logs.example.com/v1/logs</span></span></code></pre></div><p>Optional:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Resource <code>service.name</code>. Default <code>cursor</code></td></tr><tr><td><code>OTEL_LOG_USER_PROMPTS=1</code></td><td>Include user prompt text on logs and span events</td></tr><tr><td><code>OTEL_LOG_TOOL_CONTENT=1</code></td><td>Include tool payloads and failure text (truncated)</td></tr></tbody></table><p><code>serve(dir, { otel: false })</code> turns export off even when env or <code>agent/otel.ts</code> is set.</p><h2 id="how-do-i-author-agent-otel-ts" tabindex="-1">How do I author <code>agent/otel.ts</code>? <a class="header-anchor" href="#how-do-i-author-agent-otel-ts" aria-label="Permalink to &quot;How do I author \`agent/otel.ts\`?&quot;">​</a></h2><p>Use <code>defineOtel</code> when you want the collector URL, headers, or sampling in the project instead of the environment:</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;"> { defineOtel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/otel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>

package/dist/docs/assets/{guides_opentelemetry.md.Csn7ZI25.lean.js → guides_opentelemetry.md.bmPmkvJu.lean.js}

@@ -1 +1 @@
-import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o("",50)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};
+import{_ as s,c as t,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,l,d,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o("",50)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};