@cursor/july 0.1.34 → 0.1.36

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

@@ -1,9 +0,0 @@
-import{_ as t,c as s,o,ag as a}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return 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</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>only if present in the cloud repo</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>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>supported for server tools</td></tr></tbody></table><p>Hosted deployments configure the server-tool MCP URL automatically. A self-hosted public server needs <code>--public-url</code> (and <code>--bearer-token</code> when the host is not behind another trusted authentication boundary) so cloud turns can reach those tools.</p><p>Two more behaviors are cloud-specific. Sessions persist a separate SDK agent id (<code>bc-…</code>), emitted on the stream as <code>agent.bound</code> with a URL to the cloud conversation. Cloud ids are minted during the first send. And peer MCP connections resolve to <code>--public-url</code> for cloud turns, because a VM cannot reach the host&#39;s loopback; without one, peers are omitted from cloud turns 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 agent per unit of work (per PR, say). Store the <code>bc-…</code> id keyed by the work unit (an affinity store written from an <code>agent.bound</code> hook) so webhook wakes resume the same conversation instead of booting a fresh VM per event.</li><li>Stable continuation keys (<code>pr:owner/repo#N</code>) so every wake lands on the same session within a channel.</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 precisely</li><li><a href="./github.html">GitHub guide</a>: the webhook patterns that pair with cloud triage</li></ul>`,27)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

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

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

package/dist/docs/assets/index.md.CZqbBJPB.js

@@ -1,20 +0,0 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"Agent SDK documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function o(r,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="agent-sdk-documentation" tabindex="-1">Agent SDK documentation <a class="header-anchor" href="#agent-sdk-documentation" aria-label="Permalink to &quot;Agent SDK documentation&quot;">​</a></h1><p>The Agent SDK helps you build your own software factory: agents that inspect builds, review pull requests, gate promotions, and wake from Slack or GitHub when work arrives. You author each agent as ordinary files in a TypeScript project under <code>agent/</code>: markdown for agent instruction prompts, TypeScript for typed behavior. The framework discovers those files, and serves the agent over channels. The Cursor SDK and the Cursor harness run the turns.</p><p>You write the tools, instructions, channels, and evals. In return you get a factory you can version, test, and ship: side effects stay behind human approvals, and every change stays regression-checked.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
-<span class="line"><span>├── package.json</span></span>
-<span class="line"><span>├── agent/</span></span>
-<span class="line"><span>│   ├── agent.ts             # runtime config: model, local/cloud runtime</span></span>
-<span class="line"><span>│   ├── instructions.md      # the always-on system prompt</span></span>
-<span class="line"><span>│   ├── tools/               # one typed tool per file</span></span>
-<span class="line"><span>│   ├── skills/              # on-demand procedures (SKILL.md convention)</span></span>
-<span class="line"><span>│   ├── mcp-connections/     # tools from external MCP servers</span></span>
-<span class="line"><span>│   ├── subagents/           # specialist child agents</span></span>
-<span class="line"><span>│   ├── channels/            # HTTP / Slack / GitHub surfaces</span></span>
-<span class="line"><span>│   ├── hooks/               # observe the runtime event stream</span></span>
-<span class="line"><span>│   ├── ab.ts                # optional live A/B experiment</span></span>
-<span class="line"><span>│   ├── ab/                  # optional: more experiments</span></span>
-<span class="line"><span>│   ├── schedules/           # cron-driven runs</span></span>
-<span class="line"><span>│   ├── sandbox/workspace/   # files seeded into each session workspace</span></span>
-<span class="line"><span>│   └── lib/                 # shared code (import-only, never discovered)</span></span>
-<span class="line"><span>└── evals/                   # filesystem evals (regression checks)</span></span></code></pre></div><p>Browse it locally without serving an agent:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span></span></code></pre></div><p>Every running serve host also mounts this documentation at <code>/docs</code> (disable it with <code>--no-docs</code>).</p><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><p>Pick your entry point based on your goal.</p><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to the Agent SDK</td><td><a href="./quickstart.html">Quickstart</a> (PR approver), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Driving an agent from Linear (or another tracker)</td><td><a href="./guides/webhooks.html#example-linear-as-the-control-plane">Webhooks guide: Linear example</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="the-documentation" tabindex="-1">The documentation <a class="header-anchor" href="#the-documentation" aria-label="Permalink to &quot;The documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR approver that reviews by complexity and wakes from webhooks.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./concepts.html">Concepts</a>: the mental model behind the framework.</li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: make an agent better one measured round at a time.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: wake the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and <code>--store</code> them on hosted deployments.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare all eleven agents by runtime, channels, tools, state, and architecture.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/fsd.html">Remote PR coordinator</a>: hand PR triage from local chat and webhooks to durable remote sessions.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: symptom to cause, in plain language.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>The docs write commands as <code>agent-sdk &lt;command&gt;</code>. Where that command comes from depends on where you run.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>When running from a source checkout there is no installed bin. Alias it from the package directory:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> packages/agent-serve</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">alias</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> agent-sdk</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pnpm exec tsx </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/src/bin/agent-serve.ts&quot;</span></span></code></pre></div><p>When <code>@cursor/july</code> is installed as a dependency, the <code>agent-sdk</code> bin is on your package manager&#39;s path (<code>pnpm exec agent-sdk</code>, <code>npx agent-sdk</code>). <code>npx @cursor/july docs</code> runs the <code>july</code> bin with that command (no local install required).</p></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The framework is being renamed from agent-serve to the Agent SDK, and CLI examples use the new <code>agent-sdk</code> name. Paths, package imports, and environment variables keep their current names until the code rename ships:</p><table tabindex="0"><thead><tr><th>Docs say</th><th>Current name</th></tr></thead><tbody><tr><td><code>@cursor/july</code> imports and dependency</td><td><code>@cursor/july</code></td></tr><tr><td><code>agent-sdk</code> bin</td><td><code>agent-serve</code></td></tr><tr><td><code>dist/bin/agent-sdk.js</code></td><td><code>dist/bin/agent-serve.js</code></td></tr><tr><td><code>.agent-sdk/</code> state directory</td><td><code>.agent-serve/</code></td></tr><tr><td><code>/var/lib/agent-sdk</code> (deploy state root)</td><td><code>/var/lib/agent-serve</code></td></tr><tr><td><code>CURSOR_AGENT_SDK_*</code> env vars</td><td><code>AGENT_SERVE_*</code></td></tr><tr><td><code>agent-sdk (&lt;hostname&gt;)</code> API key name</td><td><code>agent-serve (&lt;hostname&gt;)</code></td></tr><tr><td>Package path <code>packages/agent-sdk</code></td><td><code>packages/agent-serve</code></td></tr><tr><td>Package skills <code>packages/agent-sdk/skills/</code></td><td><code>packages/agent-serve/skills/</code></td></tr></tbody></table></div><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Run the Agent SDK with Node 22.13 or newer, and never with Bun. Bun&#39;s HTTP/2 client corrupts the Cursor SDK&#39;s tool-result streams (<code>NGHTTP2_FRAME_SIZE_ERROR</code>), so every built-in read or grep the model makes fails and turns degrade into minutes-long retry loops.</p></div><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Model turns run on the Cursor harness, so the serving host needs a Cursor credential. Sign in once, or export an API key:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # browser sign-in; mints + stores a revocable API key</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">         # which account powers this host, and why</span></span></code></pre></div><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><p>These docs describe behavior. The package <a href="./../README.html"><code>README.md</code></a> is the compact reference, and <a href="./../AGENTS.html"><code>AGENTS.md</code></a> is the coding-agent cheat sheet. Task-shaped guides that ship with the package live under <a href="./../skills/"><code>skills/</code></a>; point a coding agent working on an Agent SDK project at them first. When the docs and the code disagree, the code is authoritative. Fix the doc.</p>`,33)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};

package/dist/docs/assets/reference_http-api.md.CfVM_ICa.js

@@ -1,11 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"HTTP API","description":"Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch.","frontmatter":{"title":"HTTP API","description":"Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,h,c){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="http-api-reference" tabindex="-1">HTTP API reference <a class="header-anchor" href="#http-api-reference" aria-label="Permalink to &quot;HTTP API reference&quot;">​</a></h1><p>Every Agent SDK host speaks the same stable HTTP API. In the default multi-agent layout each agent is namespaced under its slug (<code>/&lt;slug&gt;/v1/session</code>, <code>/&lt;slug&gt;/playground</code>), with host-level routes at the root. With <code>--mode single</code>, one agent serves the same surface unslugged (<code>/v1/*</code>).</p><p>Unless noted otherwise, routes run the agent&#39;s HTTP auth chain: the default is <code>localDevStrict()</code> (loopback only), replaced by <code>bearerAuth</code> under <code>--bearer-token</code> or <code>allowAll()</code> under <code>--allow-anonymous</code>. Session routes also require the caller to be the session&#39;s owner (<code>403</code> otherwise). Errors return JSON <code>{ ok: false, error: &quot;&lt;code&gt;&quot;, message? }</code> with a matching HTTP status.</p><h2 id="host-level-routes-multi-agent-mode" tabindex="-1">Host-level routes (multi-agent mode) <a class="header-anchor" href="#host-level-routes-multi-agent-mode" aria-label="Permalink to &quot;Host-level routes (multi-agent mode)&quot;">​</a></h2><p>These routes live at the host root, above any agent. The two index routes exist only while the playground is enabled (<code>--no-playground</code> removes them) and run no auth. The documentation site is mounted in both layouts and removed by <code>--no-docs</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /</code></td><td>A web index of every mounted agent, linking to playgrounds (playground only)</td></tr><tr><td><code>GET /v1/agents</code></td><td>The JSON index of mounted agents (playground only, no auth)</td></tr><tr><td><code>GET /docs</code>, <code>GET /docs/*</code></td><td>This documentation, served as a static site (both layouts, no auth)</td></tr><tr><td><code>GET /v1/health</code></td><td>Host-level liveness, no auth; made for ALB/ECS checks</td></tr><tr><td><code>POST /v1/webhooks/github</code></td><td>Loopback-only trigger endpoint that fans a GitHub-shaped payload out to every mounted GitHub channel (used by local tooling)</td></tr></tbody></table><h2 id="start-a-session" tabindex="-1">Start a session <a class="header-anchor" href="#start-a-session" aria-label="Permalink to &quot;Start a session&quot;">​</a></h2><p><code>POST /v1/session</code> opens a durable conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends; when the turn can&#39;t be interrupted (for example, concurrent follow-ups racing), the request returns <code>409 session_busy</code>.</p><p>Expect <code>409</code> on a stale token, an uninterruptible busy session, or a task/schedule session (those aren&#39;t followable), and <code>403</code> when the caller isn&#39;t the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#the-event-vocabulary">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns the same content as a one-shot dump with no live follow.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;input&quot;:{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}}&#39;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;toolName&quot;:&quot;inspect_pr&quot;,&quot;callId&quot;:&quot;tool_inspect_pr_…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><p>It runs an authored server tool in-process: schema-validated, no model turn. An optional <code>&quot;sessionId&quot;</code> in the body runs it inside an existing session and records it on that session&#39;s stream (<code>409 session_busy</code> while a turn runs). Agent-execution tools are rejected with <code>400</code>, and unknown tools with <code>404</code> and the list of available names. For the semantics, see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>.</p><h2 id="discovery-and-meta" tabindex="-1">Discovery and meta <a class="header-anchor" href="#discovery-and-meta" aria-label="Permalink to &quot;Discovery and meta&quot;">​</a></h2><p>Five read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>The manifest snapshot: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics; the same shape as <code>agent-sdk info --json</code></td></tr><tr><td><code>GET /v1/health</code></td><td>Per-agent liveness, no auth</td></tr><tr><td><code>GET /v1/meta</code></td><td>SPA bootstrap: agent name, dev flag, base path (no auth)</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Recent server log lines from the ring buffer, with a polling cursor</td></tr><tr><td><code>GET /v1/abs</code></td><td><a href="./../ab.html">Live A/B metrics</a>: per-session assignments and aggregate arm totals folded from durable event streams (<code>config</code> reports <code>maxPlaygroundSessions</code> / <code>durableSamples</code> / <code>durableSnapshots</code> from <code>agent/ab.config.ts</code>)</td></tr></tbody></table><h2 id="custom-channel-routes" tabindex="-1">Custom channel routes <a class="header-anchor" href="#custom-channel-routes" aria-label="Permalink to &quot;Custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with the methods, paths, and Zod schemas the channel declared (a <code>POST /&lt;slug&gt;/v1/channels/drive</code> route, say). Bodies are validated before handlers run (<code>400</code> on schema violations), and each channel&#39;s auth chain applies. The GitHub channel verifies <code>X-Hub-Signature-256</code> when a secret is configured. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p><code>/v1/mcp</code> serves the Model Context Protocol over streamable HTTP (stateless; POST carries the protocol, and GET/DELETE return spec-compliant 405s). The tools are <code>ask</code> (delegate a message, bounded waits), <code>check</code> (poll a running session), and <code>call_tool</code> (deterministic server-tool passthrough, present when the agent has server tools). The route runs the same auth chain as the session API. See <a href="./../guides/agent-to-agent.html">Agent-to-agent</a>.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>Always registered (including production / non-<code>--dev</code> serves). The playground Evals tab uses these:</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered eval datapoints and project config as <code>{ evals, config }</code> (<code>config</code> includes <code>maxPlaygroundRuns</code>, <code>durableRuns</code>)</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots (newest first) as <code>{ runs, activeRunId? }</code> for playground rehydrate</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start an eval run (<code>{filterIds?, tags?}</code>); <code>202</code> with a snapshot (<code>runId</code> is the Eval ID), <code>404</code> when nothing matches, <code>409</code> when one is running</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Poll a run&#39;s progress</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel a running batch; <code>200</code> with snapshot, <code>404</code> unknown, <code>409</code> when not running</td></tr></tbody></table><p>Eval runs are asynchronous. Poll the run route for case progress and the final <code>completed</code> or <code>failed</code> status. Batch errors appear on the snapshot returned by the poll. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics. When both fields are present, a case must match one entry from each field. Without <code>persistRuns</code> in <code>evals.config.ts</code>, listed runs are process-memory only (capped by <code>maxPlaygroundRuns</code>).</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once, through the production path. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes are the only way they run, which keeps iteration deterministic.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the static SPA bundle (omitted with <code>--no-playground</code>). The playground calls the JSON API above and has no privileged surface.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Error responses use a small, consistent set of status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning here</th></tr></thead><tbody><tr><td><code>400</code></td><td>Schema-invalid body or query, agent-execution tool called on the host, malformed request</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>Authenticated, but not the session owner</td></tr><tr><td><code>404</code></td><td>Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request</td></tr><tr><td><code>405</code></td><td>Wrong method (GET on the MCP endpoint, say)</td></tr><tr><td><code>409</code></td><td>Stale continuation token, busy session (<code>session_busy</code>), a non-followable task session, or an eval run already in progress</td></tr><tr><td><code>202</code></td><td>Accepted for background work (GitHub <code>{ task }</code> hooks, eval runs)</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./sessions.html">Sessions and streaming</a>: the handles and events these routes traffic in</li><li><a href="./channels.html">Channels</a>: authoring your own routes</li><li><a href="./../deployment.html">Deployment</a>: auth on real hosts</li></ul>`,53)])])}const k=t(n,[["render",d]]);export{u as __pageData,k as default};

package/dist/docs/assets/reference_http-api.md.CfVM_ICa.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"HTTP API","description":"Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch.","frontmatter":{"title":"HTTP API","description":"Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,h,c){return a(),s("div",null,[...e[0]||(e[0]=[o("",53)])])}const k=t(n,[["render",d]]);export{u as __pageData,k as default};

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

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