@cursor/july 0.1.111 → 0.1.112

package/dist/docs/assets/{reference_prompt.md.BQ5uAv1F.lean.js → reference_prompt.md.Ccp0R53H.lean.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors.","frontmatter":{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function p(r,s,l,o,h,d){return t(),i("div",null,[...s[0]||(s[0]=[a("",11)])])}const m=e(n,[["render",p]]);export{c as __pageData,m as default};
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors.","frontmatter":{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function p(r,s,l,o,h,d){return t(),i("div",null,[...s[0]||(s[0]=[a("",11)])])}const m=e(n,[["render",p]]);export{c as __pageData,m as default};

package/dist/docs/assets/{reference_schedules.md.BasfZWO-.js → reference_schedules.md.B2Nm6FaD.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.dypDpWZ3.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>Two ways an agent acts without an inbound message. A schedule is deploy-time cron: &quot;every weekday at 09:00, summarize open incidents.&quot; A reminder is a runtime wake bound to one conversation: &quot;re-check this PR&#39;s CI in two hours.&quot; Schedules live in the filesystem; reminders are created by running code.</p><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><p>Cron expressions are standard 5-field, evaluated in UTC with minute granularity.</p><h3 id="schedules-in-markdown" tabindex="-1">Schedules in Markdown <a class="header-anchor" href="#schedules-in-markdown" aria-label="Permalink to &quot;Schedules in Markdown&quot;">​</a></h3><p>A plain markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">---</span></span>
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>Two ways an agent acts without an inbound message. A schedule is deploy-time cron: &quot;every weekday at 09:00, summarize open incidents.&quot; A reminder is a runtime wake bound to one conversation: &quot;re-check this PR&#39;s CI in two hours.&quot; Schedules live in the filesystem; reminders are created by running code.</p><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><p>Cron expressions are standard 5-field, evaluated in UTC with minute granularity.</p><h3 id="schedules-in-markdown" tabindex="-1">Schedules in Markdown <a class="header-anchor" href="#schedules-in-markdown" aria-label="Permalink to &quot;Schedules in Markdown&quot;">​</a></h3><p>A plain markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">---</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cron: &quot;0 9 * * 1-5&quot;</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"></span>

package/dist/docs/assets/{reference_schedules.md.BasfZWO-.lean.js → reference_schedules.md.B2Nm6FaD.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.dypDpWZ3.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",38)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",38)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};

package/dist/docs/assets/{reference_sessions.md.YKvIsWAx.js → reference_sessions.md.1_6Vyv7x.js}

@@ -1 +1 @@
-import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(i,e,r,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o('<h1 id="sessions-events-and-streaming" tabindex="-1">Sessions, events, and streaming <a class="header-anchor" href="#sessions-events-and-streaming" aria-label="Permalink to &quot;Sessions, events, and streaming&quot;">​</a></h1><p>A session keeps one conversation, its workspace, and an append-only record of every message and tool call.</p><h2 id="what-does-a-session-contain" tabindex="-1">What does a session contain? <a class="header-anchor" href="#what-does-a-session-contain" aria-label="Permalink to &quot;What does a session contain?&quot;">​</a></h2><p>Each session combines:</p><ul><li>A channel and authenticated caller</li><li>A conversation the caller can continue</li><li>A workspace for local turns</li><li>An NDJSON event stream</li><li>Runtime state needed to resume after a server restart</li></ul><p>Sessions belong to the principal that created them. Follow-up, stream, and list routes return <code>403</code> when another caller tries to access one.</p><h2 id="which-session-identifier-should-i-use" tabindex="-1">Which session identifier should I use? <a class="header-anchor" href="#which-session-identifier-should-i-use" aria-label="Permalink to &quot;Which session identifier should I use?&quot;">​</a></h2><p>Sessions have two identifiers because conversation routing and inspection are different jobs.</p><table tabindex="0"><thead><tr><th>Identifier</th><th>Use it for</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Continue a conversation through its channel</td></tr><tr><td><code>sessionId</code></td><td>Stream events, inspect state, resolve approvals, or run a session-bound tool call</td></tr></tbody></table><p>Channels decide what a continuation token looks like. Slack uses its thread identity. A PR channel can use a key such as <code>pr:owner/repo#1</code>. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up. Reusing a stale HTTP token returns <code>409</code>.</p><p>Use the continuation token to keep talking. Use the session ID to observe or manage the stored session.</p><h2 id="which-session-modes-are-available" tabindex="-1">Which session modes are available? <a class="header-anchor" href="#which-session-modes-are-available" aria-label="Permalink to &quot;Which session modes are available?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Mode</th><th>Created by</th><th>What happens after a turn</th></tr></thead><tbody><tr><td><code>chat</code></td><td>HTTP sessions, channel <code>send</code>, Slack, or MCP <code>ask</code></td><td>Waits in <code>session.waiting</code> and accepts follow-ups</td></tr><tr><td><code>task</code></td><td>Markdown schedules and fire-and-forget dispatch</td><td>Ends in <code>session.completed</code> or <code>session.failed</code></td></tr></tbody></table><p>Task sessions don&#39;t accept follow-ups. Trying one returns <code>409</code>.</p><h2 id="what-happens-when-i-send-a-follow-up" tabindex="-1">What happens when I send a follow-up? <a class="header-anchor" href="#what-happens-when-i-send-a-follow-up" aria-label="Permalink to &quot;What happens when I send a follow-up?&quot;">​</a></h2><p>A follow-up to an idle chat session starts another turn. Admission when the session is already busy depends on the channel:</p><table tabindex="0"><thead><tr><th>Path</th><th>Busy-session policy</th></tr></thead><tbody><tr><td>HTTP playground / <code>POST /v1/session/:id</code> / MCP <code>ask</code></td><td><strong>Preempt</strong> (default): interrupt the in-flight turn, wait for it to settle, then run the new message</td></tr><tr><td>Slack mentions / DMs / alert-watch</td><td><strong>Coalesce</strong>: leave the active turn running, enqueue the follow-up, and drain queued asks into one follow-up turn when the active turn finishes (no mid-turn tool/hook inject)</td></tr></tbody></table><p>Pass <code>admission: &quot;coalesce&quot;</code> on <code>send()</code> to opt into the Slack policy from other callers. Omit it (or pass <code>&quot;preempt&quot;</code>) to keep interrupt semantics.</p><p><code>POST /v1/session/:id/stop</code> interrupts a turn without sending a new message. Interrupted turns record <code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code>. This means the turn was preempted. A whole-message Slack <code>stop</code> / <code>@agent stop</code> does the same for that thread and clears pending coalesced nudges.</p><p>Session-bound deterministic tool calls share the lock only for writes: a write-effect call returns <code>409 session_busy</code> while a model turn is running, a read-effect call runs alongside the turn (see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>).</p><h2 id="which-events-can-i-stream" tabindex="-1">Which events can I stream? <a class="header-anchor" href="#which-events-can-i-stream" aria-label="Permalink to &quot;Which events can I stream?&quot;">​</a></h2><p>Each NDJSON line uses this envelope: <code>{ type, index, sessionId, turnId?, at, data }</code>. The <code>index</code> increases within one session. The <code>at</code> field is an ISO-8601 timestamp.</p><table tabindex="0"><thead><tr><th>Phase</th><th>Events</th><th>What they tell you</th></tr></thead><tbody><tr><td>Session</td><td><code>session.started</code>, <code>session.waiting</code>, <code>session.completed</code>, <code>session.failed</code></td><td>Session creation, readiness, and task completion</td></tr><tr><td>Agent</td><td><code>agent.bound</code></td><td>Cloud conversation URL</td></tr><tr><td>Input</td><td><code>message.received</code></td><td>A user message was accepted</td></tr><tr><td>Turn</td><td><code>turn.queued</code>, <code>turn.started</code>, <code>turn.completed</code>, <code>turn.failed</code></td><td>Queue position under a <a href="./agent-config.html#concurrency"><code>maxRunningTurns</code> cap</a>, then turn status, final result, and token usage</td></tr><tr><td>Steps</td><td><code>step.started</code>, <code>step.completed</code></td><td>Model step boundaries and duration</td></tr><tr><td>Reasoning</td><td><code>reasoning.appended</code>, <code>reasoning.completed</code></td><td>Streamed reasoning blocks</td></tr><tr><td>Reply</td><td><code>message.appended</code>, <code>message.completed</code></td><td>Text deltas and finalized assistant messages</td></tr><tr><td>Tools</td><td><code>actions.requested</code>, <code>action.result</code></td><td>Tool names, validated arguments, outputs, and errors</td></tr><tr><td>Approvals</td><td><code>action.approval_requested</code>, <code>action.approval_resolved</code></td><td>A parked tool call and the human decision</td></tr><tr><td>Subagents</td><td><code>subagent.called</code>, <code>subagent.completed</code></td><td>Delegated work</td></tr><tr><td>Artifacts</td><td><code>artifact.tagged</code></td><td>A durable <a href="./artifacts.html">artifact</a> was tagged for this session, by host code or <code>tag_artifact</code></td></tr></tbody></table><p>Pair <code>actions.requested</code> with <code>action.result</code> to reconstruct the tool trajectory. Read <code>turn.completed.data.usage</code> for input, output, and cache token counts. When <code>agent/result.ts</code> is authored, a thrown <code>commit</code>, a <code>ctx.reject</code> that exhausts the two-repair budget, or empty assistant text emits <code>turn.failed</code> instead of <code>turn.completed</code>. <code>ctx.reject(message)</code> re-runs the same turn with that message so the model can revise while tools and the session filesystem are still up.</p><h2 id="how-do-i-stream-or-replay-session-events" tabindex="-1">How do I stream or replay session events? <a class="header-anchor" href="#how-do-i-stream-or-replay-session-events" aria-label="Permalink to &quot;How do I stream or replay session events?&quot;">​</a></h2><p>One endpoint handles both live streaming and replay:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>Pass <code>startIndex</code> to continue after the last event you received. Omit it or pass <code>0</code> to replay the full session before following new events. <code>GET /v1/session/:id/events</code> returns a one-time dump without staying connected.</p><p>Event streams replay from disk after a server restart. Conversation state resumes from the Cursor SDK store.</p><h2 id="what-goes-into-a-local-session-workspace" tabindex="-1">What goes into a local session workspace? <a class="header-anchor" href="#what-goes-into-a-local-session-workspace" aria-label="Permalink to &quot;What goes into a local session workspace?&quot;">​</a></h2><p>The Agent SDK creates a workspace before the first local turn:</p><table tabindex="0"><thead><tr><th>Source path</th><th>Lands as</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code></td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/&lt;name&gt;/SKILL.md</code></td></tr><tr><td>agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace, with a catalog in <code>AGENTS.md</code></td></tr><tr><td><code>sandbox/workspace/**</code></td><td>copied in as seed files</td></tr><tr><td>per-send <code>workspaceFiles</code></td><td>written before the turn</td></tr></tbody></table><p>The local harness uses this workspace as its working directory. Parent directories can contribute <code>AGENTS.md</code> and <code>.cursor</code> settings. Set <code>local.cwd</code> when you need a clean parent directory. A channel can also provide a different working directory for one session, such as a PR worktree.</p><p>See <a href="./agent-config.html#local-cwd">Agent config: local cwd</a> for the inheritance rules.</p><h2 id="where-does-the-agent-sdk-store-session-data" tabindex="-1">Where does the Agent SDK store session data? <a class="header-anchor" href="#where-does-the-agent-sdk-store-session-data" aria-label="Permalink to &quot;Where does the Agent SDK store session data?&quot;">​</a></h2><p>Local state lives under <code>--state-root</code>. Slugged mounts store it under a subdirectory named for the slug.</p><p>Deleting a session directory removes the session from the server: it disappears from listings and can no longer be streamed or continued. Cloud conversations remain on the Cursor backend.</p><p>Nested git checkouts already default <code>local.cwd</code> outside the enclosing repo. See <a href="#what-goes-into-a-local-session-workspace">What goes into a local session workspace?</a>.</p><h2 id="how-do-i-inspect-a-saved-event-stream" tabindex="-1">How do I inspect a saved event stream? <a class="header-anchor" href="#how-do-i-inspect-a-saved-event-stream" aria-label="Permalink to &quot;How do I inspect a saved event stream?&quot;">​</a></h2><p>Use <code>trajectory</code> with a saved trace:</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">state-roo</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:#032F62;--shiki-dark:#9ECBFF;">/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span></code></pre></div><p>The command prints tool calls, the reply, and token usage in the same JSON shape as <code>run</code>. Use <strong>Open trace</strong> in the playground for a visual view.</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="./http-api.html">HTTP API</a></li><li><a href="./hooks.html">Hooks</a></li></ul>',44)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};
+import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(i,e,r,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o('<h1 id="sessions-events-and-streaming" tabindex="-1">Sessions, events, and streaming <a class="header-anchor" href="#sessions-events-and-streaming" aria-label="Permalink to &quot;Sessions, events, and streaming&quot;">​</a></h1><p>A session keeps one conversation, its workspace, and an append-only record of every message and tool call.</p><h2 id="what-does-a-session-contain" tabindex="-1">What does a session contain? <a class="header-anchor" href="#what-does-a-session-contain" aria-label="Permalink to &quot;What does a session contain?&quot;">​</a></h2><p>Each session combines:</p><ul><li>A channel and authenticated caller</li><li>A conversation the caller can continue</li><li>A workspace for local turns</li><li>An NDJSON event stream</li><li>Runtime state needed to resume after a server restart</li></ul><p>Sessions belong to the principal that created them. Follow-up, stream, and list routes return <code>403</code> when another caller tries to access one.</p><h2 id="which-session-identifier-should-i-use" tabindex="-1">Which session identifier should I use? <a class="header-anchor" href="#which-session-identifier-should-i-use" aria-label="Permalink to &quot;Which session identifier should I use?&quot;">​</a></h2><p>Sessions have two identifiers because conversation routing and inspection are different jobs.</p><table tabindex="0"><thead><tr><th>Identifier</th><th>Use it for</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Continue a conversation through its channel</td></tr><tr><td><code>sessionId</code></td><td>Stream events, inspect state, resolve approvals, or run a session-bound tool call</td></tr></tbody></table><p>Channels decide what a continuation token looks like. Slack uses its thread identity. A PR channel can use a key such as <code>pr:owner/repo#1</code>. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up. Reusing a stale HTTP token returns <code>409</code>.</p><p>Use the continuation token to keep talking. Use the session ID to observe or manage the stored session.</p><h2 id="which-session-modes-are-available" tabindex="-1">Which session modes are available? <a class="header-anchor" href="#which-session-modes-are-available" aria-label="Permalink to &quot;Which session modes are available?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Mode</th><th>Created by</th><th>What happens after a turn</th></tr></thead><tbody><tr><td><code>chat</code></td><td>HTTP sessions, channel <code>send</code>, Slack, or MCP <code>ask</code></td><td>Waits in <code>session.waiting</code> and accepts follow-ups</td></tr><tr><td><code>task</code></td><td>Markdown schedules and fire-and-forget dispatch</td><td>Ends in <code>session.completed</code> or <code>session.failed</code></td></tr></tbody></table><p>Task sessions don&#39;t accept follow-ups. Trying one returns <code>409</code>.</p><h2 id="what-happens-when-i-send-a-follow-up" tabindex="-1">What happens when I send a follow-up? <a class="header-anchor" href="#what-happens-when-i-send-a-follow-up" aria-label="Permalink to &quot;What happens when I send a follow-up?&quot;">​</a></h2><p>A follow-up to an idle chat session starts another turn. Admission when the session is already busy depends on the channel:</p><table tabindex="0"><thead><tr><th>Path</th><th>Busy-session policy</th></tr></thead><tbody><tr><td>HTTP playground / <code>POST /v1/session/:id</code> / MCP <code>ask</code></td><td><strong>Preempt</strong> (default): interrupt the in-flight turn, wait for it to settle, then run the new message</td></tr><tr><td>Slack mentions / DMs / alert-watch</td><td><strong>Coalesce</strong>: leave the active turn running, enqueue the follow-up, and drain queued asks into one follow-up turn when the active turn finishes (no mid-turn tool/hook inject)</td></tr></tbody></table><p>Pass <code>admission: &quot;coalesce&quot;</code> on <code>send()</code> to opt into the Slack policy from other callers. Omit it (or pass <code>&quot;preempt&quot;</code>) to keep interrupt semantics.</p><p><code>POST /v1/session/:id/stop</code> interrupts a turn without sending a new message. Interrupted turns record <code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code>. This means the turn was preempted. A whole-message Slack <code>stop</code> / <code>@agent stop</code> does the same for that thread and clears pending coalesced nudges.</p><p>Session-bound deterministic tool calls share the lock only for writes: a write-effect call returns <code>409 session_busy</code> while a model turn is running, a read-effect call runs alongside the turn (see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>).</p><h2 id="which-events-can-i-stream" tabindex="-1">Which events can I stream? <a class="header-anchor" href="#which-events-can-i-stream" aria-label="Permalink to &quot;Which events can I stream?&quot;">​</a></h2><p>Each NDJSON line uses this envelope: <code>{ type, index, sessionId, turnId?, at, data }</code>. The <code>index</code> increases within one session. The <code>at</code> field is an ISO-8601 timestamp.</p><table tabindex="0"><thead><tr><th>Phase</th><th>Events</th><th>What they tell you</th></tr></thead><tbody><tr><td>Session</td><td><code>session.started</code>, <code>session.waiting</code>, <code>session.completed</code>, <code>session.failed</code></td><td>Session creation, readiness, and task completion</td></tr><tr><td>Agent</td><td><code>agent.bound</code></td><td>Cloud conversation URL</td></tr><tr><td>Input</td><td><code>message.received</code></td><td>A user message was accepted</td></tr><tr><td>Turn</td><td><code>turn.queued</code>, <code>turn.started</code>, <code>turn.completed</code>, <code>turn.failed</code></td><td>Queue position under a <a href="./agent-config.html#concurrency"><code>maxRunningTurns</code> cap</a>, then turn status, final result, and token usage</td></tr><tr><td>Steps</td><td><code>step.started</code>, <code>step.completed</code></td><td>Model step boundaries and duration</td></tr><tr><td>Reasoning</td><td><code>reasoning.appended</code>, <code>reasoning.completed</code></td><td>Streamed reasoning blocks</td></tr><tr><td>Reply</td><td><code>message.appended</code>, <code>message.completed</code></td><td>Text deltas and finalized assistant messages</td></tr><tr><td>Tools</td><td><code>actions.requested</code>, <code>action.result</code></td><td>Tool names, validated arguments, outputs, and errors</td></tr><tr><td>Approvals</td><td><code>action.approval_requested</code>, <code>action.approval_resolved</code></td><td>A parked tool call and the human decision</td></tr><tr><td>Subagents</td><td><code>subagent.called</code>, <code>subagent.completed</code></td><td>Delegated work</td></tr><tr><td>Artifacts</td><td><code>artifact.tagged</code></td><td>A durable <a href="./artifacts.html">artifact</a> was tagged for this session, by host code or <code>tag_artifact</code></td></tr></tbody></table><p>Pair <code>actions.requested</code> with <code>action.result</code> to reconstruct the tool trajectory. Read <code>turn.completed.data.usage</code> for input, output, and cache token counts. When <code>agent/result.ts</code> is authored, a thrown <code>commit</code>, a <code>ctx.reject</code> that exhausts the two-repair budget, or empty assistant text emits <code>turn.failed</code> instead of <code>turn.completed</code>. <code>ctx.reject(message)</code> re-runs the same turn with that message so the model can revise while tools and the session filesystem are still up.</p><h2 id="how-do-i-stream-or-replay-session-events" tabindex="-1">How do I stream or replay session events? <a class="header-anchor" href="#how-do-i-stream-or-replay-session-events" aria-label="Permalink to &quot;How do I stream or replay session events?&quot;">​</a></h2><p>One endpoint handles both live streaming and replay:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>Pass <code>startIndex</code> to continue after the last event you received. Omit it or pass <code>0</code> to replay the full session before following new events. <code>GET /v1/session/:id/events</code> returns a one-time dump without staying connected.</p><p>Event streams replay from disk after a server restart. Conversation state resumes from the Cursor SDK store.</p><h2 id="what-goes-into-a-local-session-workspace" tabindex="-1">What goes into a local session workspace? <a class="header-anchor" href="#what-goes-into-a-local-session-workspace" aria-label="Permalink to &quot;What goes into a local session workspace?&quot;">​</a></h2><p>The Agent SDK creates a workspace before the first local turn:</p><table tabindex="0"><thead><tr><th>Source path</th><th>Lands as</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code></td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/&lt;name&gt;/SKILL.md</code></td></tr><tr><td>agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace, with a catalog in <code>AGENTS.md</code></td></tr><tr><td><code>sandbox/workspace/**</code></td><td>copied in as seed files</td></tr><tr><td>per-send <code>workspaceFiles</code></td><td>written before the turn</td></tr></tbody></table><p>The local harness uses this workspace as its working directory. Parent directories can contribute <code>AGENTS.md</code> and <code>.cursor</code> settings. Set <code>local.cwd</code> when you need a clean parent directory. A channel can also provide a different working directory for one session, such as a PR worktree.</p><p>See <a href="./agent-config.html#local-cwd">Agent config: local cwd</a> for the inheritance rules.</p><h2 id="where-does-the-agent-sdk-store-session-data" tabindex="-1">Where does the Agent SDK store session data? <a class="header-anchor" href="#where-does-the-agent-sdk-store-session-data" aria-label="Permalink to &quot;Where does the Agent SDK store session data?&quot;">​</a></h2><p>Local state lives under <code>--state-root</code>. Slugged mounts store it under a subdirectory named for the slug.</p><p>Deleting a session directory removes the session from the server: it disappears from listings and can no longer be streamed or continued. Cloud conversations remain on the Cursor backend.</p><p>Nested git checkouts already default <code>local.cwd</code> outside the enclosing repo. See <a href="#what-goes-into-a-local-session-workspace">What goes into a local session workspace?</a>.</p><h2 id="how-do-i-inspect-a-saved-event-stream" tabindex="-1">How do I inspect a saved event stream? <a class="header-anchor" href="#how-do-i-inspect-a-saved-event-stream" aria-label="Permalink to &quot;How do I inspect a saved event stream?&quot;">​</a></h2><p>Use <code>trajectory</code> with a saved trace:</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">state-roo</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:#032F62;--shiki-dark:#9ECBFF;">/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span></code></pre></div><p>The command prints tool calls, the reply, and token usage in the same JSON shape as <code>run</code>. Use <strong>Open trace</strong> in the playground for a visual view.</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="./http-api.html">HTTP API</a></li><li><a href="./hooks.html">Hooks</a></li></ul>',44)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};

package/dist/docs/assets/{reference_sessions.md.YKvIsWAx.lean.js → reference_sessions.md.1_6Vyv7x.lean.js}

@@ -1 +1 @@
-import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(i,e,r,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",44)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};
+import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(i,e,r,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",44)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};

package/dist/docs/assets/{reference_skills.md.rNgpsGd0.js → reference_skills.md.DjQkRefx.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(o,s,h,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to &quot;Skills&quot;">​</a></h1><p>A skill is an on-demand procedure following the <code>SKILL.md</code> convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Three forms cover every case.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>agent/skills/&lt;name&gt;.md</code></td><td>Flat markdown. Optional <code>description</code> frontmatter; the first body line is the fallback.</td></tr><tr><td><code>agent/skills/&lt;name&gt;/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files (<code>references/…</code>). Requires <code>description</code> frontmatter.</td></tr><tr><td><code>agent/skills/&lt;name&gt;.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@cursor/july/skills</code>.</td></tr></tbody></table><p>Flat markdown:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">---</span></span>
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(o,s,h,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to &quot;Skills&quot;">​</a></h1><p>A skill is an on-demand procedure following the <code>SKILL.md</code> convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Three forms cover every case.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>agent/skills/&lt;name&gt;.md</code></td><td>Flat markdown. Optional <code>description</code> frontmatter; the first body line is the fallback.</td></tr><tr><td><code>agent/skills/&lt;name&gt;/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files (<code>references/…</code>). Requires <code>description</code> frontmatter.</td></tr><tr><td><code>agent/skills/&lt;name&gt;.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@cursor/july/skills</code>.</td></tr></tbody></table><p>Flat markdown:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</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;">---</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">description: Use when a pull request needs a structured approval checklist.</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"></span>

package/dist/docs/assets/{reference_skills.md.rNgpsGd0.lean.js → reference_skills.md.DjQkRefx.lean.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(o,s,h,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a("",19)])])}const u=e(n,[["render",l]]);export{c as __pageData,u as default};
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(o,s,h,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a("",19)])])}const u=e(n,[["render",l]]);export{c as __pageData,u as default};

package/dist/docs/assets/{reference_subagents.md.e5qitjJt.js → reference_subagents.md.BHsSMMyO.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(r,e,l,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one is its own directory under <code>agent/subagents/&lt;id&gt;/</code>, with the same <code>agent.ts</code> + <code>instructions.md</code> shape as the root. On the Cursor harness, subagents run as SDK custom subagents: the parent model delegates through the harness <code>task</code> tool, and the stream records <code>subagent.called</code> and <code>subagent.completed</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/subagents/researcher/</span></span>
+import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(r,e,l,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one is its own directory under <code>agent/subagents/&lt;id&gt;/</code>, with the same <code>agent.ts</code> + <code>instructions.md</code> shape as the root. On the Cursor harness, subagents run as SDK custom subagents: the parent model delegates through the harness <code>task</code> tool, and the stream records <code>subagent.called</code> and <code>subagent.completed</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/subagents/researcher/</span></span>
 <span class="line"><span>├── agent.ts            # description (required), model (optional)</span></span>
 <span class="line"><span>└── instructions.md     # the subagent&#39;s own system prompt</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:#6A737D;--shiki-dark:#6A737D;">// agent/subagents/researcher/agent.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>

package/dist/docs/assets/{reference_subagents.md.e5qitjJt.lean.js → reference_subagents.md.BHsSMMyO.lean.js}

@@ -1 +1 @@
-import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(r,e,l,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[n("",16)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};
+import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(r,e,l,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[n("",16)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_tools.md.BdCO2aHZ.js → reference_tools.md.BYzUTeVA.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="tools" tabindex="-1">Tools <a class="header-anchor" href="#tools" aria-label="Permalink to &quot;Tools&quot;">​</a></h1><p>A tool is a typed action the model can call: hit an API, run a query, write a file. Each file in <code>agent/tools/</code> defines one tool, and the filename becomes the tool name the model sees. Tools come in two execution flavors: server tools run in-process on the serve host, and agent tools run as scripts where the agent runs. Every server tool can also be called directly, with no model turn.</p><h2 id="define-a-server-tool" tabindex="-1">Define a server tool <a class="header-anchor" href="#define-a-server-tool" aria-label="Permalink to &quot;Define a server tool&quot;">​</a></h2><p>By default, <code>execute</code> runs in-process on the serving host with full access to <code>process.env</code> and your <code>agent/lib/</code> code. Local turns call server tools as SDK custom tools. Cloud turns reach them over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set; without either, the server warns at startup and cloud turns omit them.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/tools/inspect_pr.ts</span></span>
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="tools" tabindex="-1">Tools <a class="header-anchor" href="#tools" aria-label="Permalink to &quot;Tools&quot;">​</a></h1><p>A tool is a typed action the model can call: hit an API, run a query, write a file. Each file in <code>agent/tools/</code> defines one tool, and the filename becomes the tool name the model sees. Tools come in two execution flavors: server tools run in-process on the serve host, and agent tools run as scripts where the agent runs. Every server tool can also be called directly, with no model turn.</p><h2 id="define-a-server-tool" tabindex="-1">Define a server tool <a class="header-anchor" href="#define-a-server-tool" aria-label="Permalink to &quot;Define a server tool&quot;">​</a></h2><p>By default, <code>execute</code> runs in-process on the serving host with full access to <code>process.env</code> and your <code>agent/lib/</code> code. Local turns call server tools as SDK custom tools. Cloud turns reach them over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set; without either, the server warns at startup and cloud turns omit them.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/tools/inspect_pr.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>

package/dist/docs/assets/{reference_tools.md.BdCO2aHZ.lean.js → reference_tools.md.BYzUTeVA.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",57)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{templates_agentic-owners.md.Da_AGDlH.js → templates_agentic-owners.md.9M575F5C.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function l(h,s,p,r,o,d){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="review-pull-requests-with-owners-policies" tabindex="-1">Review pull requests with owners policies <a class="header-anchor" href="#review-pull-requests-with-owners-policies" aria-label="Permalink to &quot;Review pull requests with owners policies&quot;">​</a></h1><p>This agent reviews every pull request in your repository. It risk-tiers the diff, requests the owning team or user as reviewers, and approves what your policy allows. Ownership rules live in <code>.agentic-owners/policy.yml</code> files committed at any depth of the repo; the closest policy to a changed file wins, and policies are always read from the PR&#39;s base ref so a PR cannot exempt itself.</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;">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;"> ./owners-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agentic-owners</span></span></code></pre></div><p><code>init</code> writes the project, installs dependencies, and puts <code>agent-sdk</code> on PATH.</p><h2 id="log-in-and-run" tabindex="-1">Log in and run <a class="header-anchor" href="#log-in-and-run" aria-label="Permalink to &quot;Log in and run&quot;">​</a></h2><p>Set your repositories in <code>agent/lib/config.ts</code> (<code>repos: [&quot;you/your-repo&quot;]</code>), then:</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;"> owners-agent</span></span>
+import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function l(h,s,p,r,o,d){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="review-pull-requests-with-owners-policies" tabindex="-1">Review pull requests with owners policies <a class="header-anchor" href="#review-pull-requests-with-owners-policies" aria-label="Permalink to &quot;Review pull requests with owners policies&quot;">​</a></h1><p>This agent reviews every pull request in your repository. It risk-tiers the diff, requests the owning team or user as reviewers, and approves what your policy allows. Ownership rules live in <code>.agentic-owners/policy.yml</code> files committed at any depth of the repo; the closest policy to a changed file wins, and policies are always read from the PR&#39;s base ref so a PR cannot exempt itself.</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;">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;"> ./owners-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agentic-owners</span></span></code></pre></div><p><code>init</code> writes the project, installs dependencies, and puts <code>agent-sdk</code> on PATH.</p><h2 id="log-in-and-run" tabindex="-1">Log in and run <a class="header-anchor" href="#log-in-and-run" aria-label="Permalink to &quot;Log in and run&quot;">​</a></h2><p>Set your repositories in <code>agent/lib/config.ts</code> (<code>repos: [&quot;you/your-repo&quot;]</code>), then:</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;"> owners-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;"> login</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>PR events stream through your Cursor account. No webhook or GitHub App setup. Open a PR, or replay a real one deterministically (this also works with <code>repos</code> empty):</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/you/your-repo/pull/123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>Deploy with <code>agent-sdk deploy</code>.</p><h2 id="policies" tabindex="-1">Policies <a class="header-anchor" href="#policies" aria-label="Permalink to &quot;Policies&quot;">​</a></h2><p>With no policy files, every PR gets a default risk review: very-low and low risk approve, medium and above hold with a comment. Route reviews by committing policies:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># .agentic-owners/policy.yml. Anywhere in the repo; closest wins.</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># paths are repo-root-relative globs, wherever the policy file lives.</span></span>

package/dist/docs/assets/{templates_agentic-owners.md.Da_AGDlH.lean.js → templates_agentic-owners.md.9M575F5C.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function l(h,s,p,r,o,d){return a(),e("div",null,[...s[0]||(s[0]=[t("",24)])])}const g=i(n,[["render",l]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function l(h,s,p,r,o,d){return a(),e("div",null,[...s[0]||(s[0]=[t("",24)])])}const g=i(n,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/{templates_pr-autofixer.md.DqxocIGh.js → templates_pr-autofixer.md.ws0DDXDy.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as s,o as t,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR.","frontmatter":{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR."},"headers":[],"relativePath":"templates/pr-autofixer.md","filePath":"templates/pr-autofixer.md"}'),n={name:"templates/pr-autofixer.md"};function o(r,e,l,h,d,p){return t(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="fix-pull-requests-on-a-cursor-cloud-vm" tabindex="-1">Fix pull requests on a Cursor cloud VM <a class="header-anchor" href="#fix-pull-requests-on-a-cursor-cloud-vm" aria-label="Permalink to &quot;Fix pull requests on a Cursor cloud VM&quot;">​</a></h1><p>This agent coordinates from chat and Slack, then hands each opted-in pull request to a Cursor cloud VM with a real checkout. The same cloud conversation resumes when you drive the PR again, GitHub reports a change on that PR, or a merge-conflict reminder fires.</p><p>Chat never has the target checkout. <code>gh</code> and <code>git</code> run on the VM. Opening a pull request does not start a session. Drive a PR from the playground, Slack, or HTTP to opt in. After that, the agent auto-fixes: it pushes verified fixes to the PR head and performs workflow actions. It never merges, enables auto-merge, or force-pushes.</p><h2 id="scaffold" tabindex="-1">Scaffold <a class="header-anchor" href="#scaffold" aria-label="Permalink to &quot;Scaffold&quot;">​</a></h2><p>On a TTY, <code>init</code> asks which GitHub repos to watch. Scripts pass the same answer with <code>--var</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;">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;"> ./pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-autofixer</span></span>
+import{_ as a,c as s,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR.","frontmatter":{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR."},"headers":[],"relativePath":"templates/pr-autofixer.md","filePath":"templates/pr-autofixer.md"}'),n={name:"templates/pr-autofixer.md"};function o(r,e,l,h,d,p){return t(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="fix-pull-requests-on-a-cursor-cloud-vm" tabindex="-1">Fix pull requests on a Cursor cloud VM <a class="header-anchor" href="#fix-pull-requests-on-a-cursor-cloud-vm" aria-label="Permalink to &quot;Fix pull requests on a Cursor cloud VM&quot;">​</a></h1><p>This agent coordinates from chat and Slack, then hands each opted-in pull request to a Cursor cloud VM with a real checkout. The same cloud conversation resumes when you drive the PR again, GitHub reports a change on that PR, or a merge-conflict reminder fires.</p><p>Chat never has the target checkout. <code>gh</code> and <code>git</code> run on the VM. Opening a pull request does not start a session. Drive a PR from the playground, Slack, or HTTP to opt in. After that, the agent auto-fixes: it pushes verified fixes to the PR head and performs workflow actions. It never merges, enables auto-merge, or force-pushes.</p><h2 id="scaffold" tabindex="-1">Scaffold <a class="header-anchor" href="#scaffold" aria-label="Permalink to &quot;Scaffold&quot;">​</a></h2><p>On a TTY, <code>init</code> asks which GitHub repos to watch. Scripts pass the same answer with <code>--var</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;">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;"> ./pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-autofixer</span></span>
 <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;"> ./pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-autofixer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --var</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repos=acme/widgets,acme/api</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p><code>init</code> writes the project, installs dependencies, and puts <code>agent-sdk</code> on PATH. You can still edit <code>agent/lib/repos.ts</code> later, or override the list with <code>PR_AUTOFIXER_REPOS</code>.</p><h2 id="log-in" tabindex="-1">Log in <a class="header-anchor" href="#log-in" aria-label="Permalink to &quot;Log in&quot;">​</a></h2><p>Model turns and cloud agents use your Cursor account.</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;"> pr-autofixer</span></span>
 <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></code></pre></div><p>The command opens a browser if you have no stored credential. Cloud turns spend cloud-agent budget under that account.</p><h2 id="point-it-at-a-repo" tabindex="-1">Point it at a repo <a class="header-anchor" href="#point-it-at-a-repo" aria-label="Permalink to &quot;Point it at a repo&quot;">​</a></h2><p><code>init</code> writes the repo list into <code>agent/lib/repos.ts</code>. One owner. Up to 20 repos. The GitHub channel requests <code>contents-write</code> so the agent can push to the PR head.</p><h2 id="first-drive" tabindex="-1">First drive <a class="header-anchor" href="#first-drive" aria-label="Permalink to &quot;First drive&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;"> dev</span></span></code></pre></div><p>Open the playground. Paste a PR URL or <code>owner/repo#N</code>. The local agent calls <code>drive_pr</code>, which attaches the PR to a cloud session and returns when that session exists. Autofix continues in the background. <code>bcId</code> / <code>agentUrl</code> are included when already bound.</p><p>You can also POST:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/pr-autofixer/v1/channels/drive</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

package/dist/docs/assets/{templates_pr-autofixer.md.DqxocIGh.lean.js → templates_pr-autofixer.md.ws0DDXDy.lean.js}

@@ -1 +1 @@
-import{_ as a,c as s,o as t,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR.","frontmatter":{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR."},"headers":[],"relativePath":"templates/pr-autofixer.md","filePath":"templates/pr-autofixer.md"}'),n={name:"templates/pr-autofixer.md"};function o(r,e,l,h,d,p){return t(),s("div",null,[...e[0]||(e[0]=[i("",34)])])}const k=a(n,[["render",o]]);export{u as __pageData,k as default};
+import{_ as a,c as s,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR.","frontmatter":{"title":"Fix pull requests on a Cursor cloud VM","description":"Scaffold the agent, point it at your repos, and opt in to auto-fix a PR."},"headers":[],"relativePath":"templates/pr-autofixer.md","filePath":"templates/pr-autofixer.md"}'),n={name:"templates/pr-autofixer.md"};function o(r,e,l,h,d,p){return t(),s("div",null,[...e[0]||(e[0]=[i("",34)])])}const k=a(n,[["render",o]]);export{u as __pageData,k as default};

package/dist/docs/assets/{templates_security-reviewer.md.Bhnvd8VE.js → templates_security-reviewer.md.KEFYXzfK.js}

@@ -1,2 +1,2 @@
-import{_ as s,c as a,o as t,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy.","frontmatter":{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy."},"headers":[],"relativePath":"templates/security-reviewer.md","filePath":"templates/security-reviewer.md"}'),o={name:"templates/security-reviewer.md"};function n(l,e,r,h,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="review-pull-requests-for-exploitable-bugs" tabindex="-1">Review pull requests for exploitable bugs <a class="header-anchor" href="#review-pull-requests-for-exploitable-bugs" aria-label="Permalink to &quot;Review pull requests for exploitable bugs&quot;">​</a></h1><p>This agent reads a pull request diff and posts one review comment. It reports exploitable bugs: injection, authz bypass, secret leaks, SSRF, RCE. Style nits stay out.</p><p>This template is one model turn: read the diff, then post one comment.</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;">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;"> ./security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> security-reviewer</span></span></code></pre></div><p><code>init</code> asks which GitHub repos to watch. Every repo must share one owner. Pass <code>--var repos=acme/api,acme/web</code> to skip the prompt.</p><p>The list lands in <code>agent/lib/repos.ts</code>. The GitHub channel reads it for <code>cursorAccount</code> and for the wake filter. Edit that file when the set changes.</p><h2 id="connect-github-through-cursor" tabindex="-1">Connect GitHub through Cursor <a class="header-anchor" href="#connect-github-through-cursor" aria-label="Permalink to &quot;Connect GitHub through Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for those repositories (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). Sign the host in:</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;"> security-reviewer</span></span>
+import{_ as s,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy.","frontmatter":{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy."},"headers":[],"relativePath":"templates/security-reviewer.md","filePath":"templates/security-reviewer.md"}'),o={name:"templates/security-reviewer.md"};function n(l,e,r,h,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="review-pull-requests-for-exploitable-bugs" tabindex="-1">Review pull requests for exploitable bugs <a class="header-anchor" href="#review-pull-requests-for-exploitable-bugs" aria-label="Permalink to &quot;Review pull requests for exploitable bugs&quot;">​</a></h1><p>This agent reads a pull request diff and posts one review comment. It reports exploitable bugs: injection, authz bypass, secret leaks, SSRF, RCE. Style nits stay out.</p><p>This template is one model turn: read the diff, then post one comment.</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;">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;"> ./security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> security-reviewer</span></span></code></pre></div><p><code>init</code> asks which GitHub repos to watch. Every repo must share one owner. Pass <code>--var repos=acme/api,acme/web</code> to skip the prompt.</p><p>The list lands in <code>agent/lib/repos.ts</code>. The GitHub channel reads it for <code>cursorAccount</code> and for the wake filter. Edit that file when the set changes.</p><h2 id="connect-github-through-cursor" tabindex="-1">Connect GitHub through Cursor <a class="header-anchor" href="#connect-github-through-cursor" aria-label="Permalink to &quot;Connect GitHub through Cursor&quot;">​</a></h2><p>Connect GitHub in Cursor for those repositories (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>). Sign the host in:</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;"> security-reviewer</span></span>
 <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></code></pre></div><p><code>cursorAccount</code> pulls SCM events from Cursor and mints a short-lived, repo-scoped credential. <code>ctx.host.github</code> and child <code>gh</code> commands share it. See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="first-review" tabindex="-1">First review <a class="header-anchor" href="#first-review" aria-label="Permalink to &quot;First review&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;"> dev</span></span></code></pre></div><p><code>dev</code> starts the Cursor event relay for the watched repos. To drive a known PR without waiting on a live push:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/api/pull/12</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>replay</code> needs pull access. Draft PRs and repos outside <code>agent/lib/repos.ts</code> are ignored. The channel writes <code>pr/diff.patch</code> after the wake is acknowledged, then starts a model turn. The model calls <code>post_findings</code> once.</p><p>Chat replies stay in the playground. <code>post_findings</code> writes the GitHub comment.</p><h2 id="what-to-edit" tabindex="-1">What to edit <a class="header-anchor" href="#what-to-edit" aria-label="Permalink to &quot;What to edit&quot;">​</a></h2><ul><li><code>agent/lib/repos.ts</code>: watched repos</li><li><code>agent/instructions.md</code>: what counts as a finding and the comment shape</li><li><code>evals/review.eval.ts</code>: smoke cases</li></ul><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><p>Two smoke cases: one XSS fixture and one docs-only change.</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></code></pre></div><p>Eval sessions skip the GitHub write.</p><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy&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;"> deploy</span></span></code></pre></div><p>Run it from the agent&#39;s git checkout. The command infers repository, ref, path, and slug. The deployment uses the team&#39;s Cursor GitHub connection for the same watched repos.</p>`,26)])])}const k=s(o,[["render",n]]);export{u as __pageData,k as default};

package/dist/docs/assets/{templates_security-reviewer.md.Bhnvd8VE.lean.js → templates_security-reviewer.md.KEFYXzfK.lean.js}

@@ -1 +1 @@
-import{_ as s,c as a,o as t,a3 as i}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy.","frontmatter":{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy."},"headers":[],"relativePath":"templates/security-reviewer.md","filePath":"templates/security-reviewer.md"}'),o={name:"templates/security-reviewer.md"};function n(l,e,r,h,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i("",26)])])}const k=s(o,[["render",n]]);export{u as __pageData,k as default};
+import{_ as s,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy.","frontmatter":{"title":"Review pull requests for exploitable bugs","description":"Scaffold the agent, pick repos, replay a PR, and deploy."},"headers":[],"relativePath":"templates/security-reviewer.md","filePath":"templates/security-reviewer.md"}'),o={name:"templates/security-reviewer.md"};function n(l,e,r,h,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i("",26)])])}const k=s(o,[["render",n]]);export{u as __pageData,k as default};

package/dist/docs/assets/templates_thermo-quality-review.md.VNJ_mohX.js

@@ -0,0 +1,3 @@
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests for structural code quality","description":"Scaffold the agent, deploy it, and open a PR.","frontmatter":{"title":"Review pull requests for structural code quality","description":"Scaffold the agent, deploy it, and open a PR."},"headers":[],"relativePath":"templates/thermo-quality-review.md","filePath":"templates/thermo-quality-review.md"}'),l={name:"templates/thermo-quality-review.md"};function n(h,e,p,o,r,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="review-pull-requests-for-structural-code-quality" tabindex="-1">Review pull requests for structural code quality <a class="header-anchor" href="#review-pull-requests-for-structural-code-quality" aria-label="Permalink to &quot;Review pull requests for structural code quality&quot;">​</a></h1><p>This agent reads a pull request diff and posts one review comment. It reports missing abstractions, spaghetti branches, feature logic leaking into shared paths, and files pushed past 1,000 lines. Style nits and behavior disputes stay out.</p><p>This template is one model turn: read the diff, then post one comment.</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;">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;"> ./thermo-quality-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-quality-review</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-quality-review</span></span></code></pre></div><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy&quot;">​</a></h2><p>Sign in once, then deploy from a pushed checkout:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events-repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/api</span></span></code></pre></div><p>Repeat <code>--cursor-events-repo</code> for each repo. Every repo must share one owner. The deployment watches those repos through your team&#39;s Cursor GitHub connection and reviews each opened PR. No webhook or local server.</p><p>Change repos later without redeploying:</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;"> event-repos</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-quality-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/api</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/web</span></span></code></pre></div><h2 id="try-it-locally" tabindex="-1">Try it locally <a class="header-anchor" href="#try-it-locally" aria-label="Permalink to &quot;Try it locally&quot;">​</a></h2><p>Skip the deploy while you iterate. Start the relay for one repo:</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;"> dev</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;"> acme/api</span></span></code></pre></div><p>Open a PR, or replay a known one without pushing:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/api/pull/12</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>replay</code> needs pull access. Draft PRs are ignored. The channel writes <code>pr/diff.patch</code>, then starts a model turn. The model calls <code>post_findings</code> once. Chat replies stay in the playground. <code>post_findings</code> writes the GitHub comment.</p><p>Connect GitHub in Cursor first (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>) so the relay and API calls use your account. See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><p>Two smoke cases: one spaghetti-branch fixture and one clean fix. They need no GitHub access.</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></code></pre></div><p>Eval sessions skip the GitHub write.</p><h2 id="what-to-edit" tabindex="-1">What to edit <a class="header-anchor" href="#what-to-edit" aria-label="Permalink to &quot;What to edit&quot;">​</a></h2><ul><li><code>agent/instructions.md</code>: what counts as a finding and the comment shape</li><li><code>evals/review.eval.ts</code>: smoke cases</li></ul>`,24)])])}const u=s(l,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/templates_thermo-quality-review.md.VNJ_mohX.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests for structural code quality","description":"Scaffold the agent, deploy it, and open a PR.","frontmatter":{"title":"Review pull requests for structural code quality","description":"Scaffold the agent, deploy it, and open a PR."},"headers":[],"relativePath":"templates/thermo-quality-review.md","filePath":"templates/thermo-quality-review.md"}'),l={name:"templates/thermo-quality-review.md"};function n(h,e,p,o,r,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",24)])])}const u=s(l,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/templates_thermo-review.md.Hi3zWOkP.js

@@ -0,0 +1,3 @@
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests for bugs and breakage","description":"Scaffold the agent, deploy it, and open a PR.","frontmatter":{"title":"Review pull requests for bugs and breakage","description":"Scaffold the agent, deploy it, and open a PR."},"headers":[],"relativePath":"templates/thermo-review.md","filePath":"templates/thermo-review.md"}'),n={name:"templates/thermo-review.md"};function l(h,e,p,o,r,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="review-pull-requests-for-bugs-and-breakage" tabindex="-1">Review pull requests for bugs and breakage <a class="header-anchor" href="#review-pull-requests-for-bugs-and-breakage" aria-label="Permalink to &quot;Review pull requests for bugs and breakage&quot;">​</a></h1><p>This agent reads a pull request diff and posts one review comment. It reports bugs, breaking side effects, devex breaks, and feature-gate leaks in added or modified code. Style nits stay out.</p><p>This template is one model turn: read the diff, then post one comment.</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;">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;"> ./thermo-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-review</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-review</span></span></code></pre></div><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy&quot;">​</a></h2><p>Sign in once, then deploy from a pushed checkout:</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:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --cursor-events-repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/api</span></span></code></pre></div><p>Repeat <code>--cursor-events-repo</code> for each repo. Every repo must share one owner. The deployment watches those repos through your team&#39;s Cursor GitHub connection and reviews each opened PR. No webhook or local server.</p><p>Change repos later without redeploying:</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;"> event-repos</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> thermo-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/api</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme/web</span></span></code></pre></div><h2 id="try-it-locally" tabindex="-1">Try it locally <a class="header-anchor" href="#try-it-locally" aria-label="Permalink to &quot;Try it locally&quot;">​</a></h2><p>Skip the deploy while you iterate. Start the relay for one repo:</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;"> dev</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;"> acme/api</span></span></code></pre></div><p>Open a PR, or replay a known one without pushing:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/api/pull/12</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p><code>replay</code> needs pull access. Draft PRs are ignored. The channel writes <code>pr/diff.patch</code>, then starts a model turn. The model calls <code>post_findings</code> once. Chat replies stay in the playground. <code>post_findings</code> writes the GitHub comment.</p><p>Connect GitHub in Cursor first (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>) so the relay and API calls use your account. See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><p>Two smoke cases: one auth-bypass fixture and one docs-only change. They need no GitHub access.</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></code></pre></div><p>Eval sessions skip the GitHub write.</p><h2 id="what-to-edit" tabindex="-1">What to edit <a class="header-anchor" href="#what-to-edit" aria-label="Permalink to &quot;What to edit&quot;">​</a></h2><ul><li><code>agent/instructions.md</code>: what counts as a finding and the comment shape</li><li><code>evals/review.eval.ts</code>: smoke cases</li></ul>`,24)])])}const g=s(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/templates_thermo-review.md.Hi3zWOkP.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests for bugs and breakage","description":"Scaffold the agent, deploy it, and open a PR.","frontmatter":{"title":"Review pull requests for bugs and breakage","description":"Scaffold the agent, deploy it, and open a PR."},"headers":[],"relativePath":"templates/thermo-review.md","filePath":"templates/thermo-review.md"}'),n={name:"templates/thermo-review.md"};function l(h,e,p,o,r,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",24)])])}const g=s(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/{templates_triage.md.BdBWO9Ic.js → templates_triage.md.CVGe_FG6.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy.","frontmatter":{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function r(l,s,h,o,p,d){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="triage-linear-or-jira-issues-in-place" tabindex="-1">Triage Linear or Jira issues in place <a class="header-anchor" href="#triage-linear-or-jira-issues-in-place" aria-label="Permalink to &quot;Triage Linear or Jira issues in place&quot;">​</a></h1><p>This agent comments on tickets you already filed. It classifies the issue, writes a <code>Triage:</code> comment, sets bug priority, and links a duplicate when titles match.</p><p>File the ticket however you already do. This template starts after the ticket exists.</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;">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;"> ./triage-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-linear</span></span>
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy.","frontmatter":{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function r(l,s,h,o,p,d){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="triage-linear-or-jira-issues-in-place" tabindex="-1">Triage Linear or Jira issues in place <a class="header-anchor" href="#triage-linear-or-jira-issues-in-place" aria-label="Permalink to &quot;Triage Linear or Jira issues in place&quot;">​</a></h1><p>This agent comments on tickets you already filed. It classifies the issue, writes a <code>Triage:</code> comment, sets bug priority, and links a duplicate when titles match.</p><p>File the ticket however you already do. This template starts after the ticket exists.</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;">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;"> ./triage-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-linear</span></span>
 <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;"> ./triage-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-jira</span></span></code></pre></div><p>Pick the tracker you use. The agent is the same. The overlay is the connection.</p><p><code>init</code> writes the project, installs dependencies, and puts <code>agent-sdk</code> on PATH.</p><h2 id="log-in" tabindex="-1">Log in <a class="header-anchor" href="#log-in" aria-label="Permalink to &quot;Log in&quot;">​</a></h2><p>Model turns and Cursor MCP use your Cursor account.</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;"> triage-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;"> login</span></span></code></pre></div><p>The command opens a browser if you have no stored credential.</p><h2 id="connect-the-tracker" tabindex="-1">Connect the tracker <a class="header-anchor" href="#connect-the-tracker" aria-label="Permalink to &quot;Connect the tracker&quot;">​</a></h2><p>In the Cursor dashboard, open MCP and connect Linear or Jira.</p><p>The connection stays on the host. The model calls <code>record_triage</code>. Linear and Jira tools stay off the model&#39;s tool list.</p><h2 id="first-verdict" tabindex="-1">First verdict <a class="header-anchor" href="#first-verdict" aria-label="Permalink to &quot;First verdict&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;"> dev</span></span></code></pre></div><p>Open the playground. Run <code>/queue/issue</code> and paste an existing issue.</p><p>You can also POST:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/triage-agent/v1/channels/queue/issue</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

package/dist/docs/assets/{templates_triage.md.BdBWO9Ic.lean.js → templates_triage.md.CVGe_FG6.lean.js}

@@ -1 +1 @@
-import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy.","frontmatter":{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function r(l,s,h,o,p,d){return i(),a("div",null,[...s[0]||(s[0]=[t("",31)])])}const u=e(n,[["render",r]]);export{k as __pageData,u as default};
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy.","frontmatter":{"title":"Triage Linear or Jira issues in place","description":"Scaffold the agent, point it at an existing ticket, tune the rubric, run evals, and deploy."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function r(l,s,h,o,p,d){return i(),a("div",null,[...s[0]||(s[0]=[t("",31)])])}const u=e(n,[["render",r]]);export{k as __pageData,u as default};

package/dist/docs/assets/troubleshooting.md.mnfFG2Em.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as d,a3 as a}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough.","frontmatter":{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,l,c,h){return d(),o("div",null,[...e[0]||(e[0]=[a('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with three checks:</p><ol><li>Run <code>agent-sdk validate --dir .</code>.</li><li>Confirm the expected agent and connections in <code>agent-sdk info --dir . --json</code>.</li><li>Reproduce once, then inspect the serve log or session trace.</li></ol><p>Match the visible symptom below. If <code>agent-sdk</code> is not on <code>PATH</code>, use <code>npx @cursor/july</code>.</p><h2 id="serve-or-the-playground-will-not-work" tabindex="-1">Serve or the playground will not work <a class="header-anchor" href="#serve-or-the-playground-will-not-work" aria-label="Permalink to &quot;Serve or the playground will not work&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> exits before listening</td><td>Fix the errors from <code>agent-sdk validate --dir .</code>, then start it again.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>Start <code>agent-sdk serve</code>; built playground assets have no agent data without the server.</td></tr><tr><td>Agent-file edits do not appear</td><td>Open the URL printed by <code>serve --dev</code>, then press Enter in its TTY to reload after file changes.</td></tr><tr><td>Sessions exist but the list is empty</td><td>The list is scoped to the authenticated principal. Use the same identity that created the session; a <code>?sessionId=</code> deep link does not bypass authorization.</td></tr><tr><td>The preferred port is busy</td><td>Use the next port printed by the CLI, pass <code>--port &lt;number&gt;</code>, or pass <code>--port 0</code> for any free port.</td></tr></tbody></table><h2 id="a-model-turn-fails" tabindex="-1">A model turn fails <a class="header-anchor" href="#a-model-turn-fails" aria-label="Permalink to &quot;A model turn fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>File reads and greps fail repeatedly with <code>NGHTTP2_FRAME_SIZE_ERROR</code></td><td>Run the agent under Node 22.13 or newer, never Bun.</td></tr><tr><td>The turn immediately reports a missing API key</td><td>Set <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or run <code>agent-sdk login</code>.</td></tr><tr><td>Login succeeds but the model host rejects the key</td><td>Point login and model traffic at the same API host; check <code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>.</td></tr><tr><td>Cloud turns cannot reach local tools or skills</td><td>Give the cloud runtime a reachable <code>--public-url</code> and protected tool bridge, or move the required capability into the cloud checkout. See <a href="./reference/agent-config.html#choose-a-runtime">agent runtime</a>.</td></tr></tbody></table><h2 id="a-turn-behaves-unexpectedly" tabindex="-1">A turn behaves unexpectedly <a class="header-anchor" href="#a-turn-behaves-unexpectedly" aria-label="Permalink to &quot;A turn behaves unexpectedly&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Replies quote an ancestor <code>AGENTS.md</code> or unrelated repository rules</td><td>Inspect <code>local.cwd</code> in <code>/v1/info</code>. Set <code>defineAgent({ local: { cwd } })</code> or the session workspace explicitly instead of inheriting the parent checkout.</td></tr><tr><td>The model lists IDE meta-tools but never calls named MCP tools</td><td>Set <code>advertiseTools: true</code> on the local model-visible connection and confirm it under <code>connections</code> in <code>/v1/info</code>.</td></tr><tr><td>Server tools, skills, or seed files are absent</td><td>Check the selected local/cloud runtime and discovered project in <code>/v1/info</code>; follow the capability warning from <code>validate</code>.</td></tr><tr><td><code>validate</code> and <code>run</code> pass but CI type-checking fails</td><td>Run the project type check. Tool results must be JSON-shaped; prefer object literals or <code>type</code> aliases over <code>interface</code> return types.</td></tr></tbody></table><h2 id="http-returns-401-403-or-409" tabindex="-1">HTTP returns 401, 403, or 409 <a class="header-anchor" href="#http-returns-401-403-or-409" aria-label="Permalink to &quot;HTTP returns 401, 403, or 409&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>401</code> outside localhost</td><td>Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only.</td></tr><tr><td><code>403</code> on a stream or follow-up</td><td>Use the same authenticated principal that created the session.</td></tr><tr><td>A localhost route fails through a tunnel or LAN</td><td>Protect the shared host with <code>--bearer-token</code> or authored channel auth. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</td></tr><tr><td><code>409</code> on a follow-up</td><td>Refresh the rotating <code>continuationToken</code> and confirm the target is a chat session; task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> from <code>call --session</code></td><td>Wait for the turn, omit <code>--session</code>, or mark a read-only tool with <code>effect: &quot;read&quot;</code> so it can run concurrently.</td></tr><tr><td>A custom route fails schema type-checking</td><td>Add the required Zod <code>querySchema</code> for <code>GET</code>, or <code>bodySchema</code> for <code>POST</code>, <code>PUT</code>, and <code>PATCH</code>. See <a href="./reference/channels.html">Channels</a>.</td></tr></tbody></table><h2 id="a-hosted-deployment-fails-or-looks-stale" tabindex="-1">A hosted deployment fails or looks stale <a class="header-anchor" href="#a-hosted-deployment-fails-or-looks-stale" aria-label="Permalink to &quot;A hosted deployment fails or looks stale&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Local changes do not appear after deploy</td><td><code>deploy</code> reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again.</td></tr><tr><td>The deployment never becomes running</td><td>Run <code>agent-sdk deployment &lt;slug&gt;</code> and <code>agent-sdk logs --prod --slug &lt;slug&gt;</code>, then act on the reported build or startup error.</td></tr><tr><td>A secret or egress change has no effect</td><td>Confirm the name with <code>secrets list</code>, verify the <code>hosting</code> block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy.</td></tr><tr><td>Cursor events stopped after redeploy</td><td>Redeploy replaces CLI-supplied event repositories. Pass every <code>--cursor-events-repo</code> value again.</td></tr><tr><td>External HTTP rejects the alias token</td><td>Update the caller with the current token. If the token is lost or exposed, run <code>agent-sdk rotate-token &lt;slug&gt;</code> and replace it everywhere.</td></tr></tbody></table><p>See <a href="./deployment.html">Deployment</a> for source, credential, and redeployment boundaries.</p><h2 id="github-deliveries-fail" tabindex="-1">GitHub deliveries fail <a class="header-anchor" href="#github-deliveries-fail" aria-label="Permalink to &quot;GitHub deliveries fail&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery after creating the hook</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command so the forwarder uses the <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...</code>.</td></tr><tr><td><code>Hook already exists</code></td><td>Run one forwarder for the repository and stop the stale process.</td></tr><tr><td>Direct webhook deliveries are rejected outside <code>--dev</code></td><td>Configure the same <code>GITHUB_WEBHOOK_SECRET</code> on the signer and server. Cursor event pull needs no public webhook or webhook secret.</td></tr><tr><td>You cannot create a forwarder</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>; it needs pull access instead of repository administration.</td></tr></tbody></table><p>The <a href="./guides/github.html">GitHub guide</a> covers event pull, replay, and direct webhooks.</p><h2 id="slack-does-not-respond" tabindex="-1">Slack does not respond <a class="header-anchor" href="#slack-does-not-respond" aria-label="Permalink to &quot;Slack does not respond&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs say <code>channel idle ... missing credentials</code></td><td>Run <code>agent-sdk slack create --dir &lt;agent&gt;</code>, then check the generated prefix with <code>agent-sdk slack doctor</code>. Use <code>slack init --manual</code> only for an app you own.</td></tr><tr><td><code>slack create</code> is waiting for workspace approval</td><td>Open the approval link printed by the CLI, keep the command running, and retry after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Configure <code>engagement.channelPosts</code>, create the app with <code>--channel-posts</code>, and invite it to every allowed channel.</td></tr><tr><td>Approval buttons do nothing</td><td>Set <code>toolApprovals: true</code>, then recreate the app if its interactivity is not enabled.</td></tr></tbody></table><p>See the <a href="./guides/slack.html">Slack guide</a> for app setup and engagement choices.</p><h2 id="mcp-authorization-fails" tabindex="-1">MCP authorization fails <a class="header-anchor" href="#mcp-authorization-fails" aria-label="Permalink to &quot;MCP authorization fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>Add <code>oauth: true</code> to the named URL connection or correct the connection filename passed to <code>mcp oauth</code>.</td></tr><tr><td>Local auth works but hosted calls return unauthorized</td><td>Complete Connect for the running process, or run <code>mcp oauth &lt;name&gt; --store</code> and redeploy for future replacements.</td></tr><tr><td>The model invents <code>mcp_auth</code> instead of calling the server</td><td>Set <code>advertiseTools: true</code> for named local tools, or expose a host-side wrapper through <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> for the credential lifecycle.</p><h2 id="schedules-reminders-or-approvals-stall" tabindex="-1">Schedules, reminders, or approvals stall <a class="header-anchor" href="#schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;Schedules, reminders, or approvals stall&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Trigger it through the matching <code>/v1/dev/schedules/&lt;id&gt;</code> or <code>/v1/dev/reminders/&lt;id&gt;</code> route; development mode does not auto-fire.</td></tr><tr><td>A pending approval disappears after restart</td><td>Parked approvals do not survive restart. Run the turn again.</td></tr><tr><td>A reminder is disarmed with <code>handler_lost_on_restart</code></td><td>Recreate handler-form reminders after restart, or use a prompt-form reminder.</td></tr><tr><td>The same schedule fires on several self-hosted processes</td><td>Enable schedules on one serving process per project and pass <code>--no-schedules</code> to the others.</td></tr></tbody></table><h2 id="a-credential-was-exposed" tabindex="-1">A credential was exposed <a class="header-anchor" href="#a-credential-was-exposed" aria-label="Permalink to &quot;A credential was exposed&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A secret value appears in a command, transcript, or shell history</td><td>Rotate it at the provider, set it again through hidden input or stdin, and test the feature.</td></tr><tr><td>An alias token appears outside its secure destination</td><td>Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new value outside transcripts, and update every caller.</td></tr><tr><td>Someone printed a secret to verify it</td><td>Rotate it. Confirm only the name with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy and exercise the feature.</td></tr></tbody></table><h2 id="read-the-session-trace" tabindex="-1">Read the session trace <a class="header-anchor" href="#read-the-session-trace" aria-label="Permalink to &quot;Read the session trace&quot;">​</a></h2><p>Start with <code>actions.requested</code> and <code>action.result</code>. Count calls by tool name, pair every request with its result, and separate host preparation from tools chosen by the model.</p><p><code>turn.failed</code> with <code>turn interrupted</code> usually means a follow-up or stop ended the turn deliberately. Other failures should have an error event near the tool or model boundary that produced them.</p><p>Use the trace path printed by <code>agent-sdk run</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trace-pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>The playground&#39;s <strong>Open trace</strong> control renders the same trajectory. When the agent runs but makes poor decisions, move from diagnosis to a measured <a href="./hillclimbing.html">hillclimb</a>.</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="./deployment.html">Deployment</a>: hosted and self-hosted boundaries</li><li><a href="./reference/sessions.html">Sessions</a>: session ownership and event vocabulary</li><li><a href="./reference/cli.html">CLI reference</a>: command flags and exit behavior</li></ul>',36)])])}const m=t(r,[["render",s]]);export{u as __pageData,m as default};

package/dist/docs/assets/troubleshooting.md.mnfFG2Em.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as d,a3 as a}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough.","frontmatter":{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,l,c,h){return d(),o("div",null,[...e[0]||(e[0]=[a("",36)])])}const m=t(r,[["render",s]]);export{u as __pageData,m as default};