@cursor/july 0.1.100 → 0.1.102

package/dist/docs/assets/{reference_connections.md.BiGoBAk2.lean.js → reference_connections.md.Di6jJAXF.lean.js}

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

package/dist/docs/assets/reference_extensions.md.9WQMZe1l.js

@@ -0,0 +1,56 @@
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a package of tools and skills 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 tools and skills 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"}'),t={name:"reference/extensions.md"};function l(o,s,p,h,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<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 tools and skills an agent installs 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><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="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>└── skills/</span></span>
+<span class="line"><span>    └── triage.md       # replaces 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 tool or skill under the namespace. <code>disableTool()</code> comes from <code>@cursor/july/extensions</code> and fails discovery when it names a tool the extension doesn&#39;t have, so a typo can&#39;t silently keep a tool alive. 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; <code>tools/</code> and <code>skills/</code> hold the contributions in the same authoring forms as <a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>.</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>└── 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 <code>tools/</code> and <code>skills/</code> beside it. <code>root</code> is read from the built file, so copy <code>skills/*.md</code> into the build output or author skills as <code>.ts</code> with <code>defineSkill</code>.</p><p>Only <code>tools/</code> and <code>skills/</code> are mounted from an extension tree. Instructions, connections, hooks, channels, and the runtime configuration belong to the agent that mounts the extension; <code>agent-sdk validate</code> warns when a tree carries agent slots such as <code>instructions.md</code>, <code>connections/</code>, <code>hooks/</code>, <code>channels/</code>, or <code>schedules/</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="./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>`,35)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_extensions.md.9WQMZe1l.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,ag as e}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a package of tools and skills 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 tools and skills 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"}'),t={name:"reference/extensions.md"};function l(o,s,p,h,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",35)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_http-api.md.BEJx9XVj.js → reference_http-api.md.oySXBO8o.js}

@@ -2,7 +2,7 @@ import{_ as t,c as s,o,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tools declaring <code>timeArgs</code> refuse calls not bounded at or before it. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tool calls with relative, later-than-<code>asOf</code>, or omitted schema-declared time bounds are refused. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends.</p><p>Expect <code>409</code> on a stale token or a task session. Task sessions do not accept follow-ups. Expect <code>403</code> when the caller is not the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#which-events-can-i-stream">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="session-cost" tabindex="-1">Session cost <a class="header-anchor" href="#session-cost" aria-label="Permalink to &quot;Session cost&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/cost</code> returns the session&#39;s cost report: per-turn token usage and the engine&#39;s estimated cost, folded from <code>turn.completed</code> events. It runs the same owner check as the other session routes and returns <code>404</code> for an unknown session. The <a href="./cli.html#cost"><code>agent-sdk cost</code></a> command reports the same data.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

package/dist/docs/assets/{reference_project-layout.md.Bv4KOtlB.js → reference_project-layout.md.CA6QP6Lw.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o as s,ag as d}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),o={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return s(),a("div",null,[...e[0]||(e[0]=[d(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Agent SDK builds an agent by walking the filesystem under <code>agent/</code>. Each folder has a defined purpose. The path a file lands in determines how the Agent SDK loads it.</p><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>For the capabilities below, identity usually comes from the path. A/B experiments can override their file-derived name.</p><table tabindex="0"><thead><tr><th>Path</th><th>Resolves to</th></tr></thead><tbody><tr><td><code>agent/tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>agent/mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>agent/host-connections/anytool.ts</code></td><td>Host MCP connection <code>anytool</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>agent/skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>agent/subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>agent/channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr><tr><td><code>agent/ab.ts</code></td><td>A/B experiment <code>ab</code> unless <code>name</code> overrides it</td></tr><tr><td><code>agent/ab/concise.ts</code></td><td>A/B experiment <code>concise</code> unless <code>name</code> overrides it</td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-overview" tabindex="-1">Project overview <a class="header-anchor" href="#project-overview" aria-label="Permalink to &quot;Project overview&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
+import{_ as t,c as s,o as a,ag as d}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),o={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[d(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Agent SDK builds an agent by walking the filesystem under <code>agent/</code>. Each folder has a defined purpose. The path a file lands in determines how the Agent SDK loads it.</p><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>For the capabilities below, identity usually comes from the path. A/B experiments can override their file-derived name.</p><table tabindex="0"><thead><tr><th>Path</th><th>Resolves to</th></tr></thead><tbody><tr><td><code>agent/tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>agent/mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>agent/host-connections/anytool.ts</code></td><td>Host MCP connection <code>anytool</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>agent/skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>agent/subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>agent/extensions/ci.ts</code></td><td>extension mount <code>ci</code>; its tools and skills become <code>ci__&lt;name&gt;</code></td></tr><tr><td><code>agent/extensions/notion.ts</code></td><td>Cursor plugin mount <code>notion</code> (<code>cursorPlugin</code>); its skills, agents, and MCP servers become <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>agent/channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr><tr><td><code>agent/ab.ts</code></td><td>A/B experiment <code>ab</code> unless <code>name</code> overrides it</td></tr><tr><td><code>agent/ab/concise.ts</code></td><td>A/B experiment <code>concise</code> unless <code>name</code> overrides it</td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-overview" tabindex="-1">Project overview <a class="header-anchor" href="#project-overview" aria-label="Permalink to &quot;Project overview&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
 <span class="line"><span>├── package.json</span></span>
 <span class="line"><span>├── agent/</span></span>
 <span class="line"><span>│   ├── agent.ts               # runtime config (model, runtime, cloud/local)</span></span>
@@ -14,6 +14,6 @@ import{_ as t,c as a,o as s,ag as d}from"./chunks/framework.BCISBCiQ.js";const g
 <span class="line"><span>│   └── channels/</span></span>
 <span class="line"><span>│       └── github.ts          # messages and external events</span></span>
 <span class="line"><span>└── evals/</span></span>
-<span class="line"><span>    └── readiness.eval.ts      # regression cases</span></span></code></pre></div><p>Evals live in <code>evals/</code> at the project root, a sibling of <code>agent/</code>, never inside it. <code>agent/evals/</code> is silently ignored. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>agent/skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for <code>ctx.host.mcp</code> and <code>mcp oauth</code>. The model never sees them.</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>agent/otel.ts</code></td><td><code>defineOtel</code> OTLP export (traces, metrics, optional logs)</td><td><a href="./../guides/opentelemetry.html">OpenTelemetry</a></td></tr><tr><td><code>agent/ab.ts</code>, <code>agent/ab/*.ts</code></td><td><code>defineAB</code> experiments with sticky variants and live metrics</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/ab.config.ts</code></td><td><code>defineABConfig</code> shared A/B settings</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/storage.ts</code></td><td><code>defineStorage</code> backend for the durable <code>host.kv</code> / <code>host.files</code> APIs</td><td><a href="./../storage.html">Storage</a></td></tr><tr><td><code>agent/artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>agent/sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#what-goes-into-a-local-session-workspace">Sessions</a></td></tr><tr><td><code>agent/playground/</code></td><td>Custom playground tool chips</td><td><a href="./playground.html">Playground</a></td></tr><tr><td><code>agent/lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><code>agent/lib/</code> is the only place for shared code. Everything else under <code>agent/</code> is discovery surface. A stray <code>.ts</code> file in one of these folders is treated as a definition.</p><h2 id="why-didn-t-the-agent-sdk-discover-my-file" tabindex="-1">Why didn&#39;t the Agent SDK discover my file? <a class="header-anchor" href="#why-didn-t-the-agent-sdk-discover-my-file" aria-label="Permalink to &quot;Why didn&#39;t the Agent SDK discover my file?&quot;">​</a></h2><p>Run <code>agent-sdk validate --dir .</code> and <code>agent-sdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings, such as cloud runtime combined with local-only capabilities, print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # diagnostics; non-zero exit on errors</span></span>
+<span class="line"><span>    └── readiness.eval.ts      # regression cases</span></span></code></pre></div><p>Evals live in <code>evals/</code> at the project root, a sibling of <code>agent/</code>, never inside it. <code>agent/evals/</code> is silently ignored. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>agent/skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for <code>ctx.host.mcp</code> and <code>mcp oauth</code>. The model never sees them.</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>agent/extensions/&lt;ns&gt;.ts</code> or <code>agent/extensions/&lt;ns&gt;/</code></td><td>A mounted extension or Cursor plugin; its contributions become <code>&lt;ns&gt;__&lt;name&gt;</code></td><td><a href="./extensions.html">Extensions</a></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>agent/otel.ts</code></td><td><code>defineOtel</code> OTLP export (traces, metrics, optional logs)</td><td><a href="./../guides/opentelemetry.html">OpenTelemetry</a></td></tr><tr><td><code>agent/ab.ts</code>, <code>agent/ab/*.ts</code></td><td><code>defineAB</code> experiments with sticky variants and live metrics</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/ab.config.ts</code></td><td><code>defineABConfig</code> shared A/B settings</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/storage.ts</code></td><td><code>defineStorage</code> backend for the durable <code>host.kv</code> / <code>host.files</code> APIs</td><td><a href="./../storage.html">Storage</a></td></tr><tr><td><code>agent/artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>agent/sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#what-goes-into-a-local-session-workspace">Sessions</a></td></tr><tr><td><code>agent/playground/</code></td><td>Custom playground tool chips</td><td><a href="./playground.html">Playground</a></td></tr><tr><td><code>agent/lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><code>agent/lib/</code> is the only place for shared code. Everything else under <code>agent/</code> is discovery surface. A stray <code>.ts</code> file in one of these folders is treated as a definition.</p><h2 id="why-didn-t-the-agent-sdk-discover-my-file" tabindex="-1">Why didn&#39;t the Agent SDK discover my file? <a class="header-anchor" href="#why-didn-t-the-agent-sdk-discover-my-file" aria-label="Permalink to &quot;Why didn&#39;t the Agent SDK discover my file?&quot;">​</a></h2><p>Run <code>agent-sdk validate --dir .</code> and <code>agent-sdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings, such as cloud runtime combined with local-only capabilities, print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # diagnostics; non-zero exit on errors</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:#6A737D;--shiki-dark:#6A737D;">        # human-readable surface</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:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # machine-readable project info (same shape as GET /v1/info)</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="./agent-config.html">Agent config</a>: the runtime config at the root</li><li><a href="./tools.html">Tools</a>: add typed actions under <code>agent/tools/</code></li><li><a href="./../ab.html">Live A/B metrics</a>: compare variants from <code>agent/ab.ts</code> or <code>agent/ab/</code></li><li><a href="./../concepts.html">Concepts</a>: why the filesystem is the interface</li></ul>`,20)])])}const u=t(o,[["render",n]]);export{g as __pageData,u as default};

package/dist/docs/assets/{reference_project-layout.md.Bv4KOtlB.lean.js → reference_project-layout.md.CA6QP6Lw.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o as s,ag as d}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),o={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return s(),a("div",null,[...e[0]||(e[0]=[d("",20)])])}const u=t(o,[["render",n]]);export{g as __pageData,u as default};
+import{_ as t,c as s,o as a,ag as d}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),o={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[d("",20)])])}const u=t(o,[["render",n]]);export{g as __pageData,u as default};

package/dist/docs/assets/{reference_skills.md.BFW9retM.js → reference_skills.md.l2ezAcaN.js}

@@ -12,4 +12,4 @@ import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Research unfamiliar topics before answering.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Gather evidence first, then answer with the key facts.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  files: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;references/checklist.md&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;# Checklist</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">- Find sources.</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;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="how-skills-reach-the-model" tabindex="-1">How skills reach the model <a class="header-anchor" href="#how-skills-reach-the-model" aria-label="Permalink to &quot;How skills reach the model&quot;">​</a></h2><p>On the local runtime, skills land in the session workspace at <code>.cursor/skills/&lt;name&gt;/SKILL.md</code>, and the harness advertises and loads them natively. On the cloud runtime there is no session workspace, so the engine copies the same SKILL.md tree onto an Agent Store for native discovery:</p><ul><li>Hosted deployments write store-root <code>skills/&lt;name&gt;/</code>.</li><li><code>agent-sdk serve</code> / <code>run</code> with a personal <code>CURSOR_API_KEY</code> write namespaced skills on the USER store so they cannot collide with the user&#39;s own skills.</li></ul><p><code>validate</code> still warns about the combination so the store path is visible. Cloud turns with neither a hosted store nor an API key see only skills already in the cloud repo.</p><h2 id="instructions-skills-or-tools" tabindex="-1">Instructions, skills, or tools? <a class="header-anchor" href="#instructions-skills-or-tools" aria-label="Permalink to &quot;Instructions, skills, or tools?&quot;">​</a></h2><p>Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to <em>follow</em> something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.</p><p>A good skill description is a routing rule, not a title. Say <em>when</em> to use it, like &quot;Use when a pull request needs a structured approval checklist,&quot; because the description is all the model sees before deciding to load it.</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="./instructions.html">Instructions</a>: what stays always-on</li><li><a href="./tools.html">Tools</a>: when prose needs to become code</li><li><a href="./project-layout.html">Project layout</a>: where skills sit in the tree</li></ul>`,19)])])}const u=e(n,[["render",l]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="how-skills-reach-the-model" tabindex="-1">How skills reach the model <a class="header-anchor" href="#how-skills-reach-the-model" aria-label="Permalink to &quot;How skills reach the model&quot;">​</a></h2><p>On the local runtime, skills land in the session workspace at <code>.cursor/skills/&lt;name&gt;/SKILL.md</code>, and the harness advertises and loads them natively. On the cloud runtime there is no session workspace, so the engine copies the same SKILL.md tree onto an Agent Store for native discovery:</p><ul><li>Hosted deployments write store-root <code>skills/&lt;name&gt;/</code>.</li><li><code>agent-sdk serve</code> / <code>run</code> with a personal <code>CURSOR_API_KEY</code> write namespaced skills on the USER store so they cannot collide with the user&#39;s own skills.</li></ul><p><code>validate</code> still warns about the combination so the store path is visible. Cloud turns with neither a hosted store nor an API key see only skills already in the cloud repo.</p><h2 id="instructions-skills-or-tools" tabindex="-1">Instructions, skills, or tools? <a class="header-anchor" href="#instructions-skills-or-tools" aria-label="Permalink to &quot;Instructions, skills, or tools?&quot;">​</a></h2><p>Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to <em>follow</em> something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.</p><p>A good skill description is a routing rule, not a title. Say <em>when</em> to use it, like &quot;Use when a pull request needs a structured approval checklist,&quot; because the description is all the model sees before deciding to load it.</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="./instructions.html">Instructions</a>: what stays always-on</li><li><a href="./tools.html">Tools</a>: when prose needs to become code</li><li><a href="./extensions.html">Extensions</a>: skills installed as a package under a namespace</li><li><a href="./project-layout.html">Project layout</a>: where skills sit in the tree</li></ul>`,19)])])}const u=e(n,[["render",l]]);export{c as __pageData,u as default};

package/dist/docs/assets/{reference_tools.md.CvAHsdSp.js → reference_tools.md.B1up2r9W.js}

@@ -84,4 +84,4 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span></code></pre></div><p>Programmatically, <code>callTool(toolName, input, options?)</code> is available on the serve handle, on channel route handlers and <code>onStart</code> args, and on schedule <code>run</code> handlers, so a channel can mix deterministic calls with model turns, fetching PR metadata deterministically and then <code>send()</code>ing the review prompt:</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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> outcome</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/checkout/pull/42&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:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral workspace and is removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream. While a model turn is running, a session-bound call is admitted by its effect: a read-effect call (a declared <code>effect: &quot;read&quot;</code>, or an advertised MCP tool whose server annotates it read-only) runs alongside the turn, reading the workspace as the turn has left it, and is recorded under its own per-call <code>turnId</code> so trajectories keep it apart from the turn&#39;s own calls; a write-effect call — including an undeclared tool, which counts as a write — returns <code>409 session_busy</code> until the turn finishes, because a running turn owns the workspace. When the session&#39;s harness cwd cannot be materialized, a read-effect call runs in a scratch workspace instead and the outcome carries <code>scratchWorkspace: true</code>; a write-effect call fails with <code>workspace_unavailable</code>.</p><p>A session can also be addressed by its continuation token: an optional <code>continuationToken</code> (<code>&lt;channelId&gt;:&lt;key&gt;</code>, as <code>/v1/sessions</code> lists it; mutually exclusive with <code>sessionId</code>). A token that maps to a live session behaves exactly like passing that session&#39;s id — same ownership check, same busy semantics, same event recording. A token with no session behind it runs the call scratch-bound with the token&#39;s channel id and continuation key as the call&#39;s session identity, so a deployment whose tools resolve state from the continuation key can serve it with no live session. Malformed tokens are rejected with <code>400 invalid_continuation_token</code>.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>Gate side effects with <code>needsApproval</code>. Declare each tool&#39;s <code>effect</code> so dry-run sessions can execute reads and stub writes.</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/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral workspace and is removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream. While a model turn is running, a session-bound call is admitted by its effect: a read-effect call (a declared <code>effect: &quot;read&quot;</code>, or an advertised MCP tool whose server annotates it read-only) runs alongside the turn, reading the workspace as the turn has left it, and is recorded under its own per-call <code>turnId</code> so trajectories keep it apart from the turn&#39;s own calls; a write-effect call — including an undeclared tool, which counts as a write — returns <code>409 session_busy</code> until the turn finishes, because a running turn owns the workspace. When the session&#39;s harness cwd cannot be materialized, a read-effect call runs in a scratch workspace instead and the outcome carries <code>scratchWorkspace: true</code>; a write-effect call fails with <code>workspace_unavailable</code>.</p><p>A session can also be addressed by its continuation token: an optional <code>continuationToken</code> (<code>&lt;channelId&gt;:&lt;key&gt;</code>, as <code>/v1/sessions</code> lists it; mutually exclusive with <code>sessionId</code>). A token that maps to a live session behaves exactly like passing that session&#39;s id — same ownership check, same busy semantics, same event recording. A token with no session behind it runs the call scratch-bound with the token&#39;s channel id and continuation key as the call&#39;s session identity, so a deployment whose tools resolve state from the continuation key can serve it with no live session. Malformed tokens are rejected with <code>400 invalid_continuation_token</code>.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>Gate side effects with <code>needsApproval</code>. Declare each tool&#39;s <code>effect</code> so dry-run sessions can execute reads and stub writes.</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/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./extensions.html">Extensions</a>: tools installed as a package under a namespace</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

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

@@ -0,0 +1 @@
+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"}'),s={name:"../skills/framework-map/SKILL.md"};function c(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 <code>CURSOR_API_KEY</code>.</strong> <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({ path })</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/ab.ts</code> or <code>agent/ab/*.ts</code></td><td>Live A/B (<code>defineAB</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>Live A/B</td><td><code>skills/ab/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>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(s,[["render",c]]);export{g as __pageData,p as default};

package/dist/docs/assets/{skills_framework-map.md.BTi817yv.lean.js → skills_framework-map.md.DDa4MeEW.lean.js}

@@ -1 +1 @@
-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"}'),s={name:"../skills/framework-map/SKILL.md"};function a(c,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r("",20)])])}const p=t(s,[["render",a]]);export{g as __pageData,p as default};
+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"}'),s={name:"../skills/framework-map/SKILL.md"};function c(a,e,n,l,i,u){return o(),d("div",null,[...e[0]||(e[0]=[r("",20)])])}const p=t(s,[["render",c]]);export{g as __pageData,p as default};