@cursor/july 0.1.109 → 0.1.111

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

@@ -1,5 +0,0 @@
-import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function n(o,e,l,h,d,c){return r(),a("div",null,[...e[0]||(e[0]=[s(`<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>Use the Agent SDK to define Cursor agents in TypeScript and Markdown. See <a href="./reference/project-layout.html">Project layout</a> for the directory structure.</p><p>Use Node 22.13 or newer. Bun isn&#39;t supported.</p><p>Create a project:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>If <code>agent-sdk</code> isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><p>Open the docs locally:</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><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><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 reviewer), 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>Turning a Cursor Automation into a project</td><td><a href="./guides/convert-automation.html">Convert a Cursor Automation</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Starting from a packaged template</td><td><a href="./templates/demo.html">Demo</a>, <a href="./templates/grokbot-agents.html">Grok Bot agents</a>, <a href="./templates/code-wiki.html">Code wiki</a>, <a href="./templates/agents-md.html">Living AGENTS.md</a>, <a href="./templates/security-reviewer.html">Security reviewer</a>, <a href="./templates/security-help.html">Security help</a>, <a href="./templates/triage.html">Triage</a>, or <a href="./templates/agentic-owners.html">Agentic Owners</a></td></tr><tr><td>Wiring an agent to GitHub or GitHub Enterprise Server</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Wiring an agent to GitLab</td><td><a href="./guides/gitlab.html">GitLab guide</a></td></tr><tr><td>Wiring an agent to Bitbucket</td><td><a href="./guides/bitbucket.html">Bitbucket guide</a></td></tr><tr><td>Driving PRs from a cloud VM</td><td><a href="./templates/pr-autofixer.html">PR autofixer template</a></td></tr><tr><td>Handing coding work to Cursor cloud agents</td><td><a href="./guides/cloud-agents.html">Cursor cloud agents</a></td></tr><tr><td>Talking to your Grok Bot agents</td><td><a href="./guides/grokbot-agents.html">Cursor Grok Bot agents</a></td></tr><tr><td>Letting an agent change its own source</td><td><a href="./guides/improve.html">Self-improvement</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>Gating agent behavior in CI</td><td><a href="./evals.html#run-evals-in-ci">Run evals in CI</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="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR reviewer that classifies changes by complexity and handles GitHub webhook events.</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="./guides/convert-automation.html">Convert a Cursor Automation</a>: export a dashboard Automation into an Agent SDK project.</li><li><a href="./concepts.html">Concepts</a>: agent discovery, sessions, channels, runtimes, and observability.</li></ul><p><strong>Templates</strong></p><ul><li><a href="./templates/demo.html">Record a walkthrough from a collected PR</a>: host collects the PR, the model records, then comments.</li><li><a href="./templates/grokbot-agents.html">Talk to your Grok Bot agents</a>: name the bots, then consult them from this agent&#39;s own conversation.</li><li><a href="./templates/code-wiki.html">Keep a code wiki current after merge</a>: update in-repo <code>wiki/</code> pages when a pull request merges.</li><li><a href="./templates/agents-md.html">Keep AGENTS.md current from last week&#39;s work</a>: pull rules out of merged PRs and Slack, then open a follow-up PR.</li><li><a href="./templates/security-reviewer.html">Security reviewer</a>: review pull requests for exploitable bugs and post one comment.</li><li><a href="./templates/security-help.html">Answer security questions in Slack</a>: answer from your skills, or take a first look at a pasted PR.</li><li><a href="./templates/triage.html">Triage Linear or Jira issues in place</a>: classify existing tickets and comment on them.</li><li><a href="./templates/agentic-owners.html">Review pull requests with owners policies</a>: request owners and approve changes allowed by repository policy.</li><li><a href="./templates/pr-autofixer.html">Fix pull requests on a Cursor cloud VM</a></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, assert over the trajectory, and run them locally and in CI.</li><li><a href="./storage.html">Storage</a>: point durable storage at a backend you own with <code>defineStorage</code>.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: measure and improve an agent iteratively.</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>: trigger the agent from pull requests, CI, and comments.</li><li><a href="./guides/gitlab.html">GitLab</a>: trigger the agent from merge requests, notes, pipelines, and pushes.</li><li><a href="./guides/bitbucket.html">Bitbucket</a>: trigger the agent from pull requests, comments, and pushes.</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 persist them on hosted deployments (<code>--store</code>).</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-agents.html">Cursor cloud agents</a>: let the agent launch and steer cloud agents through the <code>cursor-cloud-agents</code> extension.</li><li><a href="./guides/grokbot-agents.html">Cursor Grok Bot agents</a>: let the agent talk to Grok Bot agents through the <code>cursor-grokbot-agents</code> extension.</li><li><a href="./guides/improve.html">Self-improvement</a>: let the agent change its own source through a one-off cloud agent and a pull request with the <code>improve</code> extension.</li><li><a href="./guides/opentelemetry.html">OpenTelemetry</a>: push session, turn, and tool traces to an OTLP collector you run.</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>: diagnose common failures by symptom.</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> · <a href="./reference/extensions.html">Extensions</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/artifacts.html">Artifacts</a> · <a href="./reference/result.html">Turn result</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>Docs use <code>agent-sdk &lt;command&gt;</code>. If it isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Sign in to Cursor or set <code>CURSOR_API_KEY</code>:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</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></code></pre></div><p>Confirm <code>agent-sdk whoami</code> shows the expected account.</p><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><ul><li>Package reference: <a href="./../README.html"><code>README.md</code></a></li><li>Coding-agent workflows: <a href="./skills/"><code>skills/</code></a></li></ul>`,31)])])}const p=t(i,[["render",n]]);export{g as __pageData,p as default};

package/dist/docs/assets/index.md.DD9Q2XuJ.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function n(o,e,l,h,d,c){return r(),a("div",null,[...e[0]||(e[0]=[s("",31)])])}const p=t(i,[["render",n]]);export{g as __pageData,p as default};

package/dist/docs/assets/quickstart.md.DdQOF7Y8.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build your first PR reviewer","description":"Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),t={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[h("",52)])])}const o=i(t,[["render",l]]);export{g as __pageData,o as default};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/docs/assets/skills_github.md.hgFX_oKY.js

@@ -1,16 +0,0 @@
-import{_ as i,c as t,o as a,ag as e}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"GitHub channels in the Agent SDK","description":"Build and test GitHub-driven Agent SDK agents: githubChannel hooks (auth turn vs host task), cursorAccount / --cursor-events, and local test tiers (fixtures, replay, forward). Use when wiring GitHub events or debugging delivery.","frontmatter":{"name":"agentsdk-github","description":"Build and test GitHub-driven Agent SDK agents: githubChannel hooks (auth turn vs host task), cursorAccount / --cursor-events, and local test tiers (fixtures, replay, forward). Use when wiring GitHub events or debugging delivery."},"headers":[],"relativePath":"../skills/github/SKILL.md","filePath":"../skills/github/SKILL.md"}'),n={name:"../skills/github/SKILL.md"};function h(l,s,k,p,o,d){return a(),t("div",null,[...s[0]||(s[0]=[e(`<h1 id="github-channels-in-the-agent-sdk" tabindex="-1">GitHub channels in the Agent SDK <a class="header-anchor" href="#github-channels-in-the-agent-sdk" aria-label="Permalink to &quot;GitHub channels in the Agent SDK&quot;">​</a></h1><p>Author <code>agent/channels/github.ts</code>. Production wakes: <code>cursorAccount</code> + <code>serve --cursor-events</code>. No public webhook URL. Use the HTTP route for fixtures, replay, and hosts that already terminate GitHub webhooks.</p><p>Guide: <code>docs/guides/github.md</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;"> { defaultGitHubAuth, githubChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/github&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;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cursorAccount: { repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// permissions?: &quot;read&quot; | &quot;pr-write&quot; | &quot;contents-write&quot;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onPullRequest</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 style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    pr.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;opened&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onCheckSuite</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 style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">suite</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    suite.conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;failure&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> triage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Hooks: <code>onPullRequest</code>, <code>onComment</code>, <code>onIssue</code>, <code>onCheckSuite</code>, <code>onCheckRun</code>, <code>onWorkflowRun</code>, <code>onStatus</code>, plus <code>onEvent</code> and <code>onStart</code>/<code>onStop</code>.</p><table tabindex="0"><thead><tr><th>Return</th><th>Meaning</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Model turn. Session shows in the playground. <code>workspaceFiles</code> can be a function.</td></tr><tr><td><code>{ task }</code></td><td>Host work. No chat session. Use when the work can outlive a webhook timeout.</td></tr><tr><td><code>null</code></td><td>Skip</td></tr></tbody></table><p>To keep repo scope in deploy config, use <code>cursorAccount: true</code> and pass <code>--repo owner/name</code> at serve / <code>--cursor-events-repo</code> at deploy. Repos must share one GitHub owner.</p><h2 id="event-sources" tabindex="-1">Event sources <a class="header-anchor" href="#event-sources" aria-label="Permalink to &quot;Event sources&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Source</th><th>When</th></tr></thead><tbody><tr><td><code>cursorAccount</code> + <code>serve --cursor-events</code></td><td>Preferred. Signed-in host (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>). Repos from the channel and from repeatable <code>--repo owner/name</code>. Cap 20, one GitHub owner</td></tr><tr><td>HTTP <code>POST /&lt;slug&gt;/v1/channels/github</code> with a webhook secret</td><td><code>allowAll()</code> + <code>X-Hub-Signature-256</code></td></tr><tr><td>HTTP, no secret</td><td>Loopback only. <code>serve --dev</code> also admits unsigned loopback (fixtures / forward)</td></tr></tbody></table><p><code>permissions</code>: <code>&quot;read&quot;</code> inspect; <code>&quot;pr-write&quot;</code> (default) comments / PR writes; <code>&quot;contents-write&quot;</code> push or merge-box checks. <code>progress.commitStatus</code> needs check-write; see the GitHub guide. Set <code>checks: true</code> when channel code posts its own Checks API runs through <code>ctx.github.createCheck</code>. The flag grants access. It does not post a check.</p><p>Without <code>cursorAccount</code>, outbound calls prefer App installation tokens (<code>GITHUB_APP_ID</code> + <code>GITHUB_APP_PRIVATE_KEY</code>). Local tests can use <code>GITHUB_TOKEN</code> / <code>gh auth login</code>.</p><p>The Cursor stream is metadata, not full webhook bodies. Re-read the PR from GitHub.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><ol><li><strong>Fixtures</strong> (offline, <code>--dev</code>, no signature):</li></ol><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;"> -s</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/channels/github</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;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;x-github-event: pull_request&#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;"> @fixtures/github/pull_request.synchronize.json</span></span></code></pre></div><ol start="2"><li><strong>Replay</strong> (hillclimb tier; pull access is enough):</li></ol><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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">projec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">projec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;*&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --out</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> fixtures/github</span></span></code></pre></div><ol start="3"><li><strong>Forward</strong> (live; repo admin). One forwarder per repo. Blank <code>GITHUB_TOKEN</code>/<code>GH_TOKEN</code> or every delivery 401s:</li></ol><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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --install</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">GITHUB_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> GH_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">projec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><ol start="4"><li><strong>Cursor pull</strong> (same as production):</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">projec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo</span></span></code></pre></div><p>Volume, debounce, and <code>progress.commitStatus</code> / <code>progress.banner</code> live in <code>docs/guides/github.md</code>. Do not preinstall them.</p>`,22)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/skills_github.md.hgFX_oKY.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as t,o as a,ag as e}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"GitHub channels in the Agent SDK","description":"Build and test GitHub-driven Agent SDK agents: githubChannel hooks (auth turn vs host task), cursorAccount / --cursor-events, and local test tiers (fixtures, replay, forward). Use when wiring GitHub events or debugging delivery.","frontmatter":{"name":"agentsdk-github","description":"Build and test GitHub-driven Agent SDK agents: githubChannel hooks (auth turn vs host task), cursorAccount / --cursor-events, and local test tiers (fixtures, replay, forward). Use when wiring GitHub events or debugging delivery."},"headers":[],"relativePath":"../skills/github/SKILL.md","filePath":"../skills/github/SKILL.md"}'),n={name:"../skills/github/SKILL.md"};function h(l,s,k,p,o,d){return a(),t("div",null,[...s[0]||(s[0]=[e("",22)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/skills_hillclimb.md.B_zJerxA.js

@@ -1,7 +0,0 @@
-import{_ as t,c as s,o as i,ag as a}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK hillclimb","description":"Improve one existing Agent SDK agent: pin fixtures, measure, change one lever, remeasure, lock the win with an eval. Use when an agent already runs and needs better results.","frontmatter":{"name":"agentsdk-hillclimb","description":"Improve one existing Agent SDK agent: pin fixtures, measure, change one lever, remeasure, lock the win with an eval. Use when an agent already runs and needs better results."},"headers":[],"relativePath":"../skills/hillclimb/SKILL.md","filePath":"../skills/hillclimb/SKILL.md"}'),n={name:"../skills/hillclimb/SKILL.md"};function l(o,e,r,d,h,c){return i(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="agent-sdk-hillclimb" tabindex="-1">Agent SDK hillclimb <a class="header-anchor" href="#agent-sdk-hillclimb" aria-label="Permalink to &quot;Agent SDK hillclimb&quot;">​</a></h1><p>Measure → change one lever → remeasure. One failure mode per round.</p><p>Siblings: <code>skills/evals/SKILL.md</code>, <code>skills/github/SKILL.md</code>, <code>skills/debug/SKILL.md</code>.</p><h2 id="preconditions" tabindex="-1">Preconditions <a class="header-anchor" href="#preconditions" aria-label="Permalink to &quot;Preconditions&quot;">​</a></h2><p>From the user or the invoking message:</p><ol><li><strong>Target.</strong> Path or slug</li><li><strong>Fixtures.</strong> Fixed inputs</li><li><strong>Success.</strong> What better means this round</li><li><strong>Freeze line.</strong> What must not change</li></ol><p>Ask before editing if any are missing. A moving fixture is noise.</p><table tabindex="0"><thead><tr><th>Surface</th><th>Pin it</th></tr></thead><tbody><tr><td>GitHub</td><td><code>agent-sdk github replay &lt;pr&gt; --dir &lt;project&gt;</code> (<code>--dry-run --out fixtures/github</code>)</td></tr><tr><td>One tool</td><td><code>agent-sdk call &lt;tool&gt; --dir &lt;project&gt; --input &#39;{...}&#39;</code></td></tr><tr><td>Chat</td><td><code>agent-sdk run --dir &lt;project&gt; --message &quot;&lt;fixture&gt;&quot;</code></td></tr></tbody></table><h2 id="loop" tabindex="-1">Loop <a class="header-anchor" href="#loop" aria-label="Permalink to &quot;Loop&quot;">​</a></h2><ol><li><strong>Serve.</strong> <code>agent-sdk serve --dir &lt;project&gt; --mode single --dev</code> Playground: <code>http://127.0.0.1:3000/playground</code>.</li><li><strong>Hit it.</strong> Same path a user would. Record status, wall time, <code>sessionId</code>, output, and <code>action.result</code> counts by <code>toolName</code>.</li><li><strong>Name the failure.</strong> Score correctness, efficiency, harness fit. One dominant failure this round.</li><li><strong>Change one lever.</strong> Smallest first. Delete the code or prompt that caused it. Then instructions / skills, evidence shape, host prep (<code>workspaceFiles</code>, channel <code>callTool</code>) for wandering and latency (not formatting or judgment), remove or gate wandering tools, framework only if the agent cannot express the fix. Hypothesis: <em>If we X, metric Y should move because Z.</em></li><li><strong>Remeasure.</strong> Same fixtures. Keep only if the target metric improves and the freeze line holds.</li><li><strong>Lock.</strong> A kept change gets an eval that would have failed before it (<code>skills/evals/SKILL.md</code>). Never weaken a gate to pass a round.</li></ol><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### Hillclimb round N. </span><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">\`&lt;slug&gt;\`</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Fixture(s): …</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Hypothesis: …</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Change: …</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Before → after: tools …; wall …; quality …</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Verdict: keep | revert | narrow</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Next failure mode:</span></span></code></pre></div><p>Do not deploy or post real GitHub reviews unless asked.</p>`,12)])])}const k=t(n,[["render",l]]);export{g as __pageData,k as default};

package/dist/docs/assets/skills_hillclimb.md.B_zJerxA.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as i,ag as a}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Agent SDK hillclimb","description":"Improve one existing Agent SDK agent: pin fixtures, measure, change one lever, remeasure, lock the win with an eval. Use when an agent already runs and needs better results.","frontmatter":{"name":"agentsdk-hillclimb","description":"Improve one existing Agent SDK agent: pin fixtures, measure, change one lever, remeasure, lock the win with an eval. Use when an agent already runs and needs better results."},"headers":[],"relativePath":"../skills/hillclimb/SKILL.md","filePath":"../skills/hillclimb/SKILL.md"}'),n={name:"../skills/hillclimb/SKILL.md"};function l(o,e,r,d,h,c){return i(),s("div",null,[...e[0]||(e[0]=[a("",12)])])}const k=t(n,[["render",l]]);export{g as __pageData,k as default};

package/dist/docs/assets/skills_index.md.DL7EHaQ-.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as d,ag as l}from"./chunks/framework.BCISBCiQ.js";const m=JSON.parse('{"title":"Coding-agent skills","description":"Task guides that ship with the Agent SDK for scaffolding, deployment, evals, channels, and hillclimbing.","frontmatter":{"title":"Coding-agent skills","description":"Task guides that ship with the Agent SDK for scaffolding, deployment, evals, channels, and hillclimbing."},"headers":[],"relativePath":"skills/index.md","filePath":"skills/index.md"}'),i={name:"skills/index.md"};function n(r,t,s,o,h,c){return d(),a("div",null,[...t[0]||(t[0]=[l('<h1 id="coding-agent-skills" tabindex="-1">Coding-agent skills <a class="header-anchor" href="#coding-agent-skills" aria-label="Permalink to &quot;Coding-agent skills&quot;">​</a></h1><p>Each skill is a procedure a coding agent can follow. Installing <code>@cursor/july</code> copies them into <code>~/.cursor/skills/agentsdk/</code>. This site publishes the same files.</p><p>See <a href="./../building-with-agents.html">Building agents with agents</a> for when to use each one.</p><table tabindex="0"><thead><tr><th>Skill</th><th>Use it to</th></tr></thead><tbody><tr><td><a href="./framework-map.html">framework-map</a></td><td>Learn the project layout and runtimes</td></tr><tr><td><a href="./create-agent.html">create-agent</a></td><td>Scaffold and verify a new agent</td></tr><tr><td><a href="./evals.html">evals</a></td><td>Write fixtures and regression checks</td></tr><tr><td><a href="./otel.html">otel</a></td><td>Export OpenTelemetry traces</td></tr><tr><td><a href="./hillclimb.html">hillclimb</a></td><td>Improve an agent against fixed inputs</td></tr><tr><td><a href="./github.html">github</a></td><td>Add GitHub webhooks and replay events</td></tr><tr><td><a href="./setup-slack.html">setup-slack</a></td><td>Connect an agent to Slack</td></tr><tr><td><a href="./mcp-auth.html">mcp-auth</a></td><td>Authorize host MCP OAuth</td></tr><tr><td><a href="./deploy.html">deploy</a></td><td>Deploy with an attached service account</td></tr><tr><td><a href="./debug.html">debug</a></td><td>Diagnose a local run</td></tr></tbody></table>',4)])])}const p=e(i,[["render",n]]);export{m as __pageData,p as default};

package/dist/docs/assets/skills_index.md.DL7EHaQ-.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as d,ag as l}from"./chunks/framework.BCISBCiQ.js";const m=JSON.parse('{"title":"Coding-agent skills","description":"Task guides that ship with the Agent SDK for scaffolding, deployment, evals, channels, and hillclimbing.","frontmatter":{"title":"Coding-agent skills","description":"Task guides that ship with the Agent SDK for scaffolding, deployment, evals, channels, and hillclimbing."},"headers":[],"relativePath":"skills/index.md","filePath":"skills/index.md"}'),i={name:"skills/index.md"};function n(r,t,s,o,h,c){return d(),a("div",null,[...t[0]||(t[0]=[l("",4)])])}const p=e(i,[["render",n]]);export{m as __pageData,p as default};