@cursor/july 0.1.109 → 0.1.112

package/dist/docs/assets/reference_extensions.md.ZAVUyuEX.js

@@ -1,62 +0,0 @@
-import{_ as t,c as e,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Extensions","description":"Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/.","frontmatter":{"title":"Extensions","description":"Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),n={name:"reference/extensions.md"};function o(l,s,d,h,p,r){return a(),e("div",null,[...s[0]||(s[0]=[i(`<h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages the same contributions an agent authors under <code>agent/</code> and installs them as one unit. You mount it with a single file under <code>agent/extensions/</code>, and its contributions join the agent under a namespace. The package updates like any other dependency; nothing is copied into your project. A Cursor plugin mounts the same way; see <a href="#mount-a-cursor-plugin">Mount a Cursor plugin</a>.</p><p>Extensions are native to the Agent SDK. Slot files use the <code>@cursor/july</code> helpers, so a package built on another agent framework fails <code>agent-sdk validate</code> until you rewrite it onto <code>@cursor/july</code>.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package, then add one file. The filename is the namespace.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/ci.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ci </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@acme/ci-triage&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;"> ci</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ org: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, token: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BUILDKITE_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre></div><p>Every contribution is exposed as <code>&lt;namespace&gt;__&lt;name&gt;</code>. A <code>failed_jobs</code> tool from this mount runs in the agent as <code>ci__failed_jobs</code>, and a <code>triage</code> skill loads as <code>ci__triage</code>. <code>agent-sdk info</code> lists each mount with what it contributed, and <code>GET /v1/info</code> returns the same under <code>extensions</code>.</p><p>Pass the configuration the extension asks for. The extension validates it when the agent loads, so a missing or mistyped field fails <code>agent-sdk validate</code> instead of a tool call later.</p><p>Namespaces follow the tool-name rule, and <code>__</code> is reserved: an authored <code>agent/tools/ci__failed_jobs.ts</code> fails discovery, so nothing outside a mount can pose as one of its tools.</p><h2 id="what-an-extension-can-contribute" tabindex="-1">What an extension can contribute <a class="header-anchor" href="#what-an-extension-can-contribute" aria-label="Permalink to &quot;What an extension can contribute&quot;">​</a></h2><p>An extension tree uses the same slots as <a href="./project-layout.html"><code>agent/</code></a>. Each shareable contribution lands on the agent under the mount&#39;s namespace:</p><table tabindex="0"><thead><tr><th>Path</th><th>Becomes</th></tr></thead><tbody><tr><td><code>tools/&lt;name&gt;.ts</code></td><td>tool <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>skills/&lt;name&gt;</code></td><td>skill <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>mcp-connections/&lt;name&gt;.ts</code></td><td>connection <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>host-connections/&lt;name&gt;.ts</code></td><td>host connection <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>hooks/&lt;name&gt;.ts</code></td><td>hook <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>channels/&lt;name&gt;.ts</code></td><td>channel <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>schedules/&lt;name&gt;</code></td><td>schedule <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>subagents/&lt;id&gt;/</code></td><td>subagent <code>&lt;ns&gt;__&lt;id&gt;</code></td></tr><tr><td><code>instructions.md</code> / <code>.ts</code> / dir</td><td>appended to the agent&#39;s system prompt</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>seeded into each local session workspace</td></tr><tr><td><code>artifacts.ts</code></td><td>artifact kinds <code>&lt;ns&gt;__&lt;kind&gt;</code></td></tr></tbody></table><p>The root agent still needs its own <code>instructions.md</code>. Extension instructions are extra fragments, not a substitute.</p><p><code>httpChannel()</code> stays on the agent. An extension authors <code>defineChannel</code> only; a file named <code>http.ts</code> becomes <code>&lt;ns&gt;__http</code>.</p><p>These stay on the agent that mounts the extension. Each is a singleton or is outside discovery:</p><table tabindex="0"><thead><tr><th>Path</th><th>Why it stays on the agent</th></tr></thead><tbody><tr><td><code>agent.ts</code></td><td>One <code>defineAgent</code> runtime per agent</td></tr><tr><td><code>storage.ts</code></td><td>One <code>host.kv</code> / <code>host.files</code> backend</td></tr><tr><td><code>otel.ts</code></td><td>One OTLP exporter</td></tr><tr><td><code>playground/</code></td><td>Custom chips are a Vite glob of the agent tree, not a discovery walk</td></tr><tr><td><code>extensions/</code></td><td>Nested mounts are not loaded</td></tr><tr><td><code>sandbox.ts</code></td><td>Custom sandbox backends stay on the agent</td></tr></tbody></table><p><code>agent-sdk validate</code> warns when a tree carries those paths.</p><h2 id="adjust-a-mounted-extension" tabindex="-1">Adjust a mounted extension <a class="header-anchor" href="#adjust-a-mounted-extension" aria-label="Permalink to &quot;Adjust a mounted extension&quot;">​</a></h2><p>To replace or remove a contribution, mount the extension as a directory and overlay the slot you want to change.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/extensions/ci/</span></span>
-<span class="line"><span>├── extension.ts        # the mount: export default ci({ ... })</span></span>
-<span class="line"><span>├── tools/</span></span>
-<span class="line"><span>│   ├── job_log.ts      # replaces ci__job_log with your own defineTool</span></span>
-<span class="line"><span>│   └── retry_job.ts    # export default disableTool() removes ci__retry_job</span></span>
-<span class="line"><span>├── hooks/</span></span>
-<span class="line"><span>│   └── audit.ts        # export default disableHook() removes ci__audit</span></span>
-<span class="line"><span>└── skills/</span></span>
-<span class="line"><span>    └── triage.ts       # export default disableSkill() removes ci__triage</span></span></code></pre></div><p>Use the extension&#39;s own names inside the directory, without the namespace. A file with a name the extension doesn&#39;t contribute adds a new contribution under the namespace. Each helper comes from <code>@cursor/july/extensions</code> and fails discovery when it names a contribution the extension doesn&#39;t have, so a typo can&#39;t silently keep it alive.</p><table tabindex="0"><thead><tr><th>Slot</th><th>Helper</th></tr></thead><tbody><tr><td><code>tools/&lt;name&gt;.ts</code></td><td><code>disableTool()</code></td></tr><tr><td><code>mcp-connections/&lt;name&gt;.ts</code> / <code>host-connections/&lt;name&gt;.ts</code></td><td><code>disableConnection()</code></td></tr><tr><td><code>skills/&lt;name&gt;.ts</code></td><td><code>disableSkill()</code></td></tr><tr><td><code>hooks/&lt;name&gt;.ts</code></td><td><code>disableHook()</code></td></tr><tr><td><code>channels/&lt;name&gt;.ts</code></td><td><code>disableChannel()</code></td></tr><tr><td><code>schedules/&lt;name&gt;.ts</code></td><td><code>disableSchedule()</code></td></tr><tr><td><code>subagents/&lt;id&gt;.ts</code></td><td><code>disableSubagent()</code></td></tr><tr><td><code>instructions.ts</code></td><td><code>disableInstructions()</code></td></tr><tr><td><code>artifacts.ts</code></td><td><code>disableArtifacts()</code></td></tr></tbody></table><p><code>disable()</code> is the same brand as the slot helpers above and works in any of those files.</p><p>A Cursor plugin mount overlays its MCP servers the same way; see below.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p>A Cursor plugin is a directory with <code>.cursor-plugin/plugin.json</code> (or <code>.claude-plugin/plugin.json</code>, or <code>plugin.json</code>) and any of <code>skills/</code>, <code>commands/</code>, <code>agents/</code>, and <code>mcp.json</code>. Copy the plugin into your project and mount it with <code>cursorPlugin</code>. The filename is the namespace, as with any extension.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/notion.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorPlugin } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&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;"> cursorPlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugins/notion-workspace&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// relative to the project root</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  variables: { NOTION_TOKEN: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NOTION_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The plugin joins the agent under that namespace:</p><table tabindex="0"><thead><tr><th>Plugin content</th><th>Becomes</th></tr></thead><tbody><tr><td><code>skills/&lt;name&gt;/SKILL.md</code></td><td>skill <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>commands/&lt;name&gt;.md</code></td><td>skill <code>notion__&lt;name&gt;</code>, since a command is a procedure the model runs on request</td></tr><tr><td><code>agents/&lt;name&gt;.md</code></td><td>subagent <code>notion__&lt;name&gt;</code></td></tr><tr><td>MCP servers in <code>mcp.json</code> or the manifest</td><td>connection <code>notion__&lt;server&gt;</code></td></tr></tbody></table><p><code>variables</code> fills the <code>\${NAME}</code> placeholders the plugin&#39;s MCP config declares; names you leave out come from the environment by exact name. A placeholder nothing fills fails <code>agent-sdk validate</code>, so a server never attaches half configured. A server that declares an OAuth client authorizes through <a href="./../guides/mcp-oauth.html">host MCP OAuth</a> as <code>agent-sdk mcp oauth notion__&lt;server&gt;</code>; its secret names collapse the namespace separator, so <code>notion__notion</code> stores <code>MCP_OAUTH_NOTION_NOTION_*</code>. A server that lists <code>enabledTools</code> mounts as an advertised connection with that allowlist and requires the local runtime; <code>agent-sdk validate</code> fails otherwise.</p><p>Mounting a plugin trusts it like authored code: its servers run the commands and read the environment variables its config names. Review a plugin before you vendor it.</p><p>Plugin rules and hooks are not mounted; <code>agent-sdk validate</code> warns when a plugin carries them. To drop or reconfigure one of the plugin&#39;s servers, mount as a directory and overlay <code>mcp-connections/&lt;server&gt;.ts</code>. An overlaid server is never read from the plugin, so it needs no variables.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/extensions/cloudflare/</span></span>
-<span class="line"><span>├── extension.ts                        # export default cursorPlugin({ path: &quot;plugins/cloudflare&quot; })</span></span>
-<span class="line"><span>└── mcp-connections/</span></span>
-<span class="line"><span>    ├── cloudflare-docs.ts              # replaces cloudflare__cloudflare-docs with your defineConnection</span></span>
-<span class="line"><span>    └── cloudflare-bindings.ts          # export default disableConnection() drops it</span></span></code></pre></div><p><code>disableConnection()</code> comes from <code>@cursor/july/extensions</code> and fails discovery when it names a server the plugin doesn&#39;t declare.</p><h2 id="build-an-extension" tabindex="-1">Build an extension <a class="header-anchor" href="#build-an-extension" aria-label="Permalink to &quot;Build an extension&quot;">​</a></h2><p>An extension is a directory laid out like <code>agent/</code>. <code>extension.ts</code> declares it; the slots in <a href="#what-an-extension-can-contribute">What an extension can contribute</a> use the same authoring forms as the rest of this reference.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>@acme/ci-triage/</span></span>
-<span class="line"><span>├── package.json</span></span>
-<span class="line"><span>├── extension.ts        # defineExtension</span></span>
-<span class="line"><span>├── tools/</span></span>
-<span class="line"><span>│   ├── failed_jobs.ts</span></span>
-<span class="line"><span>│   ├── job_log.ts</span></span>
-<span class="line"><span>│   └── retry_job.ts</span></span>
-<span class="line"><span>├── skills/</span></span>
-<span class="line"><span>│   └── triage.md</span></span>
-<span class="line"><span>├── hooks/</span></span>
-<span class="line"><span>│   └── audit.ts</span></span>
-<span class="line"><span>├── mcp-connections/</span></span>
-<span class="line"><span>│   └── buildkite.ts</span></span>
-<span class="line"><span>└── lib/</span></span>
-<span class="line"><span>    └── buildkite.ts    # shared code, never discovered</span></span></code></pre></div><p>Declare the extension with its root and, when consumers must configure it, a schema for their settings.</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;">// extension.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineExtension } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineExtension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  root: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.dirname,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Investigate failing CI builds on Buildkite.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  config: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    org: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    token: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    logTailLines: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">positive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The default export is what consumers call to mount the extension, and it is also how your own modules read the consumer&#39;s settings. Import it and read <code>extension.config</code>; the value is validated and has defaults applied.</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;">// tools/job_log.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> extension </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../extension.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { jobLogTail } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/buildkite.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> 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;Read the tail of a CI job&#39;s log.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  effect: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;read&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;">({ pipeline: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), build: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), job: 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;">pipeline</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">job</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">org</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">token</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">logTailLines</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> extension.config;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> jobLogTail</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ org, token, pipeline, build, job, lines: logTailLines });</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Because the consumer picks the namespace, have skills and tool descriptions refer to sibling tools by their short names and say they appear under the mount&#39;s namespace (<code>&lt;namespace&gt;__job_log</code>).</p><p>Publish the built <code>extension.js</code> as the package entry point with the slot directories beside it. <code>root</code> is read from the built file, so copy <code>skills/*.md</code> and <code>instructions.md</code> into the build output or author them as <code>.ts</code>.</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/cloud-agents.html">Cursor cloud agents</a>: the extension that lets an agent launch and steer cloud agents</li><li><a href="./../guides/grokbot-agents.html">Cursor Grok Bot agents</a>: the extension that lets an agent talk to Grok Bot agents</li><li><a href="./../guides/improve.html">Self-improvement</a>: the extension that lets an agent change its own source through a cloud agent and a pull request</li><li><a href="./tools.html">Tools</a>: the tool contract extensions contribute to</li><li><a href="./skills.html">Skills</a>: the skill forms an extension can carry</li><li><a href="./project-layout.html">Project layout</a>: where <code>agent/extensions/</code> sits in the tree</li></ul>`,46)])])}const g=t(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/docs/assets/reference_extensions.md.ZAVUyuEX.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as e,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Extensions","description":"Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/.","frontmatter":{"title":"Extensions","description":"Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),n={name:"reference/extensions.md"};function o(l,s,d,h,p,r){return a(),e("div",null,[...s[0]||(s[0]=[i("",46)])])}const g=t(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/docs/assets/reference_result.md.BK5SxDrf.js

@@ -1,19 +0,0 @@
-import{_ as t,c as i,o as e,ag as a}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Turn result","description":"Run host code on the final assistant text when a turn finishes. Throw to fail the turn.","frontmatter":{"title":"Turn result","description":"Run host code on the final assistant text when a turn finishes. Throw to fail the turn."},"headers":[],"relativePath":"reference/result.md","filePath":"reference/result.md"}'),n={name:"reference/result.md"};function h(l,s,r,o,d,p){return e(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="turn-result" tabindex="-1">Turn result <a class="header-anchor" href="#turn-result" aria-label="Permalink to &quot;Turn result&quot;">​</a></h1><p>Judgment agents need a place to act on the model&#39;s last message: parse it, then page, comment, or close a ticket. Author <code>agent/result.ts</code> with <code>defineResult</code> from <code>@cursor/july/result</code>. When that file exists, every finished turn runs <code>commit</code> on the serving host with the full assistant text.</p><p>A thrown <code>commit</code> fails the turn. Empty assistant text fails it too. Hooks still observe only; they cannot fail a valid turn.</p><p>Use this for an end-of-turn actuation. Mid-turn actions belong in <a href="./tools.html">tools</a>. Durable records that outlive a session belong in <a href="./artifacts.html">artifacts</a>.</p><h2 id="author-agent-result-ts" tabindex="-1">Author <code>agent/result.ts</code> <a class="header-anchor" href="#author-agent-result-ts" aria-label="Permalink to &quot;Author \`agent/result.ts\`&quot;">​</a></h2><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;"> { defineResult } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/result&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { applyDecision, parseDecision } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;./lib/actuate.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineResult</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;"> commit</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>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> applyDecision</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parseDecision</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx.text), ctx.host);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>commit</code> is required. Parse <code>ctx.text</code> however the agent needs. Tell the model the document shape in <code>instructions.md</code>. The Agent SDK does not inject a schema.</p><p>Put <code>result.ts</code> on the root agent only. A copy under a subagent is ignored with a warning.</p><h2 id="commit-on-the-host" tabindex="-1">Commit on the host <a class="header-anchor" href="#commit-on-the-host" aria-label="Permalink to &quot;Commit on the host&quot;">​</a></h2><p><code>commit</code> runs in the serving process after the model finishes, before the turn completes. <code>ctx</code> is the same host surface a server tool gets, plus the turn text:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>The session that produced this turn, including <code>purpose</code></td></tr><tr><td><code>ctx.host</code></td><td>Shared host services (<code>kv</code>, <code>files</code>, <code>mcp</code>)</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session workspace</td></tr><tr><td><code>ctx.text</code></td><td>The full assistant string</td></tr></tbody></table><p>A dry-run session skips <code>commit</code> and still completes. Eval sessions do run <code>commit</code>; return early when <code>ctx.session.purpose === &quot;eval&quot;</code> if the handler must not actuate.</p><p>On cloud runtime, the model still runs on the VM. <code>commit</code> runs on the serving host after the turn returns.</p><p><code>GET /v1/info</code> reports <code>result: true</code> when the file is authored.</p><h2 id="assert-in-evals" tabindex="-1">Assert in evals <a class="header-anchor" href="#assert-in-evals" aria-label="Permalink to &quot;Assert in evals&quot;">​</a></h2><p><code>t.succeeded()</code> fails when <code>commit</code> throws or the turn produced no text, because those are turn failures. Read the document on <code>t.reply</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEval, includes } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&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;"> defineEval</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;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Triage LIN-1842. It duplicates LIN-1801.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;duplicate&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">));</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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="./../evals.html">Evals</a>: <code>t.succeeded</code> and <code>t.reply</code></li><li><a href="./sessions.html">Sessions and streaming</a>: <code>turn.completed</code> and <code>turn.failed</code></li><li><a href="./hooks.html">Hooks</a>: observe the stream after the turn has already settled</li><li><a href="./project-layout.html">Project layout</a>: where <code>agent/result.ts</code> lives</li></ul>`,20)])])}const u=t(n,[["render",h]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_result.md.BK5SxDrf.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as i,o as e,ag as a}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Turn result","description":"Run host code on the final assistant text when a turn finishes. Throw to fail the turn.","frontmatter":{"title":"Turn result","description":"Run host code on the final assistant text when a turn finishes. Throw to fail the turn."},"headers":[],"relativePath":"reference/result.md","filePath":"reference/result.md"}'),n={name:"reference/result.md"};function h(l,s,r,o,d,p){return e(),i("div",null,[...s[0]||(s[0]=[a("",20)])])}const u=t(n,[["render",h]]);export{k as __pageData,u as default};

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

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

package/dist/docs/assets/scaffolding-agents.md.Kctn3OVb.lean.js

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

package/dist/docs/assets/skills_create-agent.md.Q3h6Je-e.js

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

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

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

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

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

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

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

package/dist/docs/assets/skills_deploy.md.CWqi_ZxW.js

@@ -1,35 +0,0 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Deploy an Agent SDK agent","description":"Deploy or redeploy an Agent SDK project to Cursor-managed hosting with an attached service account. Use when asked to deploy, redeploy, publish, or update a hosted Agent SDK agent.","frontmatter":{"name":"agentsdk-deploy","description":"Deploy or redeploy an Agent SDK project to Cursor-managed hosting with an attached service account. Use when asked to deploy, redeploy, publish, or update a hosted Agent SDK agent."},"headers":[],"relativePath":"../skills/deploy/SKILL.md","filePath":"../skills/deploy/SKILL.md"}'),n={name:"../skills/deploy/SKILL.md"};function h(p,s,l,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="deploy-an-agent-sdk-agent" tabindex="-1">Deploy an Agent SDK agent <a class="header-anchor" href="#deploy-an-agent-sdk-agent" aria-label="Permalink to &quot;Deploy an Agent SDK agent&quot;">​</a></h1><p>Use this skill only after a person asks for a deployment. It deploys a pushed Git ref to Cursor-managed hosting. Local files never upload.</p><p>Use the exact published <code>@cursor/july</code> release embedded in the installed skill. Do not use a floating npm tag or a workspace build of the CLI.</p><h2 id="gather-the-target" tabindex="-1">Gather the target <a class="header-anchor" href="#gather-the-target" aria-label="Permalink to &quot;Gather the target&quot;">​</a></h2><p>Resolve these values from the request and checkout:</p><ul><li>Agent directory. Default to the current directory only when it contains one Agent SDK project.</li><li>Deployment slug. Default to the normalized directory name.</li><li>Git ref. Default to the exact pushed <code>HEAD</code> commit.</li><li>Team. Use the service account&#39;s team unless the request names another.</li><li>Cursor-event repositories and CLI-only egress domains.</li></ul><p>Ask one focused question when the target or requested ref is ambiguous. Do not ask for values the checkout or existing deployment supplies.</p><h2 id="use-the-attached-service-account" tabindex="-1">Use the attached service account <a class="header-anchor" href="#use-the-attached-service-account" aria-label="Permalink to &quot;Use the attached service account&quot;">​</a></h2><p>Continue only when <code>CURSOR_SERVICE_ACCOUNT_KEY</code> is present. Never print the value. Do not run <code>agent-sdk login</code>.</p><p>On Linux and macOS, run every Agent SDK command through this wrapper:</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:#24292E;--shiki-dark:#E1E4E8;">CURSOR_JULY_VERSION</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;__CURSOR_JULY_VERSION__&quot;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">case</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$CURSOR_JULY_VERSION</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> in</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">  __CURSOR_JULY_</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">__</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">)</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    echo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;The Agent SDK deploy skill is not bound to a package version.&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &gt;&amp;2</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    exit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ;;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">esac</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">run_agent_sdk</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  env</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> NODE_OPTIONS</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -u</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> CURSOR_API_KEY</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    CURSOR_API_KEY_FILE=/dev/null</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    npx</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --yes</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july@</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$CURSOR_JULY_VERSION</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">$@</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>The installed copy pins the release it came from. The wrapper isolates that published CLI and the attached service account. The presence check prevents a stored personal login from being used when the attachment is missing.</p><p>Verify the principal before any write:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">test</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CURSOR_SERVICE_ACCOUNT_KEY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:-</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  echo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;No attached Cursor service account.&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &gt;&amp;2</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  exit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">run_agent_sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>Continue only when <code>credentialSource</code> is <code>service-account</code>. Record the team and complete service-account ID for the final report. Stop on an authentication, team-access, repository-scope, or hosting-entitlement error.</p><h2 id="pin-pushed-source" tabindex="-1">Pin pushed source <a class="header-anchor" href="#pin-pushed-source" aria-label="Permalink to &quot;Pin pushed source&quot;">​</a></h2><p>Find the Git root and commit:</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:#24292E;--shiki-dark:#E1E4E8;">GIT_ROOT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot; rev-parse </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">--show-toplevel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">)&quot;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">SOURCE_REF</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$GIT_ROOT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot; rev-parse HEAD)&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$GIT_ROOT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> status</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --short</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -C</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$GIT_ROOT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> branch</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -r</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --contains</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$SOURCE_REF</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>Use a ref from the request instead of <code>SOURCE_REF</code> when the person names one. Confirm the selected commit exists on the remote. If intended changes are uncommitted or unpushed, stop and explain they will not ship. Do not commit or push unless the request includes that work.</p><p>The CLI infers the normalized HTTPS <code>origin</code>, agent path, and slug from <code>--dir</code>. Pass <code>--repo</code>, <code>--path</code>, or <code>--slug</code> when the request overrides the inferred value. Never print a remote URL that contains credentials.</p><h2 id="preserve-deployment-inputs" tabindex="-1">Preserve deployment inputs <a class="header-anchor" href="#preserve-deployment-inputs" aria-label="Permalink to &quot;Preserve deployment inputs&quot;">​</a></h2><p>A redeploy replaces its source, Cursor-event repositories, and CLI-supplied egress domains. Preserve the existing <code>cursorEventRepos</code> and <code>egressAllowedDomains</code> unless the request or project changes them. Reapply each value with:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>--cursor-events-repo &lt;owner/repo&gt;</span></span>
-<span class="line"><span>--allow-domain &lt;hostname&gt;</span></span></code></pre></div><p>Read existing settings through a filter that selects only those two fields:</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;">run_agent_sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$SLUG</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  node</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -e</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    let raw = &quot;&quot;;</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    process.stdin.setEncoding(&quot;utf8&quot;);</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    process.stdin.on(&quot;data&quot;, (chunk) =&gt; { raw += chunk; });</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    process.stdin.on(&quot;end&quot;, () =&gt; {</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      const value = JSON.parse(raw);</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      console.log(JSON.stringify({</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">        cursorEventRepos: value.cursorEventRepos ?? [],</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">        egressAllowedDomains: value.egressAllowedDomains ?? [],</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      }, null, 2));</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    });</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &#39;</span></span></code></pre></div><p>Never print or save the full response because it can contain short-lived engine-access headers.</p><p>For a new SCM-channel deployment, ask which repositories should wake the agent when the project does not declare the answer. The source repository is not always the event repository.</p><h2 id="validate-deploy-and-verify" tabindex="-1">Validate, deploy, and verify <a class="header-anchor" href="#validate-deploy-and-verify" aria-label="Permalink to &quot;Validate, deploy, and verify&quot;">​</a></h2><p>Validate with the same published package and principal:</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;">run_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;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>Stop on validation errors. Review hosting warnings about secret names, egress domains, and channel configuration before continuing.</p><p>Deploy the pinned source. Add the preserved or requested repeatable flags:</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;">run_agent_sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --ref</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$SOURCE_REF</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>The command waits for a terminal deployment state. Do not treat <code>pending</code>, <code>accepted</code>, or <code>deploying</code> as success. If the command is interrupted, resume inspection with:</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;">run_agent_sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$SLUG</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>A first deployment prints a one-time alias token. Never paste it into chat or expose it in an agent-captured terminal. Before a first deploy, ask for a secure destination or ask the person to run the final command in a private terminal. When writing the token, use mode <code>0600</code> and print only the path. Redeploys do not print the token. JSON deployment output can also contain credentials, so filter it before display.</p><p>Finish only when the deployment reports <code>running</code>. Report the slug, team, generation, pinned ref, and complete service-account ID. On failure, report the deployment status and sanitized error without retrying a different ref or principal.</p>`,37)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/skills_deploy.md.CWqi_ZxW.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Deploy an Agent SDK agent","description":"Deploy or redeploy an Agent SDK project to Cursor-managed hosting with an attached service account. Use when asked to deploy, redeploy, publish, or update a hosted Agent SDK agent.","frontmatter":{"name":"agentsdk-deploy","description":"Deploy or redeploy an Agent SDK project to Cursor-managed hosting with an attached service account. Use when asked to deploy, redeploy, publish, or update a hosted Agent SDK agent."},"headers":[],"relativePath":"../skills/deploy/SKILL.md","filePath":"../skills/deploy/SKILL.md"}'),n={name:"../skills/deploy/SKILL.md"};function h(p,s,l,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",37)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/skills_evals.md.DFxYPErF.js

@@ -1,25 +0,0 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Agent SDK evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first.","frontmatter":{"name":"agentsdk-evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first."},"headers":[],"relativePath":"../skills/evals/SKILL.md","filePath":"../skills/evals/SKILL.md"}'),n={name:"../skills/evals/SKILL.md"};function d(l,s,o,h,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="agent-sdk-evals" tabindex="-1">Agent SDK evals <a class="header-anchor" href="#agent-sdk-evals" aria-label="Permalink to &quot;Agent SDK evals&quot;">​</a></h1><p>Fixed input, model turn, gates on the trajectory. Files live at project-root <code>evals/**/*.eval.ts</code>. <code>agent/evals/</code> is ignored. Guide: <code>docs/evals.md</code>.</p><p>Observing production: hooks. Tool logic without a model: <code>agent-sdk call &lt;tool&gt; --input &#39;{...}&#39;</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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather/nyc</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Form</th><th>Case id</th></tr></thead><tbody><tr><td><code>evals/weather.eval.ts</code> + <code>test</code></td><td><code>weather</code></td></tr><tr><td><code>evals/weather/nyc.eval.ts</code> + <code>test</code></td><td><code>weather/nyc</code></td></tr><tr><td><code>evals/weather.eval.ts</code> + <code>{ id: &quot;nyc&quot; }</code></td><td><code>weather/nyc</code></td></tr><tr><td><code>evals/sql.eval.ts</code> exporting an array of <code>defineEval</code> calls</td><td><code>sql/0000</code>, <code>sql/0001</code>, ...</td></tr></tbody></table><p><code>eval</code> boots an ephemeral server and a temp state root. <code>--url</code> points at a running agent. Model turns need a Cursor credential (<code>CURSOR_API_KEY</code>, then <code>CURSOR_API_KEY_FILE</code>, then <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>agent-sdk login</code>); <code>--list</code> does not. Node 22.13+, never Bun.</p><h2 id="seeding" tabindex="-1">Seeding <a class="header-anchor" href="#seeding" aria-label="Permalink to &quot;Seeding&quot;">​</a></h2><p>Creating or expanding cases: <code>AskQuestion</code> first.</p><table tabindex="0"><thead><tr><th>Question</th><th>Options</th></tr></thead><tbody><tr><td><strong>How should we get eval samples?</strong></td><td>Generate test eval samples for me <code>(recommended)</code> · I will add / upload the data manually</td></tr></tbody></table><ol><li><strong>Manual.</strong> They provide files or paste. Show the shape below. Do not invent cases. Then <code>eval --list</code> and wire gates. API-backed pointers (PR URLs, SHAs, gold labels): materialize under <code>fixtures/</code> first.</li><li><strong>Generated.</strong> Ask count (<code>3</code> recommended). Append to an existing <code>cases</code> array when it fits. Never overwrite or weaken a datapoint. Create <code>evals/evals.config.ts</code> if missing (<code>maxConcurrency: 20</code>; cap 200).</li></ol><h2 id="api" tabindex="-1">API <a class="header-anchor" href="#api" aria-label="Permalink to &quot;API&quot;">​</a></h2><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;"> { defineEval, includes, satisfies } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smoke&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cases: [</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;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;nyc&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;NYC temperature.&quot;</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;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;What&#39;s the temperature in NYC?&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;get_weather&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notCalledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;save_weather_note&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">°</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">[FC]</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">));</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEvalConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&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;"> defineEvalConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  maxConcurrency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Either <code>test(t)</code> or <code>cases</code>, not both. <code>t.send</code> waits for the turn to settle (complete, park, or fail) and returns it; <code>turn.calledTool(...)</code> reads only that turn, <code>t.*</code> reads the whole run. First-send options: <code>workspaceFiles</code>, <code>workspaceDir</code>, <code>cloud</code>.</p><p>Gates: <code>t.succeeded()</code> / <code>t.parked()</code>, <code>calledTool(name, { input, output, status, count })</code> / <code>notCalledTool</code>, <code>toolOrder</code>, <code>maxToolCalls</code>, <code>taggedArtifact</code>, <code>event</code> / <code>notEvent</code>, <code>t.check(value, includes | equals | matches | similarity | satisfies)</code>. Records: <code>t.metric</code>, <code>t.log</code>, <code>t.score</code> (soft 0-1).</p><p>Severity is on the handle: default gate; <code>.soft()</code> tracked; <code>.atLeast(0.8)</code> soft with a bar (verdict <code>scored</code>, exit 1 only under <code>--strict</code>); <code>.gate(0.8)</code> hard. <code>t.judge.factuality</code>, <code>summarizes</code>, <code>closedQA</code>, and <code>sql</code> are soft by default and need a judge model (<code>judge</code> in <code>evals.config.ts</code>, on the eval or case, or per-call <code>{ model }</code>).</p><h2 id="side-effects" tabindex="-1">Side effects <a class="header-anchor" href="#side-effects" aria-label="Permalink to &quot;Side effects&quot;">​</a></h2><p>Eval sessions run real tools. Guard actuation with <code>ctx.session.purpose === &quot;eval&quot;</code> in the tool, hook, or <code>defineResult</code> and return a shaped result so <code>calledTool</code> can still assert the decision.</p><h2 id="what-to-gate" tabindex="-1">What to gate <a class="header-anchor" href="#what-to-gate" aria-label="Permalink to &quot;What to gate&quot;">​</a></h2><p>Decisions and shape, not prose.</p><ol><li><code>t.succeeded()</code> first</li><li>Intended tool + the tempting wrong one</li><li>A shape regex or <code>satisfies</code> on parsed fields</li><li>If formatting keeps failing, tighten instructions. Do not move rendering into a host tool.</li></ol><p>Anti-patterns: exact phrasing; more than ~5 gates (split); live drifting inputs (pin them).</p><table tabindex="0"><thead><tr><th>Surface</th><th>Fixture</th></tr></thead><tbody><tr><td>Chat</td><td>One frozen prompt</td></tr><tr><td>Tool-heavy</td><td><code>agent-sdk call</code> first, then the prompt</td></tr><tr><td>GitHub</td><td><code>github replay … --dry-run --out fixtures/github</code></td></tr><tr><td>Host-prep PR review</td><td>A team-owned PR; gate findings shape, not counts</td></tr><tr><td>Workspace</td><td><code>workspaceFiles</code> in <code>t.send</code></td></tr><tr><td>Dataset</td><td><code>loadJson</code> / <code>loadJsonl</code> / <code>loadYaml</code> from <code>@cursor/july/evals/loaders</code>, paths from the project root</td></tr></tbody></table><h2 id="debug-and-ci" tabindex="-1">Debug and CI <a class="header-anchor" href="#debug-and-ci" aria-label="Permalink to &quot;Debug and CI&quot;">​</a></h2><p>A failed local run leaves <code>evals/&lt;case-id&gt;.json</code> (assertions, inputs, tool I/O, final text, logs) under <code>evals/&lt;stamp&gt;/</code> in the project state directory (the CLI prints the path); read it before editing the eval. <code>--state-root &lt;path&gt;</code> keeps the raw session events too.</p><p>CI: <code>agent-sdk eval --dir . --json --no-stream --junit reports/evals.xml</code>. Exit <code>1</code> on a failed gate, <code>2</code> when nothing matched, <code>--strict</code> to fail on <code>scored</code>.</p><p>Every kept hillclimb change lands an eval that would have failed before it. Never weaken a gate to pass a round.</p>`,27)])])}const g=e(n,[["render",d]]);export{k as __pageData,g as default};

package/dist/docs/assets/skills_evals.md.DFxYPErF.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Agent SDK evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first.","frontmatter":{"name":"agentsdk-evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first."},"headers":[],"relativePath":"../skills/evals/SKILL.md","filePath":"../skills/evals/SKILL.md"}'),n={name:"../skills/evals/SKILL.md"};function d(l,s,o,h,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t("",27)])])}const g=e(n,[["render",d]]);export{k as __pageData,g as default};

package/dist/docs/assets/skills_framework-map.md.BxLSOhSY.js

@@ -1 +0,0 @@
-import{_ as t,c as d,o,ag as r}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK framework map","description":"Orient on Agent SDK layout, local vs cloud runtime, sessions, and invariants (Node not Bun, root evals/, typecheck after tsx). Use when creating, editing, or running a project with agent/agent.ts.","frontmatter":{"name":"agentsdk-framework-map","description":"Orient on Agent SDK layout, local vs cloud runtime, sessions, and invariants (Node not Bun, root evals/, typecheck after tsx). Use when creating, editing, or running a project with agent/agent.ts."},"headers":[],"relativePath":"../skills/framework-map/SKILL.md","filePath":"../skills/framework-map/SKILL.md"}'),c={name:"../skills/framework-map/SKILL.md"};function s(a,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r('<h1 id="agent-sdk-framework-map" tabindex="-1">Agent SDK framework map <a class="header-anchor" href="#agent-sdk-framework-map" aria-label="Permalink to &quot;Agent SDK framework map&quot;">​</a></h1><p><code>@cursor/july</code> discovers files under <code>agent/</code> and serves the agent over HTTP, Slack, and GitHub. Markdown is prose. TypeScript is typed behavior. Ground truth: package <code>README.md</code> and <code>AGENTS.md</code>.</p><p>CLI is <code>agent-sdk</code> (Node, never Bun).</p><p>Public docs: <code>node_modules/@cursor/july/dist/docs/llms.txt</code> or <code>/docs/llms.txt</code> on a running host.</p><h2 id="invariants" tabindex="-1">Invariants <a class="header-anchor" href="#invariants" aria-label="Permalink to &quot;Invariants&quot;">​</a></h2><ol><li><strong>Node 22.13+, never Bun.</strong> Bun corrupts harness tool-result streams (<code>NGHTTP2_FRAME_SIZE_ERROR</code>).</li><li><strong>Evals live at project-root <code>evals/</code>.</strong> <code>agent/evals/</code> is ignored.</li><li><strong>tsx does not typecheck.</strong> Tool <code>execute</code> must return JSON-shaped values: object literals or <code>type</code> aliases, not <code>interface</code> types.</li><li><strong>Nested git checkouts.</strong> Discovery sets <code>local.cwd</code> to a per-project cache directory under <code>~/.cache</code>. Point cwd at a checkout only when the agent must inherit that tree.</li><li><strong>Attached MCP is nameless</strong> until <code>advertiseTools: true</code>.</li><li><strong>Model turns need a Cursor credential</strong> (<code>CURSOR_API_KEY</code>, then <code>CURSOR_API_KEY_FILE</code>, then <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>agent-sdk login</code>). <code>validate</code>, <code>info</code>, <code>call</code>, and <code>serve</code> bring-up do not.</li></ol><h2 id="folder-structure" tabindex="-1">Folder structure <a class="header-anchor" href="#folder-structure" aria-label="Permalink to &quot;Folder structure&quot;">​</a></h2><p>Path is identity. Full list: README &quot;Folder structure&quot;.</p><table tabindex="0"><thead><tr><th>Path</th><th>Role</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt (required)</td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One tool. <code>execution: &quot;server&quot;</code> or <code>&quot;agent&quot;</code></td></tr><tr><td><code>agent/skills/*</code></td><td>On-demand procedures</td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP. Never name an account file <code>cursor.ts</code>. <code>advertiseTools: true</code> for named local tools</td></tr><tr><td><code>agent/host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP for <code>ctx.host.mcp</code> / <code>mcp oauth</code></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent (<code>description</code> required)</td></tr><tr><td><code>agent/extensions/&lt;ns&gt;.ts</code></td><td>Mounted extension or Cursor plugin (<code>cursorPlugin</code>); contributions are <code>&lt;ns&gt;__&lt;name&gt;</code></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>Slack / GitHub / custom HTTP</td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only</td></tr><tr><td><code>agent/artifacts.ts</code></td><td>Durable tagged outputs (<code>defineArtifacts</code>)</td></tr><tr><td><code>agent/result.ts</code></td><td>Host <code>commit</code> on the final assistant text (<code>defineResult</code>)</td></tr><tr><td><code>agent/otel.ts</code></td><td>OpenTelemetry (<code>defineOtel</code>)</td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron. Never auto-fire under <code>--dev</code></td></tr><tr><td><code>agent/sandbox/workspace/</code></td><td>Session seed files (local only)</td></tr><tr><td><code>agent/lib/</code></td><td>Import-only. Never discovered</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Case id is the path under <code>evals/</code></td></tr></tbody></table><h2 id="local-vs-cloud" tabindex="-1">Local vs cloud <a class="header-anchor" href="#local-vs-cloud" aria-label="Permalink to &quot;Local vs cloud&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (default) runs on the serve host. <code>runtime: &quot;cloud&quot;</code> needs <code>cloud: { repos: [...] }</code>.</p><table tabindex="0"><thead><tr><th>Capability</th><th>local</th><th>cloud</th></tr></thead><tbody><tr><td>Server tools</td><td>yes</td><td>yes on managed hosting; self-hosted needs <code>--public-url</code></td></tr><tr><td>Tool approvals</td><td>yes</td><td>no</td></tr><tr><td>Agent tools / skills</td><td>yes</td><td>yes</td></tr><tr><td>sandbox seeds</td><td>yes</td><td>no</td></tr><tr><td>Checkout</td><td>you arrange it</td><td>the VM carries it</td></tr></tbody></table><p>Use cloud when the job needs a checkout at scale. <code>validate</code> warns when cloud is combined with local-only capabilities.</p><h2 id="sessions" tabindex="-1">Sessions <a class="header-anchor" href="#sessions" aria-label="Permalink to &quot;Sessions&quot;">​</a></h2><ul><li><strong>continuationToken</strong> continues a conversation. HTTP follow-ups rotate it. Stale tokens return <code>409</code>.</li><li><strong>sessionId</strong> is the inspect handle (<code>GET /v1/session/:id/stream?startIndex=N</code>).</li></ul><p>A follow-up to a busy HTTP/MCP session interrupts the in-flight turn. Slack coalesces. Routes: <code>docs/reference/http-api.md</code>. Session files live under the project state directory (<code>--state-root</code>).</p><h2 id="where-logic-belongs" tabindex="-1">Where logic belongs <a class="header-anchor" href="#where-logic-belongs" aria-label="Permalink to &quot;Where logic belongs&quot;">​</a></h2><p>Code: side-effect gates, write dedupe, auth, evidence seeding, hard API caps. Model: formatting, summarizing, classification, replies. Budget: <code>skills/create-agent/SKILL.md</code>.</p><p>Loop: <code>validate</code> / <code>info</code> / <code>call</code> / <code>run</code> / <code>eval</code> / <code>serve</code>. Serve only this agent&#39;s directory.</p><table tabindex="0"><thead><tr><th>Task</th><th>Skill</th></tr></thead><tbody><tr><td>Scaffold</td><td><code>skills/create-agent/SKILL.md</code></td></tr><tr><td>Evals</td><td><code>skills/evals/SKILL.md</code></td></tr><tr><td>OpenTelemetry</td><td><code>skills/otel/SKILL.md</code></td></tr><tr><td>GitHub</td><td><code>skills/github/SKILL.md</code></td></tr><tr><td>Slack</td><td><code>skills/setup-slack/SKILL.md</code></td></tr><tr><td>Host MCP OAuth</td><td><code>skills/mcp-auth/SKILL.md</code></td></tr><tr><td>Managed deployment</td><td><code>skills/deploy/SKILL.md</code></td></tr><tr><td>Local triage</td><td><code>skills/debug/SKILL.md</code></td></tr><tr><td>Measured improvement</td><td><code>skills/hillclimb/SKILL.md</code></td></tr></tbody></table>',20)])])}const p=t(c,[["render",s]]);export{g as __pageData,p as default};

package/dist/docs/assets/skills_framework-map.md.BxLSOhSY.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as d,o,ag as r}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK framework map","description":"Orient on Agent SDK layout, local vs cloud runtime, sessions, and invariants (Node not Bun, root evals/, typecheck after tsx). Use when creating, editing, or running a project with agent/agent.ts.","frontmatter":{"name":"agentsdk-framework-map","description":"Orient on Agent SDK layout, local vs cloud runtime, sessions, and invariants (Node not Bun, root evals/, typecheck after tsx). Use when creating, editing, or running a project with agent/agent.ts."},"headers":[],"relativePath":"../skills/framework-map/SKILL.md","filePath":"../skills/framework-map/SKILL.md"}'),c={name:"../skills/framework-map/SKILL.md"};function s(a,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r("",20)])])}const p=t(c,[["render",s]]);export{g as __pageData,p as default};