@cursor/july 0.1.68 → 0.1.74

package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.js → reference_cli.md.TAaYU8br.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>july</code> (so <code>npx @cursor/july docs</code> works), <code>agent-sdk</code>, and the legacy <code>agent-serve</code> alias. The examples on this page use <code>agent-sdk</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p>The current release still uses <code>.agent-serve</code> for on-disk state. See the <a href="/docs/#run-the-cli">rename table</a> for identifiers still moving to agent-sdk names.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved <code>events.ndjson</code> file</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Install the coding-agent skills without running <code>init</code></td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>july</code> (so <code>npx @cursor/july docs</code> works), <code>agent-sdk</code>, and the legacy <code>agent-serve</code> alias. The examples on this page use <code>agent-sdk</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p>The current release still uses <code>.agent-serve</code> for on-disk state. See the <a href="/docs/#run-the-cli">rename table</a> for identifiers still moving to agent-sdk names.</p><p><code>agent-sdk help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agent-sdk slack help</code> and <code>agent-sdk github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#cost"><code>cost</code></a></td><td>Report per-session token usage and estimated cost</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the shipped documentation site locally</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved <code>events.ndjson</code> file</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#convert-automation"><code>convert-automation</code></a></td><td>Export a Cursor Automation into an agent project</td></tr><tr><td><a href="#install-skills"><code>install-skills</code></a></td><td>Refresh coding-agent skills (<code>npm install</code> already copies them)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><code>version</code></td><td>Print the installed version and exit (also <code>--version</code> / <code>-V</code>)</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp"><code>mcp</code></a></td><td>Proxy the agent&#39;s MCP endpoint over stdio; <code>mcp install</code> writes <code>~/.cursor/mcp.json</code></td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Provision, set up, and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code>, <code>mcp</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>cost</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL. <code>mcp</code> has no default target; pass <code>--url</code> or <code>--prod</code>.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, the Agent SDK selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--mode multi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">single] [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--state-root </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --allow-anonymous]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--allow-anonymous-cursor-github]</span></span>
@@ -52,7 +52,7 @@ import{_ as i,c as e,o as a,ag as t}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;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --var</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repos=acme/widgets,acme/api</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;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # machine-readable summary for tooling</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                     # no directory: print the setup guide</span></span></code></pre></div><p><code>init</code> leaves existing files unchanged and labels each one <code>create</code> or <code>exist</code>. It prints the project path, then runs <code>npm install</code> so <code>@cursor/july</code> resolves for <code>dev</code> and <code>run</code>.</p><p>Templates may ship <code>init.json</code>. On a TTY, <code>init</code> asks those questions before writing files. <code>pr-autofixer</code> asks for GitHub repos. Repeat <code>--var id=value</code> to answer without a prompt. <code>--json</code> and non-TTY hosts skip the interview unless <code>--var</code> is set.</p><p>On a TTY, <code>init</code> also asks whether to install or update the coding-agent skills in <code>~/.cursor/skills/agentkit/</code>. If accepted, it overwrites them with the version bundled in the installed package. The prompt is skipped for <code>--json</code> and non-interactive hosts.</p><p>If the host isn&#39;t signed in, <code>init</code> runs <code>agent-sdk login</code> and waits for the browser flow. It then prints the <code>cd</code>, <code>agent-sdk login</code>, and <code>agent-sdk dev</code> steps still needed.</p><p>With <code>--json</code>, <code>init</code> still installs dependencies but never blocks on login or skill installation. It prints <code>{ ok, directory, created, skipped, installed, installError, next }</code> (with <code>login</code> in <code>next</code> when unsigned).</p><h2 id="convert-automation" tabindex="-1">convert-automation <a class="header-anchor" href="#convert-automation" aria-label="Permalink to &quot;convert-automation&quot;">​</a></h2><p><code>convert-automation</code> exports a Cursor Automation into an agent project.</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:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ur</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>&lt;url&gt;</code> is the dashboard URL (<code>…/automations/&lt;uuid&gt;</code> or <code>…/custom-agents/&lt;uuid&gt;</code>) or a bare UUID. The command fetches the Automation with your Cursor credentials. It writes converted files to <code>--dir</code>, which defaults to <code>./&lt;automation-name&gt;</code>, adds missing <code>init</code> scaffold files, and runs <code>npm install</code>. File generation does not overwrite existing paths. The install may still update lockfiles or run lifecycle scripts from an existing <code>package.json</code>.</p><p>MCP servers convert to Cursor-account connections resolved at runtime. The project contains their names, not server URLs or credentials. Local runs use the signed-in account. Hosted deployments use a separate service account; authorize each generated connection with <a href="#mcp-oauth"><code>mcp oauth</code></a> after the first deploy. Review the generated project, then run <code>validate</code> and <code>dev</code>.</p><p>Warnings do not change the exit status. Bad arguments, authentication failures, fetch failures, and file write failures return a nonzero exit code.</p><p><code>--json</code> prints <code>{ ok, directory, files, warnings, setupSteps, installed, installError, mcpConnections }</code>. On failure it prints <code>{ ok: false, error }</code> and still writes the prose error to stderr.</p><p>The <a href="./../guides/convert-automation.html">Convert a Cursor Automation</a> guide covers generated files and behavior the converter cannot reproduce.</p><h2 id="install-skills" tabindex="-1">install-skills <a class="header-anchor" href="#install-skills" aria-label="Permalink to &quot;install-skills&quot;">​</a></h2><p><code>install-skills</code> installs the package&#39;s coding-agent skills into <code>~/.cursor/skills/agentkit/</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;"> install-skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--print] [--json]</span></span></code></pre></div><p>Running the command is the confirmation: it never prompts, and it overwrites the installed skills with the version bundled in the package. <code>init</code> offers the same install once, interactively. <code>--print</code> previews the skills, the removals, and the install path without writing anything. <code>--json</code> prints <code>{ ok, dryRun, directory, firstInstall, skills, removed }</code>.</p><h2 id="info" tabindex="-1">info <a class="header-anchor" href="#info" aria-label="Permalink to &quot;info&quot;">​</a></h2><p><code>info</code> prints the discovered agent surface.</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;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>info</code> reports the model, instruction size, tools, skills, MCP connections, subagents, channel routes, schedules, hooks, and diagnostics. Text output summarizes each mounted agent. <code>--json</code> prints <code>{ agents: [{ slug, ...projectInfo }] }</code>, with one entry per mounted slug. Use <code>validate</code>, not <code>info --json</code>, when a script needs an error exit status.</p><h2 id="validate" tabindex="-1">validate <a class="header-anchor" href="#validate" aria-label="Permalink to &quot;validate&quot;">​</a></h2><p><code>validate</code> checks the project and sets the exit 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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>validate</code> prints diagnostics for each agent and exits non-zero when any diagnostic has error severity. <code>serve</code> also refuses to start when errors are present. Warnings don&#39;t change the exit status.</p><h2 id="login-logout-whoami" tabindex="-1">login / logout / whoami <a class="header-anchor" href="#login-logout-whoami" aria-label="Permalink to &quot;login / logout / whoami&quot;">​</a></h2><p>Three commands manage the host&#39;s Cursor credential.</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 style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ke</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--key-name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                     # no directory: print the setup guide</span></span></code></pre></div><p><code>init</code> leaves existing files unchanged and labels each one <code>create</code> or <code>exist</code>. It prints the project path, then runs <code>npm install</code> so <code>@cursor/july</code> resolves for <code>dev</code> and <code>run</code>.</p><p>Templates may ship <code>init.json</code>. On a TTY, <code>init</code> asks those questions before writing files. <code>pr-autofixer</code> asks for GitHub repos. Repeat <code>--var id=value</code> to answer without a prompt. <code>--json</code> and non-TTY hosts skip the interview unless <code>--var</code> is set.</p><p>On a TTY, <code>init</code> also asks whether to refresh the coding-agent skills in <code>~/.cursor/skills/agentsdk/</code>. Installing <code>@cursor/july</code> already copies them via postinstall (with <code>alwaysApply: true</code> so Cursor injects the bodies), so this prompt is a chance to overwrite with the package version. The prompt is skipped for <code>--json</code> and non-interactive hosts.</p><p>If the host isn&#39;t signed in, <code>init</code> runs <code>agent-sdk login</code> and waits for the browser flow. It then prints the <code>cd</code>, <code>agent-sdk login</code>, and <code>agent-sdk dev</code> steps still needed.</p><p>With <code>--json</code>, <code>init</code> still installs dependencies but never blocks on login or skill installation. It prints <code>{ ok, directory, created, skipped, installed, installError, next }</code> (with <code>login</code> in <code>next</code> when unsigned).</p><h2 id="convert-automation" tabindex="-1">convert-automation <a class="header-anchor" href="#convert-automation" aria-label="Permalink to &quot;convert-automation&quot;">​</a></h2><p><code>convert-automation</code> exports a Cursor Automation into an agent project.</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:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ur</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>&lt;url&gt;</code> is the dashboard URL (<code>…/automations/&lt;uuid&gt;</code> or <code>…/custom-agents/&lt;uuid&gt;</code>) or a bare UUID. The command fetches the Automation with your Cursor credentials. It writes converted files to <code>--dir</code>, which defaults to <code>./&lt;automation-name&gt;</code>, adds missing <code>init</code> scaffold files, and runs <code>npm install</code>. File generation does not overwrite existing paths. The install may still update lockfiles or run lifecycle scripts from an existing <code>package.json</code>.</p><p>MCP servers convert to Cursor-account connections resolved at runtime. The project contains their names, not server URLs or credentials. Local runs use the signed-in account. Hosted deployments use a separate service account; authorize each generated connection with <a href="#mcp-oauth"><code>mcp oauth</code></a> after the first deploy. Review the generated project, then run <code>validate</code> and <code>dev</code>.</p><p>Warnings do not change the exit status. Bad arguments, authentication failures, fetch failures, and file write failures return a nonzero exit code.</p><p><code>--json</code> prints <code>{ ok, directory, files, warnings, setupSteps, installed, installError, mcpConnections }</code>. On failure it prints <code>{ ok: false, error }</code> and still writes the prose error to stderr.</p><p>The <a href="./../guides/convert-automation.html">Convert a Cursor Automation</a> guide covers generated files and behavior the converter cannot reproduce.</p><h2 id="install-skills" tabindex="-1">install-skills <a class="header-anchor" href="#install-skills" aria-label="Permalink to &quot;install-skills&quot;">​</a></h2><p><code>install-skills</code> copies the package&#39;s coding-agent skills into <code>~/.cursor/skills/agentsdk/</code> with <code>alwaysApply: true</code> so Cursor loads them as global rules. Installing <code>@cursor/july</code> already does this in postinstall (<code>npm install</code>, <code>npx</code>, a version bump). Use this command to refresh without reinstalling the package, or from a monorepo source checkout (postinstall skips that tree).</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;"> install-skills</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--print] [--json]</span></span></code></pre></div><p>Running the command is the confirmation: it never prompts, and it overwrites the installed skills with the version bundled in the package. <code>init</code> offers the same refresh once, interactively. <code>--print</code> previews the skills, the removals, and the install path without writing anything. <code>--json</code> prints <code>{ ok, dryRun, directory, firstInstall, skills, removed }</code>.</p><p>Set <code>CURSOR_JULY_SKIP_SKILL_INSTALL=1</code> to skip the postinstall copy. <code>CURSOR_JULY_SKILLS_HOME</code> overrides the <code>~/.cursor/skills</code> directory.</p><h2 id="info" tabindex="-1">info <a class="header-anchor" href="#info" aria-label="Permalink to &quot;info&quot;">​</a></h2><p><code>info</code> prints the discovered agent surface.</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;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>info</code> reports the model, instruction size, tools, skills, MCP connections, subagents, channel routes, schedules, hooks, and diagnostics. Text output summarizes each mounted agent. <code>--json</code> prints <code>{ agents: [{ slug, ...projectInfo }] }</code>, with one entry per mounted slug. Use <code>validate</code>, not <code>info --json</code>, when a script needs an error exit status.</p><h2 id="validate" tabindex="-1">validate <a class="header-anchor" href="#validate" aria-label="Permalink to &quot;validate&quot;">​</a></h2><p><code>validate</code> checks the project and sets the exit 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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>validate</code> prints diagnostics for each agent and exits non-zero when any diagnostic has error severity. <code>serve</code> also refuses to start when errors are present. Warnings don&#39;t change the exit status.</p><h2 id="login-logout-whoami" tabindex="-1">login / logout / whoami <a class="header-anchor" href="#login-logout-whoami" aria-label="Permalink to &quot;login / logout / whoami&quot;">​</a></h2><p>Three commands manage the host&#39;s Cursor credential.</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 style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ke</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--key-name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--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;"> logout</span></span></code></pre></div><p><code>login</code> signs the host in to Cursor: browser sign-in mints a named, dashboard-revocable API key, and only the key is stored (the default name is <code>&lt;invoked command&gt; (&lt;hostname&gt;)</code>). It powers inference, the cloud runtime, and Cursor account MCP connections. <code>--key-name</code> changes the name of a browser-minted key. <code>login --api-key</code> validates and stores a key you already created.</p><p><code>whoami</code> shows which credential is active and why. <code>CURSOR_API_KEY</code> takes precedence over the stored login. <code>logout</code> removes the local credential file but doesn&#39;t revoke the API key. Revoke it in the Cursor dashboard when it should stop working.</p><p>Non-production backends: login and account RPCs honor <code>CURSOR_API_BASE_URL</code> while the SDK harness honors <code>CURSOR_BACKEND_URL</code>. Set both to the same URL, or keys minted on one backend are rejected by the other.</p><h2 id="update" tabindex="-1">update <a class="header-anchor" href="#update" aria-label="Permalink to &quot;update&quot;">​</a></h2><p><code>update</code> upgrades an installed copy to the latest published version.</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;"> update</span></span></code></pre></div><p>The command checks npm&#39;s <code>latest</code> tag, detects how the Agent SDK was installed, and runs the matching npm, pnpm, Yarn, or Bun upgrade command. It handles global installs and project dependencies. It doesn&#39;t prompt before running the package-manager command.</p><p>Source checkouts, <code>npx</code> or <code>pnpm dlx</code> caches, and unknown install layouts aren&#39;t changed. The command prints a manual upgrade hint instead.</p><p>Published installs also check for a newer version at most once every 24 hours and print an update warning on stderr. Source checkouts, CI, and commands with an explicit <code>--json</code> flag skip this automatic check.</p><h2 id="deploy" tabindex="-1">deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;deploy&quot;">​</a></h2><p><code>deploy</code> sends one or more agents to Cursor managed hosting.</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;"> deploy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --all]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https-url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--ref </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">git-ref</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">agent-path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
@@ -84,4 +84,4 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--events a,b,c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;*&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">action</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--comment </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--context </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--channel </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--host </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">host</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--port </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--secret </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,197)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,198)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.Cl14Jfo3.lean.js → reference_cli.md.TAaYU8br.lean.js}

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

package/dist/docs/assets/{reference_connections.md.Bwswbm6H.js → reference_connections.md.Cu3N-S3Q.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function h(l,s,o,p,r,k){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.linear.app/mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -6,19 +6,18 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Tokens come from env vars. Never hardcode them in the file.</p><h2 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></h2><p>For servers that speak OAuth, set <code>oauth: true</code> and authorize with the CLI. Tokens live in <code>~/.config/agent-serve/mcp-auth.json</code>. <code>--store</code> copies them onto the hosted deployment as <code>MCP_OAUTH_&lt;NAME&gt;_*</code> secrets.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  oauth: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  hostOnly: </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;">// model cannot call; host.mcp still can</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # browser PKCE → local mcp-auth.json</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --store</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # also upsert deployment secrets</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><p>Use <code>hostOnly: true</code> when only deterministic host tools should call the server (deploys, admin APIs). Account MCP (<code>cursorAccount: true</code>) stays the right choice for connectors already linked in the Cursor dashboard; omit <code>servers</code> (or pass <code>&quot;*&quot;</code>) to forward every connected connector.</p><h2 id="per-session-auth-auth" tabindex="-1">Per-session auth (<code>auth</code>) <a class="header-anchor" href="#per-session-auth-auth" aria-label="Permalink to &quot;Per-session auth (\`auth\`)&quot;">​</a></h2><p>For http/sse connections whose credential depends on <strong>who the session is for</strong> — a multi-tenant agent asserting the tenant it is acting for — declare an <code>auth</code> callback instead of static headers. It runs host-side at turn-build time with the session&#39;s <code>SessionInfo</code> and returns headers merged over the static ones:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --store</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # also upsert deployment secrets</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><p>Set <code>hostOnly: true</code> only when host tools should call the server and the model should not. Playground chat will not see those tools. Account MCP (<code>cursorAccount: true</code>) is the right choice for connectors already linked in the Cursor dashboard. Omit <code>servers</code> (or pass <code>&quot;*&quot;</code>) to forward every connected connector. If the model should call those tools by name on local turns, set <code>advertiseTools: true</code>.</p><h2 id="per-session-auth-auth" tabindex="-1">Per-session auth (<code>auth</code>) <a class="header-anchor" href="#per-session-auth-auth" aria-label="Permalink to &quot;Per-session auth (\`auth\`)&quot;">​</a></h2><p>For http/sse connections whose credential depends on <strong>who the session is for</strong> — a multi-tenant agent asserting the tenant it is acting for — declare an <code>auth</code> callback instead of static headers. It runs host-side at turn-build time with the session&#39;s <code>SessionInfo</code> and returns headers merged over the static ones:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> grantFor</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">(</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">)</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// optional — named tools instead of meta-tools</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The callback is evaluated on <strong>every local turn</strong> — reminder fires and post-restart follow-ups included — so the identity always comes from the session itself, never from state parked in memory. The model never sees a tenant parameter and can never choose the tenant. A callback that throws fails the turn: a turn never silently runs without the connection&#39;s identity. Local runtime only; cloud turns are refused. <code>host.mcp</code> calls from server tools keep the static headers only. Not combinable with <code>oauth: true</code> — the host OAuth provider owns the Authorization header.</p><p>Derive the identity from durable session facts — <code>session.auth</code>, <code>session.id</code>, or your channel&#39;s own session state. Do <strong>not</strong> key it off <code>session.continuationKey</code>: the HTTP channel rotates the continuation key after every accepted follow-up, so a tenant mapping keyed on it silently breaks mid-conversation. (Channels that mint stable, parseable tokens by design are the exception.)</p><p><code>auth</code> works attached or advertised. Advertised connections open per-operation clients with the evaluated headers. Attached connections ride the turn&#39;s SDK <code>mcpServers</code>, passed on <strong>every send</strong> rather than pinned on the cached per-session agent handle, so a rotated credential is live on the very next turn. The cost: when any attached connection has <code>auth</code>, <em>all</em> of the agent&#39;s attached connections are configured per send — the harness opens fresh MCP clients for them on each turn, so a stdio (<code>command</code>) server respawns per turn and loses any in-process state; keep stateful stdio servers out of agents that attach an auth&#39;d connection (or advertise the auth&#39;d connection instead). Workspace prewarm has no session, so it omits auth&#39;d connections rather than attaching them without an identity.</p><h2 id="advertise-a-connection-s-tools-by-name-advertisetools" tabindex="-1">Advertise a connection&#39;s tools by name (<code>advertiseTools</code>) <a class="header-anchor" href="#advertise-a-connection-s-tools-by-name-advertisetools" aria-label="Permalink to &quot;Advertise a connection&#39;s tools by name (\`advertiseTools\`)&quot;">​</a></h2><p>By default an attached MCP server&#39;s tools sit behind the harness&#39;s MCP meta-tools — nothing in the model&#39;s named toolset says the tools exist. Set <code>advertiseTools: true</code> and the engine instead lists the connection at turn-build time and synthesizes a named 1:1 passthrough server tool per entry — the server&#39;s own names, descriptions, and live schemas — merged into the authored <code>agent/tools/</code> catalog. The raw connection is then not attached to the model (it stays available on <code>host.mcp</code>), so each tool appears exactly once.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The callback is evaluated on <strong>every local turn</strong> — reminder fires and post-restart follow-ups included — so the identity always comes from the session itself, never from state parked in memory. The model never sees a tenant parameter and can never choose the tenant. A callback that throws fails the turn: a turn never silently runs without the connection&#39;s identity. Local runtime only; cloud turns are refused. <code>host.mcp</code> calls from server tools keep the static headers only. Not combinable with <code>oauth: true</code> — the host OAuth provider owns the Authorization header.</p><p>Derive the identity from durable session facts — <code>session.auth</code>, <code>session.id</code>, or your channel&#39;s own session state. Do <strong>not</strong> key it off <code>session.continuationKey</code>: the HTTP channel rotates the continuation key after every accepted follow-up, so a tenant mapping keyed on it silently breaks mid-conversation. (Channels that mint stable, parseable tokens by design are the exception.)</p><p><code>auth</code> works attached or advertised. Advertised connections open per-operation clients with the evaluated headers. Attached connections ride the turn&#39;s SDK <code>mcpServers</code>, passed on <strong>every send</strong> rather than pinned on the cached per-session agent handle, so a rotated credential is live on the very next turn. The cost: when any attached connection has <code>auth</code>, <em>all</em> of the agent&#39;s attached connections are configured per send — the harness opens fresh MCP clients for them on each turn, so a stdio (<code>command</code>) server respawns per turn and loses any in-process state; keep stateful stdio servers out of agents that attach an auth&#39;d connection (or advertise the auth&#39;d connection instead). Workspace prewarm has no session, so it omits auth&#39;d connections rather than attaching them without an identity.</p><h2 id="advertise-tools" tabindex="-1">Advertise a connection&#39;s tools by name (<code>advertiseTools</code>) <a class="header-anchor" href="#advertise-tools" aria-label="Permalink to &quot;Advertise a connection&#39;s tools by name (\`advertiseTools\`) {#advertise-tools}&quot;">​</a></h2><p>Attached MCP servers sit behind the harness MCP meta-tools. The model does not see names like <code>Datadog-search_datadog_dashboards</code> until you set <code>advertiseTools: true</code>. Use that flag when playground or local chat should call the tools by name.</p><p>The engine lists the connection at turn-build time and synthesizes a named 1:1 passthrough server tool per entry, using the server&#39;s names, descriptions, and live schemas. Those merge into the authored <code>agent/tools/</code> catalog. The raw connection is then not attached to the model (it stays available on <code>host.mcp</code>), so each tool appears exactly once.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://api.cursor.com/v1/mcp/plugins&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">session</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ headers: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tenantHeaders</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(session) }),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Fail-closed, by design: a <code>listTools</code> failure, an invalid tool name, or a name collision (with an authored tool or another advertised connection) fails the turn — a turn never silently runs with a shrunken toolset. Listing runs once per turn, so point this at endpoints that answer <code>tools/list</code> cheaply. Connections with <code>auth</code> are listed and called through one-off clients carrying that session&#39;s headers; auth-less ones (including Cursor account connections) go through the shared host registry. Local runtime only, like all server tools, and not combinable with <code>hostOnly</code> (advertising puts the tools in the model&#39;s toolset; <code>hostOnly</code> means off the model). Advertised tools do not appear on surfaces built from the static catalog (<code>info</code>, the peer-agent MCP server, cloud <code>agentsdk-tools</code>) and cannot be invoked via direct tool calls.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Fail-closed, by design: a <code>listTools</code> failure, an invalid tool name, or a name collision (with an authored tool or another advertised connection) fails the turn. A turn never silently runs with a shrunken toolset. Listing runs once per turn, so point this at endpoints that answer <code>tools/list</code> cheaply. Connections with <code>auth</code> are listed and called through one-off clients carrying that session&#39;s headers. Auth-less ones (including Cursor account connections) go through the shared host registry. Local runtime only, like all server tools, and not combinable with <code>hostOnly</code>. Advertising puts the tools in the model&#39;s toolset. <code>hostOnly</code> keeps them off the model. <code>GET /v1/info</code> reports <code>advertiseTools</code> on the connection. The per-tool list is built per turn, not on the static catalog, the peer-agent MCP server, or cloud <code>agentsdk-tools</code>, and those advertised tools cannot be invoked via direct tool calls.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--import&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;tsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp/units-server.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // env, cwd</span></span>
@@ -31,18 +30,26 @@ import{_ as i,c as a,o as e,ag as t}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:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="cursor-account-mcp-connection" tabindex="-1">Cursor account MCP connection <a class="header-anchor" href="#cursor-account-mcp-connection" aria-label="Permalink to &quot;Cursor account MCP connection&quot;">​</a></h2><p><code>{ cursorAccount: true }</code> forwards the MCP connectors the signed-in Cursor account already authorized (dashboard → MCP): Linear, Notion, Slack, and the rest. You don&#39;t configure tokens. Every tool runs on the Cursor backend with the account&#39;s stored OAuth credentials, so raw tokens never reach the serve host, session workspaces, or traces.</p><p>By default the agent gets <strong>every</strong> connected HTTP/SSE connector on the account. Pass <code>servers: &quot;*&quot;</code> (or <code>[&quot;*&quot;]</code>) for the same all-connectors behavior in an explicit form. Pass a name list when you want a smaller set.</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/cursor.ts: every connected connector</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="cursor-account-mcp-connection" tabindex="-1">Cursor account MCP connection <a class="header-anchor" href="#cursor-account-mcp-connection" aria-label="Permalink to &quot;Cursor account MCP connection&quot;">​</a></h2><p><code>{ cursorAccount: true }</code> forwards the MCP connectors the signed-in Cursor account already authorized (dashboard → MCP): Linear, Notion, Slack, and the rest. You don&#39;t configure tokens. Every tool runs on the Cursor backend with the account&#39;s stored OAuth credentials, so raw tokens never reach the serve host, session workspaces, or traces.</p><p>By default the agent gets <strong>every</strong> connected HTTP/SSE connector on the account. Pass <code>servers: &quot;*&quot;</code> (or <code>[&quot;*&quot;]</code>) for the same all-connectors behavior in an explicit form. Pass a name list when you want a smaller set.</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/account.ts: every connected connector</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// same, spelled out:</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, servers: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;*&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  servers: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;*&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// only Linear:</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><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>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). <code>serve</code> fails fast at startup otherwise, and logs each connector&#39;s live status (<code>connected</code>, <code>needsAuth</code>, <code>error</code>) as it starts.</p><p>Local turns and host-side calls go through a loopback bridge guarded by a per-startup secret. Cloud-runtime turns reach the same bridge through the serve <code>--public-url</code>, so <code>servers</code> filters apply there too. A cloud-capable agent that combines a concrete <code>servers</code> allowlist with no <code>--public-url</code> fails at startup rather than running unfiltered. Backend execution covers the account&#39;s HTTP/SSE servers. Stdio servers can&#39;t run server-side, so author a <code>{ command }</code> MCP connection for those.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>Whoever can talk to the agent can drive these connectors, because they are ordinary agent tools. <code>serve</code> refuses to start when <code>--allow-anonymous</code> is combined with account MCP connections unless you also pass <code>--allow-anonymous-cursor-account-mcp</code> (trusted boundary only; for example an SSO proxy or the hosted alias token). Prefer <code>--bearer-token</code> on shared hosts.</p></div><h2 id="peer-mcp-connection" tabindex="-1">Peer MCP connection <a class="header-anchor" href="#peer-mcp-connection" aria-label="Permalink to &quot;Peer MCP connection&quot;">​</a></h2><p><code>{ agent: &quot;&lt;slug&gt;&quot; }</code> addresses another agent mounted on the same serve host. The model gets the peer&#39;s <code>ask</code> and <code>check</code> (and <code>call_tool</code>) tools and can delegate work to 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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  advertiseTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Name the file <code>account.ts</code>. <code>cursor.ts</code> collides with the IDE <code>cursor</code> MCP namespace. <code>advertiseTools: true</code> puts connector tools on local turns by name. Without it they sit behind harness meta-tools.</p><p>The host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). <code>serve</code> fails fast at startup otherwise, and logs each connector&#39;s live status (<code>connected</code>, <code>needsAuth</code>, <code>error</code>) as it starts.</p><p>Local turns and host-side calls go through a loopback bridge guarded by a per-startup secret. Cloud-runtime turns reach the same bridge through the serve <code>--public-url</code>, so <code>servers</code> filters apply there too. A cloud-capable agent that combines a concrete <code>servers</code> allowlist with no <code>--public-url</code> fails at startup rather than running unfiltered. Backend execution covers the account&#39;s HTTP/SSE servers. Stdio servers can&#39;t run server-side, so author a <code>{ command }</code> MCP connection for those.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>Whoever can talk to the agent can drive these connectors, because they are ordinary agent tools. <code>serve</code> refuses to start when <code>--allow-anonymous</code> is combined with account MCP connections unless you also pass <code>--allow-anonymous-cursor-account-mcp</code> (trusted boundary only; for example an SSO proxy or the hosted alias token). Prefer <code>--bearer-token</code> on shared hosts.</p></div><h2 id="peer-mcp-connection" tabindex="-1">Peer MCP connection <a class="header-anchor" href="#peer-mcp-connection" aria-label="Permalink to &quot;Peer MCP connection&quot;">​</a></h2><p><code>{ agent: &quot;&lt;slug&gt;&quot; }</code> addresses another agent mounted on the same serve host. The model gets the peer&#39;s <code>ask</code> and <code>check</code> (and <code>call_tool</code>) tools and can delegate work to 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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agent: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Delegate weather questions to the weather agent.&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>Unknown slugs and self-references fail <code>serve</code> at startup. Resolution (loopback versus <code>--public-url</code>), loop caveats, and the delegation model are in the <a href="./../guides/agent-to-agent.html">Agent-to-agent guide</a>.</p><h2 id="every-mcp-connection-is-available-in-three-places" tabindex="-1">Every MCP connection is available in three places <a class="header-anchor" href="#every-mcp-connection-is-available-in-three-places" aria-label="Permalink to &quot;Every MCP connection is available in three places&quot;">​</a></h2><p>One authored MCP connection serves three consumers.</p><ol><li><p><strong>Cursor agent:</strong> Local or cloud turns see the MCP connection through SDK <code>mcpServers</code>, and the model calls its tools directly.</p></li><li><p><strong>Server tools:</strong> Deterministic host code composes MCP calls through <code>ctx.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:#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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Unknown slugs and self-references fail <code>serve</code> at startup. Resolution (loopback versus <code>--public-url</code>), loop caveats, and the delegation model are in the <a href="./../guides/agent-to-agent.html">Agent-to-agent guide</a>.</p><h2 id="every-mcp-connection-is-available-in-three-places" tabindex="-1">Every MCP connection is available in three places <a class="header-anchor" href="#every-mcp-connection-is-available-in-three-places" aria-label="Permalink to &quot;Every MCP connection is available in three places&quot;">​</a></h2><p>One authored MCP connection serves three consumers.</p><ol><li><p><strong>Cursor agent:</strong> Attached connections ride SDK <code>mcpServers</code> behind harness MCP meta-tools. Set <code>advertiseTools: true</code> so local turns see named tools. <code>hostOnly</code> keeps the connection off the model.</p></li><li><p><strong>Server tools:</strong> Deterministic host code composes MCP calls through <code>ctx.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:#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>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Search Linear issues.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ query: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">query</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>
@@ -54,4 +61,4 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {});</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result);</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, <code>--store</code>, <code>hostOnly</code></li><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,46)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, <code>--store</code>, <code>hostOnly</code></li><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,48)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_connections.md.Bwswbm6H.lean.js → reference_connections.md.Cu3N-S3Q.lean.js}

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

package/dist/docs/assets/{reference_sessions.md.DBVFi2Sx.js → reference_sessions.md.B0DdlM-K.js}

@@ -4,5 +4,5 @@ import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const u
 <span class="line"><span>  sessions/&lt;id&gt;/workspace/         # the harness cwd</span></span>
 <span class="line"><span>  traces/&lt;sessionId&gt;.ndjson        # written by \`run\`</span></span>
 <span class="line"><span>  runner/                          # Cursor SDK conversation store</span></span>
-<span class="line"><span>  tool-calls/&lt;callId&gt;/             # ephemeral deterministic-call workspaces</span></span></code></pre></div><p>Deleting a session directory removes the session from the server: it disappears from listings and can no longer be streamed or continued. The <code>runner/</code> store keeps its own conversation copy until you remove it. Cloud conversations remain on the Cursor backend.</p><p>Change the root with <code>--state-root</code> or <code>stateRoot</code>. Keep it outside repositories whose parent rules shouldn&#39;t reach the agent. See <a href="./../concepts.html#what-files-can-a-local-session-access">local session workspaces</a>.</p><h2 id="how-do-i-inspect-a-saved-event-stream" tabindex="-1">How do I inspect a saved event stream? <a class="header-anchor" href="#how-do-i-inspect-a-saved-event-stream" aria-label="Permalink to &quot;How do I inspect a saved event stream?&quot;">​</a></h2><p>Use <code>trajectory</code> with a trace or session event file:</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .agent-serve/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span>
+<span class="line"><span>  tool-calls/&lt;callId&gt;/             # ephemeral deterministic-call workspaces</span></span></code></pre></div><p>Deleting a session directory removes the session from the server: it disappears from listings and can no longer be streamed or continued. The <code>runner/</code> store keeps its own conversation copy until you remove it. Cloud conversations remain on the Cursor backend.</p><p>Change the root with <code>--state-root</code> or <code>stateRoot</code>. Nested git checkouts already default <code>local.cwd</code> outside the enclosing repo. See <a href="./../concepts.html#what-files-can-a-local-session-access">local session workspaces</a>.</p><h2 id="how-do-i-inspect-a-saved-event-stream" tabindex="-1">How do I inspect a saved event stream? <a class="header-anchor" href="#how-do-i-inspect-a-saved-event-stream" aria-label="Permalink to &quot;How do I inspect a saved event stream?&quot;">​</a></h2><p>Use <code>trajectory</code> with a trace or session event file:</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .agent-serve/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">stateRoo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/sessions/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/events.ndjson</span></span></code></pre></div><p>The command prints tool calls, the reply, and token usage in the same JSON shape as <code>run</code>. Use <strong>Open trace</strong> in the playground for a visual view.</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="./http-api.html">HTTP API</a></li><li><a href="./hooks.html">Hooks</a></li><li><a href="./../ab.html">Live A/B metrics</a></li><li><a href="./../concepts.html">How the Agent SDK works</a></li></ul>`,45)])])}const k=t(n,[["render",i]]);export{u as __pageData,k as default};

package/dist/docs/assets/{reference_tools.md.Wmvb7Lob.js → reference_tools.md.DTg_kEsx.js}

@@ -34,7 +34,7 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">message=$(python3 -c &#39;import json,sys; print(json.load(sys.stdin)[&quot;message&quot;])&#39;)</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">printf &#39;%s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\\\</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">n&#39; &quot;$message&quot;</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>On the local runtime, scripts land under <code>.agent-serve/tools/</code> in the session workspace with a catalog in <code>AGENTS.md</code>. On cloud, the catalog and script bodies travel on the first prompt.</p><h2 id="tools-from-an-mcp-connection-advertised-by-name" tabindex="-1">Tools from an MCP connection, advertised by name <a class="header-anchor" href="#tools-from-an-mcp-connection-advertised-by-name" aria-label="Permalink to &quot;Tools from an MCP connection, advertised by name&quot;">​</a></h2><p>Authored <code>agent/tools/</code> files are one catalog for every session. When the tools should come from an MCP server — including per-tenant toolsets resolved at runtime — declare the connection with <code>advertiseTools: true</code> (plus per-session <code>auth</code> when the credential depends on who the session is for) and the engine synthesizes named 1:1 passthrough server tools from the connection&#39;s live <code>listTools</code> on every local turn. See <a href="./connections.html#advertise-a-connection-s-tools-by-name-advertisetools">MCP Connections</a>. Advertised tools ride the same execution path as authored server tools, but cannot be invoked via <a href="#call-a-tool-without-a-model-turn">direct tool calls</a>.</p><h2 id="gate-a-tool-on-human-approval" tabindex="-1">Gate a tool on human approval <a class="header-anchor" href="#gate-a-tool-on-human-approval" aria-label="Permalink to &quot;Gate a tool on human approval&quot;">​</a></h2><p>A server tool can require a person to sign off before it runs. Set <code>needsApproval</code> to <code>true</code>, or to a predicate over the validated input:</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;"> defineTool</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>On the local runtime, scripts land under <code>.agent-serve/tools/</code> in the session workspace with a catalog in <code>AGENTS.md</code>. On cloud, the catalog and script bodies travel on the first prompt.</p><h2 id="tools-from-an-mcp-connection-advertised-by-name" tabindex="-1">Tools from an MCP connection, advertised by name <a class="header-anchor" href="#tools-from-an-mcp-connection-advertised-by-name" aria-label="Permalink to &quot;Tools from an MCP connection, advertised by name&quot;">​</a></h2><p>Authored <code>agent/tools/</code> files are one catalog for every session. When the tools should come from an MCP server — including per-tenant toolsets resolved at runtime — declare the connection with <code>advertiseTools: true</code> (plus per-session <code>auth</code> when the credential depends on who the session is for) and the engine synthesizes named 1:1 passthrough server tools from the connection&#39;s live <code>listTools</code> on every local turn. See <a href="./connections.html#advertise-tools">MCP Connections</a>. Advertised tools ride the same execution path as authored server tools, but cannot be invoked via <a href="#call-a-tool-without-a-model-turn">direct tool calls</a>.</p><h2 id="gate-a-tool-on-human-approval" tabindex="-1">Gate a tool on human approval <a class="header-anchor" href="#gate-a-tool-on-human-approval" aria-label="Permalink to &quot;Gate a tool on human approval&quot;">​</a></h2><p>A server tool can require a person to sign off before it runs. Set <code>needsApproval</code> to <code>true</code>, or to a predicate over the validated input:</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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Promote a verified build to an environment.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  needsApproval: </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;">// or: (input) =&gt; input.environment === &quot;production&quot;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

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

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

package/dist/docs/assets/{scaffolding-agents.md.CrWSA0Ko.lean.js → scaffolding-agents.md.CiGsJ1aw.lean.js}

@@ -1 +1 @@
-import{_ as a,c as o,o as t,ag as l}from"./chunks/framework.CAZyNGu9.js";const f=JSON.parse('{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent.","frontmatter":{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent."},"headers":[],"relativePath":"scaffolding-agents.md","filePath":"scaffolding-agents.md"}'),r={name:"scaffolding-agents.md"};function s(i,e,n,d,h,c){return t(),o("div",null,[...e[0]||(e[0]=[l("",34)])])}const p=a(r,[["render",s]]);export{f as __pageData,p as default};
+import{_ as o,c as a,o as t,ag as l}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent.","frontmatter":{"title":"Scaffold an agent with Cursor","description":"Use the bundled create-agent skill to plan, build, and verify a new agent."},"headers":[],"relativePath":"scaffolding-agents.md","filePath":"scaffolding-agents.md"}'),s={name:"scaffolding-agents.md"};function i(r,e,n,d,c,h){return t(),a("div",null,[...e[0]||(e[0]=[l("",34)])])}const f=o(s,[["render",i]]);export{p as __pageData,f as default};

package/dist/docs/assets/troubleshooting.md.DQ-hYuZT.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as d}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,c,h,l){return a(),o("div",null,[...e[0]||(e[0]=[d('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with four checks, in order:</p><ol><li>Project discovery: <code>agent-sdk validate --dir .</code></li><li>Whether the serve process is running</li><li>What the playground or HTTP API shows</li><li>The session event stream (trace)</li></ol><p>Match your symptom below. Keep the commands as <code>agent-sdk</code>; see <a href="/docs/#run-the-cli">Run the CLI</a> if you still need an alias.</p><h2 id="what-if-serve-or-the-playground-looks-wrong" tabindex="-1">What if serve or the playground looks wrong? <a class="header-anchor" href="#what-if-serve-or-the-playground-looks-wrong" aria-label="Permalink to &quot;What if serve or the playground looks wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> won&#39;t start</td><td>Run <code>agent-sdk validate --dir .</code> and fix the reported errors.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>The UI needs a running <code>serve</code> process. Building the playground assets alone is not enough.</td></tr><tr><td>Edits to the playground don&#39;t show up</td><td>Use <code>serve --dev</code> and open the printed playground HMR URL (often port <code>5273</code>), not only the static <code>:3000</code> URL.</td></tr><tr><td>Sessions exist on disk but the playground list is empty</td><td>The list shows sessions for the authenticated caller. In <code>--dev</code> on loopback the list is wider. Otherwise open <code>/&lt;slug&gt;/playground?sessionId=ses_…</code> or inspect <code>sessions/</code> under your state root.</td></tr><tr><td>Port 3000 or 5273 is already in use</td><td>For the default serve port, the CLI tries the next free port and prints a notice. Pass <code>--port</code> to pick one, or <code>--port 0</code> for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port.</td></tr></tbody></table><h2 id="what-if-a-model-turn-goes-wrong" tabindex="-1">What if a model turn goes wrong? <a class="header-anchor" href="#what-if-a-model-turn-goes-wrong" aria-label="Permalink to &quot;What if a model turn goes wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Built-in file reads and greps fail; the turn retries for a long time</td><td>Run under Node 22.13+ (or <code>tsx</code>), never Bun. Look for <code>NGHTTP2_FRAME_SIZE_ERROR</code> in logs.</td></tr><tr><td>The turn fails immediately with an API-key error</td><td>Sign in with <code>agent-sdk login</code>, or set <code>CURSOR_API_KEY</code>. Discovery, <code>info</code>, <code>call</code>, and serve bring-up work without a key; model turns need one.</td></tr><tr><td>Replies quote rules or <code>AGENTS.md</code> from outside your agent project</td><td>The session workspace inherited parent-folder config. Nested git checkouts default <code>local.cwd</code> to <code>~/.cache/agent-serve/&lt;dir&gt;</code>. Point <code>defineAgent({ local: { cwd } })</code> at a checkout only when the agent should inherit that tree, or set <code>--state-root</code> to a clean directory (for example under <code>/tmp</code>).</td></tr><tr><td>Yellow box shows Datadog/Linear tools, but the model lists <code>GetDynamicTools</code> / IDE <code>cursor</code> tools and never calls them</td><td>Attached MCP sits behind harness meta-tools, or <code>hostOnly</code> hid the connection, or the harness cwd is still inside another checkout. Set <code>advertiseTools: true</code> for named tools on local turns. Check <code>GET /v1/info</code> <code>local.cwd</code> and <code>connections[].advertiseTools</code>.</td></tr><tr><td>Server tools, skills, or workspace seed files never appear</td><td>The agent runtime is <code>cloud</code>. Those features apply on the local runtime. <code>validate</code> warns when this combination is present.</td></tr><tr><td><code>validate</code> and <code>run</code> succeed, but typecheck fails in CI</td><td>The CLI runs TypeScript with type-stripping only. Keep tool <code>execute</code> return types as object literals or <code>type</code> aliases, not <code>interface</code> types.</td></tr><tr><td>Login works, but turns are rejected when using custom API hosts</td><td>Point login and model traffic at the same host (<code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>). A key from one host is rejected by the other.</td></tr></tbody></table><h2 id="what-if-the-http-api-returns-an-error" tabindex="-1">What if the HTTP API returns an error? <a class="header-anchor" href="#what-if-the-http-api-returns-an-error" aria-label="Permalink to &quot;What if the HTTP API returns an error?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>409</code> on a follow-up message</td><td>Refresh the <code>continuationToken</code> (it rotates on each accepted follow-up), wait if the session is busy, or confirm the session is a chat session (task and schedule sessions are not followable).</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>Wait for the model turn to finish, or omit <code>--session</code> for a one-off call.</td></tr><tr><td><code>403</code> on stream or follow-up</td><td>Use the same auth identity that created the session. Off localhost, pass <code>--bearer-token</code> and send it on every request.</td></tr><tr><td>Works on localhost; blocked through a tunnel or LAN</td><td>Default auth allows only direct loopback callers. Share the host with <code>--bearer-token &lt;secret&gt;</code> (or authored <code>bearerAuth</code>). Use <code>--allow-anonymous</code> only on a trusted private network.</td></tr><tr><td>A channel route fails to compile with a schema type error</td><td><code>GET</code> routes need a Zod <code>querySchema</code>. <code>POST</code> / <code>PUT</code> / <code>PATCH</code> need a Zod <code>bodySchema</code>. Use <code>z.object({})</code> or <code>z.unknown()</code> for open shapes.</td></tr></tbody></table><h2 id="what-if-github-webhooks-misbehave" tabindex="-1">What if GitHub webhooks misbehave? <a class="header-anchor" href="#what-if-github-webhooks-misbehave" aria-label="Permalink to &quot;What if GitHub webhooks misbehave?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery, but the hook was created</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command. The forwarder uses your <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …</code></td></tr><tr><td><code>Hook already exists</code> when starting a forwarder</td><td>GitHub allows one forwarder per repo. Run a single <code>github forward --dir &lt;parent&gt;</code> and stop stale forwarders.</td></tr><tr><td>Deliveries rejected outside <code>--dev</code></td><td>Set <code>GITHUB_WEBHOOK_SECRET</code> on the server and on the signer. Without a secret, the channel stays loopback-only.</td></tr><tr><td>You lack repo admin and can&#39;t forward</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>. It needs pull access only and posts signed test payloads.</td></tr></tbody></table><h2 id="what-if-slack-stays-quiet" tabindex="-1">What if Slack stays quiet? <a class="header-anchor" href="#what-if-slack-stays-quiet" aria-label="Permalink to &quot;What if Slack stays quiet?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs show <code>channel idle … missing credentials</code></td><td>Expected when tokens are missing. Run <code>agent-sdk slack create --dir &lt;agent&gt;</code> to provision the app and write the tokens, or <code>agent-sdk slack init --manual --dir &lt;agent&gt;</code> and paste the manifests at api.slack.com. Then set <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> per agent and run <code>agent-sdk slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td><code>slack create</code> reports the app needs admin approval</td><td>Open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link; the same URL is <strong>Send a reminder</strong> after you submit). Managed install does not file the request. Keep the CLI running, then click <strong>Retry</strong> in the dashboard after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Default engagement is mentions and DMs only. Enable <code>engagement.channelPosts</code> with an allowlist, and subscribe the app to <code>message.channels</code> / <code>message.groups</code>.</td></tr><tr><td>Approve / Deny buttons do nothing</td><td>Channels that post approval cards need <code>toolApprovals: true</code>. Recreate the app with <code>slack create</code> if interactivity is off.</td></tr></tbody></table><h2 id="what-if-host-mcp-oauth-fails" tabindex="-1">What if host MCP OAuth fails? <a class="header-anchor" href="#what-if-host-mcp-oauth-fails" aria-label="Permalink to &quot;What if host MCP OAuth fails?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>The connection file needs <code>oauth: true</code>, or you passed the wrong connection name to <code>agent-sdk mcp oauth</code>.</td></tr><tr><td>Local auth works; hosted calls unauthorized</td><td>Run <code>agent-sdk mcp oauth &lt;name&gt; --store</code>, confirm names with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy.</td></tr><tr><td>Model asks for <code>mcp_auth</code> or IDE MCP for a privileged server</td><td>That connection is <code>hostOnly</code>. Call it from a host tool via <code>ctx.host.mcp</code>, and update instructions.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> and <a href="./../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-if-a-secret-showed-up-in-a-terminal-transcript" tabindex="-1">What if a secret showed up in a terminal transcript? <a class="header-anchor" href="#what-if-a-secret-showed-up-in-a-terminal-transcript" aria-label="Permalink to &quot;What if a secret showed up in a terminal transcript?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>secrets set … NAME=VALUE</code> in an agent-captured terminal or shell history</td><td>Rotate the secret at the provider. Set it again with names only: <code>agent-sdk secrets set &lt;slug&gt; NAME</code> (hidden prompt) or pipe/redirect the value. <code>NAME=VALUE</code> requires <code>--from-argv</code> and still leaks into argv.</td></tr><tr><td>Alias token printed during first deploy or <code>rotate-token</code></td><td>Treat it as exposed if the transcript left your machine. Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new token outside agent transcripts, and update callers.</td></tr><tr><td>Someone verified a secret with <code>echo</code> / <code>printenv</code></td><td>Rotate it. Confirm presence with <code>agent-sdk secrets list &lt;slug&gt;</code> (names only), then redeploy and test the feature.</td></tr></tbody></table><h2 id="what-if-schedules-reminders-or-approvals-stall" tabindex="-1">What if schedules, reminders, or approvals stall? <a class="header-anchor" href="#what-if-schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;What if schedules, reminders, or approvals stall?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Dev mode does not auto-fire. Trigger with <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code> or <code>POST /&lt;slug&gt;/v1/dev/reminders/&lt;id&gt;</code> (list reminders at <code>GET /v1/dev/reminders</code>).</td></tr><tr><td>A pending tool approval disappeared after restart</td><td>Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again.</td></tr><tr><td>A reminder is disarmed after restart (<code>handler_lost_on_restart</code>)</td><td>Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders.</td></tr></tbody></table><h2 id="how-do-i-read-a-session-trace" tabindex="-1">How do I read a session trace? <a class="header-anchor" href="#how-do-i-read-a-session-trace" aria-label="Permalink to &quot;How do I read a session trace?&quot;">​</a></h2><p>Look at <code>actions.requested</code> / <code>action.result</code> pairs for the tool trajectory. Count calls by tool name before blaming latency. Separate host-side work (channel <code>callTool</code>, preparation) from tools the model chose.</p><p><code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> means a follow-up or stop ended the turn on purpose.</p><p>If the model reads outside the session workspace, the prepared files don&#39;t match what the instructions expect. Fix the layout. See <a href="./hillclimbing.html">Hillclimbing</a>.</p><p><code>agent-sdk trajectory --events &lt;file&gt;</code> summarizes any saved NDJSON stream. The playground <strong>Open trace</strong> control does the same visually.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./concepts.html">Concepts</a>: the model behind these symptoms</li><li><a href="./hillclimbing.html">Hillclimbing</a>: when the agent runs but underperforms</li><li><a href="./deployment.html">Deployment</a>: auth and state on shared hosts</li></ul>',28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};