@cursor/july 0.1.42 → 0.1.45

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

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

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

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

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

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