@cursor/july 0.1.102 → 0.1.103

package/dist/docs/assets/concepts.md.rPzW2HZN.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o,ag as s}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"How the Agent SDK works","description":"Understand projects, sessions, event streams, channels, and runtimes in plain language.","frontmatter":{"title":"How the Agent SDK works","description":"Understand projects, sessions, event streams, channels, and runtimes in plain language."},"headers":[],"relativePath":"concepts.md","filePath":"concepts.md"}'),n={name:"concepts.md"};function r(d,e,l,i,c,h){return o(),a("div",null,[...e[0]||(e[0]=[s('<h1 id="how-the-agent-sdk-works" tabindex="-1">How the Agent SDK works <a class="header-anchor" href="#how-the-agent-sdk-works" aria-label="Permalink to &quot;How the Agent SDK works&quot;">​</a></h1><p>An agent is a folder of instructions and capabilities. The Agent SDK discovers those files, runs conversations, and records what happened.</p><h2 id="what-happens-when-someone-sends-a-message" tabindex="-1">What happens when someone sends a message? <a class="header-anchor" href="#what-happens-when-someone-sends-a-message" aria-label="Permalink to &quot;What happens when someone sends a message?&quot;">​</a></h2><p>Follow one message through the system:</p><ol><li>A channel receives the message from HTTP, Slack, GitHub, or another webhook.</li><li>The channel starts a session or continues an existing one.</li><li>The runtime gives the model its instructions, tools, and workspace.</li><li>The model replies and can call tools along the way.</li><li>The Agent SDK appends every message and tool call to the session&#39;s event stream.</li></ol><p>The channel is the front door. The runtime does the work. The event stream is the record you inspect later.</p><h2 id="how-do-files-become-an-agent" tabindex="-1">How do files become an agent? <a class="header-anchor" href="#how-do-files-become-an-agent" aria-label="Permalink to &quot;How do files become an agent?&quot;">​</a></h2><p>Each capability has a home in the project. The path tells the Agent SDK what to load. The filename becomes the capability&#39;s name. For example, <code>agent/tools/get_weather.ts</code> creates a tool named <code>get_weather</code>.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td>Model and runtime settings</td></tr><tr><td><code>agent/instructions.md</code></td><td>The always-on system prompt</td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>Typed actions the model can call</td></tr><tr><td><code>agent/skills/*</code></td><td>Procedures loaded when needed</td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>Tools from external MCP servers</td></tr><tr><td><code>agent/host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for host tools only</td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP, Slack, and GitHub entry points</td></tr><tr><td><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></td><td>Sticky variants and live performance metrics</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Repeatable checks at the project root</td></tr></tbody></table><p>Other folders add subagents, extensions, hooks, schedules, and workspace files. You don&#39;t register them elsewhere. Run <code>agent-sdk validate</code> to catch invalid files before serving the project.</p><p>See <a href="./reference/project-layout.html">Project layout</a> for the folder structure.</p><h2 id="how-does-the-agent-sdk-identify-a-conversation" tabindex="-1">How does the Agent SDK identify a conversation? <a class="header-anchor" href="#how-does-the-agent-sdk-identify-a-conversation" aria-label="Permalink to &quot;How does the Agent SDK identify a conversation?&quot;">​</a></h2><p>A session is one durable conversation. It has two identifiers:</p><ul><li><strong><code>continuationToken</code></strong> tells a channel which conversation to resume. A Slack channel can use its thread ID. A GitHub channel can use the pull request. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up.</li><li><strong><code>sessionId</code></strong> identifies the stored session. Use it to stream events, inspect the session, resolve approvals, or bind a tool call to the session.</li></ul><p>Use the continuation token to keep talking. Use the session ID to observe or manage the conversation.</p><h2 id="how-do-i-see-what-an-agent-did" tabindex="-1">How do I see what an agent did? <a class="header-anchor" href="#how-do-i-see-what-an-agent-did" aria-label="Permalink to &quot;How do I see what an agent did?&quot;">​</a></h2><p>Each session records an append-only event stream. It includes:</p><ul><li>Messages and streamed text</li><li>Requested tool calls and their results</li><li>Approval requests and decisions</li><li>Turn completion and token usage</li></ul><p>Sessions and their event streams survive server restarts. The playground renders the stream. Evals assert against it. The <code>agent-sdk trajectory</code> command turns a saved stream into a short summary.</p><p>When a run surprises you, inspect its event stream first. See <a href="./reference/sessions.html">Sessions and streaming</a> for the event vocabulary.</p><h2 id="what-does-a-channel-control" tabindex="-1">What does a channel control? <a class="header-anchor" href="#what-does-a-channel-control" aria-label="Permalink to &quot;What does a channel control?&quot;">​</a></h2><p>A channel connects the agent to a surface such as HTTP, Slack, GitHub, or a custom webhook. It controls:</p><ul><li>Routes and input schemas</li><li>Authentication</li><li>Conversation identity</li><li>How replies return to the user</li></ul><p>The built-in HTTP session API is always available. Custom routes accept loopback callers by default. Add an auth policy before sharing them over a network.</p><p>Channels should also prepare deterministic input for the model. For example, a GitHub channel can fetch the pull request, collect the diff, and seed the workspace before the turn starts. The model can then focus on the review instead of gathering files.</p><p>See <a href="./reference/channels.html">Channels</a> for route and authentication details.</p><h2 id="where-does-a-turn-run" tabindex="-1">Where does a turn run? <a class="header-anchor" href="#where-does-a-turn-run" aria-label="Permalink to &quot;Where does a turn run?&quot;">​</a></h2><p>Choose a runtime in <code>agent/agent.ts</code>:</p><table tabindex="0"><thead><tr><th></th><th>Local (default)</th><th>Cloud</th></tr></thead><tbody><tr><td>Turn runs on</td><td>The server host</td><td>A Cursor cloud agent</td></tr><tr><td>Server tools</td><td>Supported</td><td>Supported when the server has <code>--public-url</code> or <code>--cloud-tools-url</code>; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them.</td></tr><tr><td>Approvals (<code>needsApproval</code>)</td><td>Supported</td><td>Not supported (local runtime only)</td></tr><tr><td>Agent tool scripts</td><td>Supported</td><td>Supported</td></tr><tr><td>Skills</td><td>Added to the session workspace</td><td>Available automatically</td></tr><tr><td>Seeded files</td><td>Added to the session workspace</td><td>Ignored</td></tr><tr><td>Repository</td><td>You provide it</td><td>The cloud agent checks it out</td></tr></tbody></table><p>Use the local runtime when the host has the tools and files the agent needs. Use the cloud runtime when each turn needs an isolated repository checkout. <code>agent-sdk validate</code> warns when a cloud agent uses a local-only capability.</p><p>See <a href="./guides/cloud-runtime.html">Cloud runtime</a> for setup and trade-offs.</p><h2 id="what-files-can-a-local-session-access" tabindex="-1">What files can a local session access? <a class="header-anchor" href="#what-files-can-a-local-session-access" aria-label="Permalink to &quot;What files can a local session access?&quot;">​</a></h2><p>Each local session gets its own workspace. The Agent SDK writes the instructions as <code>AGENTS.md</code>, installs authored skills, copies sandbox files, and adds agent tool scripts.</p><p>The workspace is a real Cursor project. It can inherit <code>AGENTS.md</code> and <code>.cursor</code> settings from parent directories. Nested git checkouts default <code>local.cwd</code> to a per-project cache directory under <code>~/.cache</code>. Point <code>cwd</code> at a checkout only when the agent should inherit that tree. <code>run</code> and <code>eval</code> already use a temporary state root.</p><p>Session files live under <code>--state-root</code>. See <a href="./reference/sessions.html#where-does-the-agent-sdk-store-session-data">Sessions</a> for the layout.</p><h2 id="how-can-one-agent-call-another" tabindex="-1">How can one agent call another? <a class="header-anchor" href="#how-can-one-agent-call-another" aria-label="Permalink to &quot;How can one agent call another?&quot;">​</a></h2><p>Every mounted agent also serves MCP at <code>/&lt;slug&gt;/v1/mcp</code>. Another agent or MCP client can use <code>ask</code>, <code>check</code>, and <code>call_tool</code> to delegate work. A peer MCP connection such as <code>defineConnection({ agent: &quot;weather-agent&quot; })</code> adds those tools to the calling agent.</p><p>See <a href="./guides/agent-to-agent.html">Agent-to-agent</a> for a complete example.</p><h2 id="which-rules-prevent-common-setup-problems" tabindex="-1">Which rules prevent common setup problems? <a class="header-anchor" href="#which-rules-prevent-common-setup-problems" aria-label="Permalink to &quot;Which rules prevent common setup problems?&quot;">​</a></h2><ul><li>Use Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Put evals under the project-root <code>evals/</code> directory, not <code>agent/evals/</code>.</li><li>Run a TypeScript check before shipping. <code>validate</code> and <code>run</code> execute TypeScript but don&#39;t type-check it.</li><li>Return JSON-shaped values from tool <code>execute</code> functions.</li><li>Keep local session workspaces away from parent rules you don&#39;t want the agent to inherit.</li><li>Sign in or set <code>CURSOR_API_KEY</code> before starting a model turn. Discovery, validation, direct tool calls, and server startup work without a credential.</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Quickstart</a></li><li><a href="./reference/project-layout.html">Project layout</a></li><li><a href="./reference/sessions.html">Sessions and streaming</a></li><li><a href="./reference/channels.html">Channels</a></li><li><a href="./ab.html">Live A/B metrics</a></li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a></li></ul>',42)])])}const m=t(n,[["render",r]]);export{p as __pageData,m as default};

package/dist/docs/assets/guides_cloud-agents.md.DumwWXba.js

@@ -1,9 +0,0 @@
-import{_ as t,c as a,o as s,ag as n}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.","frontmatter":{"title":"Cursor cloud agents","description":"Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),o={name:"guides/cloud-agents.md"};function i(r,e,h,l,d,u){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="cursor-cloud-agents" tabindex="-1">Cursor cloud agents <a class="header-anchor" href="#cursor-cloud-agents" aria-label="Permalink to &quot;Cursor cloud agents&quot;">​</a></h1><p>The <code>cursor-cloud-agents</code> extension lets an agent delegate coding work to Cursor cloud agents and stay in the conversation while they do it. The cloud agents work on real repository checkouts and push branches and pull requests; your agent hands off the task, reports back, and answers questions in the meantime. A Slack triage agent turns a bug report into a PR, a planner fans a refactor out across repositories, a reviewer asks a cloud agent to address its own comments.</p><p>This is different from the <a href="./cloud-runtime.html">cloud runtime</a>. The runtime moves <em>this</em> agent&#39;s turns onto a cloud VM. The extension keeps the agent where it is and lets it start <em>other</em> cloud agents.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>The extension ships with <code>@cursor/july</code>. Mount it with one file.</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/cloud.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorCloudAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions/cursor-cloud-agents&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;"> cursorCloudAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/api&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    autoCreatePR: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Launches run under the host&#39;s signed-in account (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>) and spend its cloud-agent budget. Name the repositories the agent may target, and keep approval on when you can&#39;t.</p><p>Mount it on an agent that runs on the local runtime; that is where launches park for approval. On the <a href="./cloud-runtime.html#what-changes-on-cloud">cloud runtime</a> approvals don&#39;t resolve.</p><h2 id="what-the-agent-can-do" tabindex="-1">What the agent can do <a class="header-anchor" href="#what-the-agent-can-do" aria-label="Permalink to &quot;What the agent can do&quot;">​</a></h2><p>With the extension mounted, the agent can hand off coding work and stay in the conversation while it happens:</p><ul><li><strong>Hand off a task.</strong> Launch a cloud agent on one of your repositories, or on a pull request, with a self-contained brief. It gets back an agent id and a URL to share.</li><li><strong>Check on it.</strong> See whether the agent is still running, what it produced, and which branches or pull requests it pushed.</li><li><strong>Read what was done.</strong> Pull the agent&#39;s full conversation into the workspace, quote its final report, or trace the exact edits before summarizing for a person.</li><li><strong>Steer or stop.</strong> Send a follow-up to an agent it launched; it queues behind the current run, or interrupts it on request. Cancel a run that went sideways.</li><li><strong>Keep track.</strong> List the agents launched in this conversation, or everything it has launched before.</li></ul><p>A skill teaches the model when to delegate, how to write a brief a cloud agent can act on alone, and how to follow up. Everything the extension launches stays bound to whoever launched it: an agent started by another user, or outside the extension, is out of reach. That separation is only as fine as your host&#39;s auth; a shared bearer token or <code>--allow-anonymous</code> makes every caller one principal, so use <a href="./../reference/channels.html#auth-policies">authored auth</a> when callers need their own.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>cloud</code></td><td>Launch defaults, in the same shape as the agent&#39;s own <a href="./../reference/agent-config.html#cloud-options">cloud options</a>.</td></tr><tr><td><code>cloud.repos</code></td><td>The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can&#39;t name one, so secrets in <code>cloud.envVars</code> never reach a repository you didn&#39;t list.</td></tr><tr><td><code>model</code></td><td>The model launched agents run. Omit it to use the account default.</td></tr><tr><td><code>needsApproval</code></td><td>Park launches and follow-ups for a <a href="./human-in-the-loop.html">human decision</a>. Defaults to <code>true</code> when no <code>cloud.repos</code> are configured, <code>false</code> otherwise.</td></tr><tr><td><code>apiKey</code></td><td>A Cursor API key to launch with instead of the host&#39;s own.</td></tr></tbody></table><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to &quot;Adjust it&quot;">​</a></h2><p>To take a capability away, such as sending follow-ups, mount as a directory and disable that tool; see <a href="./../reference/extensions.html#adjust-a-mounted-extension">overlays</a>.</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="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li><li><a href="./human-in-the-loop.html">Human-in-the-loop approvals</a>: where parked launches get approved</li><li><a href="./cloud-runtime.html">Cloud runtime</a>: run the agent&#39;s own turns on cloud agents instead</li></ul>`,19)])])}const g=t(o,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_cloud-runtime.md.BRirbRAN.js

@@ -1,9 +0,0 @@
-import{_ as t,c as s,o,ag as a}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return o(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cloud&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/org/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // env / envVars / … forwarded to the Cursor SDK</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 host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>).</p><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Cloud agents run against the Cursor backend under the signed-in account, and every wake spends real cloud-agent budget. Decide explicitly what may trigger one.</p></div><h2 id="what-changes-on-cloud" tabindex="-1">What changes on cloud <a class="header-anchor" href="#what-changes-on-cloud" aria-label="Permalink to &quot;What changes on cloud&quot;">​</a></h2><p>Cloud turns run on a VM without your authored files, so the runtime mapping shifts:</p><table tabindex="0"><thead><tr><th>Folder or file</th><th>Local runtime</th><th>Cloud runtime</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code> in the session workspace</td><td>prepended to the first prompt</td></tr><tr><td>Server tools (<code>execution: &quot;server&quot;</code>)</td><td>in-process SDK custom tools</td><td>authenticated HTTP MCP back to the AgentSDK host, when <code>--public-url</code> or <code>--cloud-tools-url</code> is set</td></tr><tr><td>Agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace</td><td>catalog + script bodies on the first prompt</td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/</code> in the workspace</td><td>native discovery after the first turn, from the hosted store or the signed-in account</td></tr><tr><td><code>mcp-connections/*.ts</code></td><td>SDK <code>mcpServers</code></td><td>SDK <code>mcpServers</code> (peers need <code>--public-url</code>)</td></tr><tr><td><code>host-connections/*.ts</code></td><td><code>ctx.host.mcp</code> only</td><td><code>ctx.host.mcp</code> only</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>seeded into the session workspace</td><td>ignored</td></tr><tr><td>Tool approvals (<code>needsApproval</code>)</td><td>supported</td><td>not supported; keep approval-gated tools on local turns</td></tr></tbody></table><p>Authored skills are discovered natively after the first cloud turn, using the hosted store or the signed-in account.</p><p>Approvals are a local-runtime contract. On cloud, a <code>needsApproval</code> tool call rides one HTTP MCP request from the VM, and a parked call would hold that request open until it times out; there is no durable approval flow for cloud turns.</p><p>Peer MCP connections need <code>--public-url</code> for cloud turns. Without one, peers are omitted and the server warns at startup.</p><h2 id="hybrid-local-agent-cloud-sessions" tabindex="-1">Hybrid: local agent, cloud sessions <a class="header-anchor" href="#hybrid-local-agent-cloud-sessions" aria-label="Permalink to &quot;Hybrid: local agent, cloud sessions&quot;">​</a></h2><p>A local-runtime agent can still open cloud-attached sessions per send. Channel handlers may pass a <code>cloud</code> block (repos pinned to a PR ref, say) in <code>send</code> options, and Slack handlers may return <code>cloud</code> from a mention hook. A PR driver works this way: chat stays local, and the <code>drive</code> flow attaches the PR to a cloud VM. The agent-level <code>cloud</code> config is the base that per-session options merge over.</p><h2 id="patterns-that-hold-up" tabindex="-1">Patterns that hold up <a class="header-anchor" href="#patterns-that-hold-up" aria-label="Permalink to &quot;Patterns that hold up&quot;">​</a></h2><p>These come from running a PR driver against real PR traffic:</p><ul><li>One cloud session per unit of work, keyed with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake lands on the same conversation.</li><li>Keep the host deterministic: fetch briefs and metadata on the host, send the VM a compact prompt, and let the VM re-read source of truth with its own <code>gh</code> and <code>git</code> instead of trusting payload snapshots.</li><li>Limit exposure: add repository allowlists on webhook channels, because every wake spends the account&#39;s budget.</li></ul><h2 id="verify-cloud-agents" tabindex="-1">Verify cloud agents <a class="header-anchor" href="#verify-cloud-agents" aria-label="Permalink to &quot;Verify cloud agents&quot;">​</a></h2><p><code>agent-sdk run</code> and <code>eval</code> work unchanged. The trajectory records the same event vocabulary plus <code>agent.bound</code> with the cloud URL, so you can open the cloud conversation for any session. Cloud turns take minutes. Pass generous <code>--timeout-ms</code> values, and keep curl timeouts long when driving channels directly.</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="./../reference/agent-config.html">Agent config</a>: the <code>runtime</code> and <code>cloud</code> fields</li><li><a href="./github.html">GitHub guide</a>: the webhook patterns that pair with cloud triage</li><li><a href="./cloud-agents.html">Cursor cloud agents</a>: keep the agent local and let it launch cloud agents instead</li></ul>`,28)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_cloud-runtime.md.BRirbRAN.lean.js

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

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

@@ -1 +0,0 @@
-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_hooks.md.a8BJxMR5.js

@@ -1,14 +0,0 @@
-import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),o={name:"reference/hooks.md"};function n(d,e,h,r,l,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook is an observe-only subscriber to the session event stream. Hooks run after each event is recorded. They cannot change the event or the turn. That makes them the home for audit logging, metrics, mirroring transcripts into your own store, and maintaining derived state. Handler errors are logged and never fatal. A hook can&#39;t inject context into the next turn or block a turn.</p><p>For deterministic context composition before the model runs, use the host path that already owns the wake: channel handlers (fetch, <code>callTool</code>, <code>workspaceFiles</code>, and the message you pass to <code>send</code>), plus <code>instructions.md</code>, skills, and <code>sandbox/workspace/</code> seed files. Hooks observe what happened; they do not assemble the prompt.</p><p>Author <code>agent/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/july/hooks</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;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/hooks&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;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;turn.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prior</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;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;last-result&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> notes</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;"> ctx.host.files.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">read</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;notes.md&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;turn done&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ctx.session.id, event.data.usage, prior, notes);</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;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // page, count, or record</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Keys are event types (see the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>), or <code>&quot;*&quot;</code> for everything. Handlers receive the event with its envelope (<code>index</code>, <code>sessionId</code>, <code>turnId?</code>, <code>at</code>) and a <code>HookContext</code>:</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>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code> for the owning channel</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root. Prefer <code>ctx.host.kv</code> / <code>ctx.host.files</code> for derived state; this tree resets on hosted replace</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services; same as a tool&#39;s <code>ctx.host</code>. Pull JSON with <code>ctx.host.kv</code> and file-shaped state with <code>ctx.host.files</code> (session-bound by default; pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files)</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><p>Hook context includes <code>ctx.host</code>, the same shared services a tool gets. Persist JSON with <code>ctx.host.kv</code> and file-shaped state with <code>ctx.host.files</code>. Hooks observe; they do not own delivery surfaces.</p><h2 id="hooks-channel-events-evals-or-a-b" tabindex="-1">Hooks, channel events, evals, or A/B? <a class="header-anchor" href="#hooks-channel-events-evals-or-a-b" aria-label="Permalink to &quot;Hooks, channel events, evals, or A/B?&quot;">​</a></h2><p>All of them consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th><th>A/B (<code>defineAB</code>)</th></tr></thead><tbody><tr><td>Scope</td><td>every session on the agent</td><td>sessions the channel owns</td><td>one test turn</td><td>every live session; enrollment at creation, metrics on each turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td><td><code>ab.assigned</code> + fold stream → <code>onSample</code></td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td><td>yes through arm instructions or <code>session.abs</code>; collection is observe-only</td></tr><tr><td>Authored at</td><td><code>agent/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td><td><a href="./../ab.html"><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></a></td></tr></tbody></table><p>For GitHub merge-box checks and sticky PR banners, use <code>githubChannel({ progress: { commitStatus, banner } })</code> from <code>@cursor/july/channels/github</code>. That is the supported Autofix-style path. See <a href="./../guides/github.html#show-pr-progress">GitHub: Show PR progress</a>. Override channel <code>events</code> only when the lifecycle is custom, such as never-red status from tool output. Do not use <code>defineHook</code> for those writes.</p><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Usage metering: subscribe to <code>turn.completed</code> and forward <code>event.data.usage</code> (token counts) to your metrics system.</p><p>Failure alerting: <code>turn.failed</code> carries the message, and <code>ctx.session.id</code> points at the trace.</p><p>Derived state: persist ids that must survive hosted replace with <code>ctx.host.kv</code> or <code>ctx.host.files</code>. <code>stateRoot</code> resets on replace.</p><p>Transcript export: subscribe to <code>&quot;*&quot;</code> and append to your own store.</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="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li><li><a href="./../ab.html">Live A/B metrics</a>: sticky variants over the same event stream</li></ul>`,20)])])}const u=s(o,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/skills_framework-map.md.DDa4MeEW.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"}'),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/guides/cloud-runtime.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en-US" dir="ltr">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width,initial-scale=1">
-    <title>Cloud runtime | Agent SDK</title>
-    <meta name="description" content="Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.">
-    <meta name="generator" content="VitePress v1.6.4">
-    <link rel="preload stylesheet" href="/docs/assets/style.BRuM8477.css" as="style">
-    <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
-    
-    <script type="module" src="/docs/assets/app.CLA03RCz.js"></script>
-    <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/docs/assets/chunks/theme.DWCwM6p-.js">
-    <link rel="modulepreload" href="/docs/assets/chunks/framework.BCISBCiQ.js">
-    <link rel="modulepreload" href="/docs/assets/guides_cloud-runtime.md.BRirbRAN.lean.js">
-    <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
-    <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
-    <link rel="alternate" type="text/plain" href="/docs/llms.txt">
-    <link rel="alternate" type="text/markdown" href="/docs/guides/cloud-runtime.md">
-  </head>
-  <body>
-    <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.102" data-v-c26a5f4f>0.1.102</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/demo.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/code-wiki.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Code wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agents-md.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Living AGENTS.md</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-help.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security help</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible collapsed" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Coding-agent skills</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>ab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/create-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>create-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/debug.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>debug</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/framework-map.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>framework-map</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>github</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/hillclimb.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>hillclimb</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/mcp-auth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>mcp-auth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/otel.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>otel</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/skills/setup-slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>setup-slack</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cursor cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Extensions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_guides_cloud-runtime" data-v-2e506a34><div><h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cloud&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/org/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // env / envVars / … forwarded to the Cursor SDK</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 host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>).</p><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Cloud agents run against the Cursor backend under the signed-in account, and every wake spends real cloud-agent budget. Decide explicitly what may trigger one.</p></div><h2 id="what-changes-on-cloud" tabindex="-1">What changes on cloud <a class="header-anchor" href="#what-changes-on-cloud" aria-label="Permalink to &quot;What changes on cloud&quot;">​</a></h2><p>Cloud turns run on a VM without your authored files, so the runtime mapping shifts:</p><table tabindex="0"><thead><tr><th>Folder or file</th><th>Local runtime</th><th>Cloud runtime</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code> in the session workspace</td><td>prepended to the first prompt</td></tr><tr><td>Server tools (<code>execution: &quot;server&quot;</code>)</td><td>in-process SDK custom tools</td><td>authenticated HTTP MCP back to the AgentSDK host, when <code>--public-url</code> or <code>--cloud-tools-url</code> is set</td></tr><tr><td>Agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace</td><td>catalog + script bodies on the first prompt</td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/</code> in the workspace</td><td>native discovery after the first turn, from the hosted store or the signed-in account</td></tr><tr><td><code>mcp-connections/*.ts</code></td><td>SDK <code>mcpServers</code></td><td>SDK <code>mcpServers</code> (peers need <code>--public-url</code>)</td></tr><tr><td><code>host-connections/*.ts</code></td><td><code>ctx.host.mcp</code> only</td><td><code>ctx.host.mcp</code> only</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>seeded into the session workspace</td><td>ignored</td></tr><tr><td>Tool approvals (<code>needsApproval</code>)</td><td>supported</td><td>not supported; keep approval-gated tools on local turns</td></tr></tbody></table><p>Authored skills are discovered natively after the first cloud turn, using the hosted store or the signed-in account.</p><p>Approvals are a local-runtime contract. On cloud, a <code>needsApproval</code> tool call rides one HTTP MCP request from the VM, and a parked call would hold that request open until it times out; there is no durable approval flow for cloud turns.</p><p>Peer MCP connections need <code>--public-url</code> for cloud turns. Without one, peers are omitted and the server warns at startup.</p><h2 id="hybrid-local-agent-cloud-sessions" tabindex="-1">Hybrid: local agent, cloud sessions <a class="header-anchor" href="#hybrid-local-agent-cloud-sessions" aria-label="Permalink to &quot;Hybrid: local agent, cloud sessions&quot;">​</a></h2><p>A local-runtime agent can still open cloud-attached sessions per send. Channel handlers may pass a <code>cloud</code> block (repos pinned to a PR ref, say) in <code>send</code> options, and Slack handlers may return <code>cloud</code> from a mention hook. A PR driver works this way: chat stays local, and the <code>drive</code> flow attaches the PR to a cloud VM. The agent-level <code>cloud</code> config is the base that per-session options merge over.</p><h2 id="patterns-that-hold-up" tabindex="-1">Patterns that hold up <a class="header-anchor" href="#patterns-that-hold-up" aria-label="Permalink to &quot;Patterns that hold up&quot;">​</a></h2><p>These come from running a PR driver against real PR traffic:</p><ul><li>One cloud session per unit of work, keyed with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake lands on the same conversation.</li><li>Keep the host deterministic: fetch briefs and metadata on the host, send the VM a compact prompt, and let the VM re-read source of truth with its own <code>gh</code> and <code>git</code> instead of trusting payload snapshots.</li><li>Limit exposure: add repository allowlists on webhook channels, because every wake spends the account&#39;s budget.</li></ul><h2 id="verify-cloud-agents" tabindex="-1">Verify cloud agents <a class="header-anchor" href="#verify-cloud-agents" aria-label="Permalink to &quot;Verify cloud agents&quot;">​</a></h2><p><code>agent-sdk run</code> and <code>eval</code> work unchanged. The trajectory records the same event vocabulary plus <code>agent.bound</code> with the cloud URL, so you can open the cloud conversation for any session. Cloud turns take minutes. Pass generous <code>--timeout-ms</code> values, and keep curl timeouts long when driving channels directly.</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="./../reference/agent-config.html">Agent config</a>: the <code>runtime</code> and <code>cloud</code> fields</li><li><a href="./github.html">GitHub guide</a>: the webhook patterns that pair with cloud triage</li><li><a href="./cloud-agents.html">Cursor cloud agents</a>: keep the agent local and let it launch cloud agents instead</li></ul></div></div></main><footer class="VPDocFooter" data-v-2e506a34 data-v-574f06fa><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-574f06fa><span class="visually-hidden" id="doc-footer-aria-label" data-v-574f06fa>Pager</span><div class="pager" data-v-574f06fa><a class="VPLink link pager-link prev" href="/docs/guides/mcp-oauth.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Host MCP OAuth</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/guides/cloud-agents.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Cursor cloud agents</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"mlVgqvSk\",\"building-with-agents.md\":\"CUSWxlP_\",\"concepts.md\":\"rPzW2HZN\",\"deployment.md\":\"MFPKqsqI\",\"evals.md\":\"CPzDAwoH\",\"guides_agent-to-agent.md\":\"BDb0t1QV\",\"guides_cloud-agents.md\":\"DumwWXba\",\"guides_cloud-runtime.md\":\"BRirbRAN\",\"guides_convert-automation.md\":\"B4sjlodG\",\"guides_github.md\":\"BtPr9GaP\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Dp6cDP7f\",\"guides_opentelemetry.md\":\"BVTXDCRg\",\"guides_slack.md\":\"9oHPye9o\",\"guides_webhooks.md\":\"DKdA43Qm\",\"hillclimbing.md\":\"CpTGTCle\",\"index.md\":\"Kiht7ell\",\"quickstart.md\":\"DdQOF7Y8\",\"reference_agent-config.md\":\"BHeYMgme\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"Cd2f2iyV\",\"reference_cli.md\":\"DfoeyvL0\",\"reference_connections.md\":\"Di6jJAXF\",\"reference_extensions.md\":\"9WQMZe1l\",\"reference_hooks.md\":\"a8BJxMR5\",\"reference_http-api.md\":\"oySXBO8o\",\"reference_instructions.md\":\"CR7XSsGk\",\"reference_playground.md\":\"DnX5nL-B\",\"reference_project-layout.md\":\"CA6QP6Lw\",\"reference_prompt.md\":\"DnaD5dNK\",\"reference_schedules.md\":\"DI_JrHgq\",\"reference_sessions.md\":\"NxFP_CAC\",\"reference_skills.md\":\"l2ezAcaN\",\"reference_subagents.md\":\"CfsIloPm\",\"reference_tools.md\":\"B1up2r9W\",\"scaffolding-agents.md\":\"em43xlY1\",\"skills_ab.md\":\"CsFNatVx\",\"skills_create-agent.md\":\"BVoWPcan\",\"skills_debug.md\":\"CDbPhHfg\",\"skills_evals.md\":\"723kpUmA\",\"skills_framework-map.md\":\"DDa4MeEW\",\"skills_github.md\":\"D0JahM8c\",\"skills_hillclimb.md\":\"B_zJerxA\",\"skills_index.md\":\"DKwIxzGg\",\"skills_mcp-auth.md\":\"DGvFP3HE\",\"skills_otel.md\":\"CgiZryR3\",\"skills_setup-slack.md\":\"BBgx8lUz\",\"storage.md\":\"BOHeqk2M\",\"templates_agentic-owners.md\":\"BZSH4N9z\",\"templates_agents-md.md\":\"CXSMZljE\",\"templates_code-wiki.md\":\"CDYZIBFN\",\"templates_demo.md\":\"BeQX9V3H\",\"templates_pr-autofixer.md\":\"x5zl6-GT\",\"templates_security-help.md\":\"C3Ny_Qr2\",\"templates_security-reviewer.md\":\"lshxbCLK\",\"templates_triage.md\":\"Co4UNzkZ\",\"troubleshooting.md\":\"Cus_YZga\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.102\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Templates\",\"link\":\"/templates/demo\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Code wiki\",\"link\":\"/templates/code-wiki\"},{\"text\":\"Living AGENTS.md\",\"link\":\"/templates/agents-md\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Security help\",\"link\":\"/templates/security-help\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Coding-agent skills\",\"collapsed\":true,\"items\":[{\"text\":\"Overview\",\"link\":\"/skills/\"},{\"text\":\"ab\",\"link\":\"/skills/ab\"},{\"text\":\"create-agent\",\"link\":\"/skills/create-agent\"},{\"text\":\"debug\",\"link\":\"/skills/debug\"},{\"text\":\"evals\",\"link\":\"/skills/evals\"},{\"text\":\"framework-map\",\"link\":\"/skills/framework-map\"},{\"text\":\"github\",\"link\":\"/skills/github\"},{\"text\":\"hillclimb\",\"link\":\"/skills/hillclimb\"},{\"text\":\"mcp-auth\",\"link\":\"/skills/mcp-auth\"},{\"text\":\"otel\",\"link\":\"/skills/otel\"},{\"text\":\"setup-slack\",\"link\":\"/skills/setup-slack\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"Cursor cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Extensions\",\"link\":\"/reference/extensions\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
-    
-  </body>
-</html>

package/dist/docs/guides/cloud-runtime.md

@@ -1,117 +0,0 @@
-# Cloud runtime
-
-By default, turns execute on the Cursor SDK's local harness, on the same
-machine as the server. Set `runtime: "cloud"` and turns execute on
-Cursor cloud agents instead. They're ephemeral VMs that carry a repo
-checkout, run `gh`, `git`, and tests for real, and scale past what one
-host's disk and CPU can do. The serve host keeps handling routing, host
-preparation, sessions, and bookkeeping.
-
-A canonical use is a PR driver whose triage runs on cloud VMs. The
-patterns in this guide come from running one against real PR traffic.
-
-## When to switch
-
-A guideline from running PR agents at scale: per-PR worktrees on the serve host
-don't scale to hundreds of engineers opening PRs. When the job needs a
-repo checkout at scale, use cloud. The signals:
-
-- The agent must run repo commands (tests, builds, `git`) against many
-  different refs concurrently.
-- Turns are long and heavy, and you don't want them competing with the
-  server for resources.
-- The work product is a PR or branch the VM can push, not a local file.
-
-Stay local when the agent is conversational, tool-driven against APIs,
-or works over host-prepared evidence. Local turns are cheaper, start
-faster, and support the full authored surface.
-
-## Configure it
-
-Cloud runtime is two fields on the agent config.
-
-```ts
-import { defineAgent } from "@cursor/july";
-
-export default defineAgent({
-  runtime: "cloud",
-  cloud: {
-    repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
-    // env / envVars / … forwarded to the Cursor SDK
-  },
-});
-```
-
-The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
-
-> [!IMPORTANT]
-> Cloud agents run against the Cursor backend under the signed-in
-> account, and every wake spends real cloud-agent budget. Decide
-> explicitly what may trigger one.
-
-## What changes on cloud
-
-Cloud turns run on a VM without your authored files, so the runtime
-mapping shifts:
-
-| Folder or file | Local runtime | Cloud runtime |
-| --- | --- | --- |
-| `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
-| Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
-| Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
-| `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
-| `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
-| `host-connections/*.ts` | `ctx.host.mcp` only | `ctx.host.mcp` only |
-| `sandbox/workspace/**` | seeded into the session workspace | ignored |
-| Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
-
-Authored skills are discovered natively after the first cloud turn,
-using the hosted store or the signed-in account.
-
-Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
-call rides one HTTP MCP request from the VM, and a parked call would
-hold that request open until it times out; there is no durable approval
-flow for cloud turns.
-
-Peer MCP connections need `--public-url` for cloud turns. Without one,
-peers are omitted and the server warns at startup.
-
-## Hybrid: local agent, cloud sessions
-
-A local-runtime agent can still open cloud-attached sessions per send.
-Channel handlers may pass a `cloud` block (repos pinned to a PR ref, say)
-in `send` options, and Slack handlers may return `cloud` from a mention
-hook. A PR driver works this way: chat stays local, and the `drive`
-flow attaches the PR to a cloud VM. The agent-level `cloud` config is the
-base that per-session options merge over.
-
-## Patterns that hold up
-
-These come from running a PR driver against real PR traffic:
-
-- One cloud session per unit of work, keyed with a stable continuation
-  token (`pr:owner/repo#N`) so every wake lands on the same conversation.
-- Keep the host deterministic: fetch briefs and metadata on the host,
-  send the VM a compact prompt, and let the VM re-read source of truth
-  with its own `gh` and `git` instead of trusting payload snapshots.
-- Limit exposure: add repository allowlists on webhook channels,
-  because every wake spends the account's budget.
-
-## Verify cloud agents
-
-`agent-sdk run` and `eval` work unchanged. The trajectory records the
-same event vocabulary plus `agent.bound` with the cloud URL, so you can
-open the cloud conversation for any session. Cloud turns take minutes.
-Pass generous `--timeout-ms` values, and keep curl timeouts long when
-driving channels directly.
-
-## What's next
-
-Continue with these pages:
-
-- [Agent config](/docs/reference/agent-config.md): the `runtime` and
-  `cloud` fields
-- [GitHub guide](/docs/guides/github.md): the webhook patterns that pair with
-  cloud triage
-- [Cursor cloud agents](/docs/guides/cloud-agents.md): keep the agent local and
-  let it launch cloud agents instead

package/dist/internal/convert-automation/index.d.ts

@@ -1,3 +0,0 @@
-export { convertWorkflow } from "./convert-workflow.js";
-export type { ConvertAutomationMetadata, ConvertedFile, ConvertedMcpConnection, ConvertMcpServer, ConvertWorkflowInput, ConvertWorkflowResult, WorkflowJson, } from "./types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/internal/convert-automation/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/convert-automation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,yBAAyB,EACzB,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/internal/convert-automation/index.js

@@ -1 +0,0 @@
-export { convertWorkflow } from "./convert-workflow.js";

package/dist/internal/grokbot/runner.d.ts

@@ -1,64 +0,0 @@
-/**
- * The grokbot runtime's remote client — a thin client like `"cloud"`.
- * Turns execute on Cursor's hosted Grok Bot (Sand) harness (the Temporal
- * turn workflow and the account's own computer), reached through the
- * public `/v0/grokbot` session API.
- *
- * Sand delivery contract, preserved end to end: only content the agent
- * delivers through SendToUser becomes the user-visible reply. The hosted
- * transcript exposes those deliveries as `send-message` entries; the
- * agent's internal monologue never appears in the transcript, so it can
- * never leak into the session reply.
- */
-import type { RunnerTurnRequest, TurnOutcome } from "../../types.js";
-import type { AgentRunner } from "./../sdk-runner.js";
-export interface GrokBotRunnerOptions {
-    /** Cursor API key. Resolved as option → env → file → stored login. */
-    apiKey?: string;
-    /** Test seam. Defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-    /**
-     * Test seam. Defaults to {@link cursorExternalApiUrl} (`api.cursor.com`).
-     * `/v0/grokbot` is an external-api microlith route — it 404s on api2.
-     */
-    backendUrl?: string;
-    /** Test seam. Poll interval while a turn runs. */
-    pollIntervalMs?: number;
-    /** Test seam. Hard turn deadline. */
-    turnTimeoutMs?: number;
-}
-/** One transcript entry as `/v0/grokbot/sessions/:id/entries` exposes it. */
-export interface GrokBotEntry {
-    seq: string;
-    updatedSeq: string;
-    kind: string;
-    role?: string;
-    text?: string;
-    createdAtMs: number;
-}
-export declare class GrokBotRunner implements AgentRunner {
-    private readonly options;
-    /**
-     * One hosted Grok Bot agent per SDK agent name — the backend
-     * get-or-creates by name, so every SDK session forwards into the same
-     * hosted agent and conversation, and the Grok Bot app shows one agent
-     * rather than one per session.
-     */
-    private readonly agents;
-    /**
-     * Per-hosted-agent turn chain. Sessions share one hosted conversation
-     * and one transcript cursor, so turns run one at a time per agent:
-     * deliveries attribute to the turn that sent them, and an abort only
-     * interrupts its own turn — mirroring the hosted workflow's own queue.
-     */
-    private readonly turns;
-    private client;
-    constructor(options?: GrokBotRunnerOptions);
-    runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
-    private executeTurn;
-    dispose(): Promise<void>;
-    private ensureClient;
-    private getAgent;
-    private sleep;
-}
-//# sourceMappingURL=runner.d.ts.map

package/dist/internal/grokbot/runner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/internal/grokbot/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAKrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAuID,qBAAa,aAAc,YAAW,WAAW;IAiBnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,MAAM,CAA+B;IAE7C,YAA6B,OAAO,GAAE,oBAAyB,EAAI;IAE7D,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB9D;YAEa,WAAW;IAiFnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAI7B;IAED,OAAO,CAAC,YAAY;YAKN,QAAQ;YAyBR,KAAK;CAgBpB"}