@cursor/july 0.1.108 → 0.1.111

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

@@ -1,4 +1,4 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.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.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>
 <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.Bds_XWcV.lean.js → templates_pr-autofixer.md.DqxocIGh.lean.js}

@@ -1 +1 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.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.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};

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

@@ -1,2 +1,2 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.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.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>
 <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.lshxbCLK.lean.js → templates_security-reviewer.md.Bhnvd8VE.lean.js}

@@ -1 +1 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.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.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};

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

@@ -1,4 +1,4 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.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.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>
 <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.Co4UNzkZ.lean.js → templates_triage.md.BdBWO9Ic.lean.js}

@@ -1 +1 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.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.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};

package/dist/docs/assets/{troubleshooting.md.CYEAO9bM.js → troubleshooting.md.BcgNoYtJ.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,ag as d}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,c,i,l,h){return a(),o("div",null,[...e[0]||(e[0]=[d('<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 four checks, in order:</p><ol><li>Project discovery: <code>agent-sdk validate --dir .</code></li><li>Whether the serve process is running</li><li>What the playground or HTTP API shows</li><li>The session event stream (trace)</li></ol><p>Match your symptom below. Keep the commands as <code>agent-sdk</code>. If it is not on <code>PATH</code>, use <code>npx @cursor/july</code>.</p><h2 id="what-if-serve-or-the-playground-looks-wrong" tabindex="-1">What if serve or the playground looks wrong? <a class="header-anchor" href="#what-if-serve-or-the-playground-looks-wrong" aria-label="Permalink to &quot;What if serve or the playground looks wrong?&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> won&#39;t start</td><td>Run <code>agent-sdk validate --dir .</code> and fix the reported errors.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>The UI needs a running <code>serve</code> process. Building the playground assets alone is not enough.</td></tr><tr><td>The playground UI looks stale</td><td><code>serve --dev</code> prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY).</td></tr><tr><td>Sessions exist but the playground list is empty</td><td>The list shows sessions for the authenticated caller. In <code>--dev</code> on loopback the list is wider. Otherwise open <code>/&lt;slug&gt;/playground?sessionId=ses_…</code>.</td></tr><tr><td>Port 3000 is already in use</td><td>For the default serve port, the CLI tries the next free port and prints a notice. Pass <code>--port</code> to pick one, or <code>--port 0</code> for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port.</td></tr></tbody></table><h2 id="what-if-a-model-turn-goes-wrong" tabindex="-1">What if a model turn goes wrong? <a class="header-anchor" href="#what-if-a-model-turn-goes-wrong" aria-label="Permalink to &quot;What if a model turn goes wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Built-in file reads and greps fail; the turn retries for a long time</td><td>Run under Node 22.13+ (or <code>tsx</code>), never Bun. Look for <code>NGHTTP2_FRAME_SIZE_ERROR</code> in logs.</td></tr><tr><td>The turn fails immediately with an API-key error</td><td>Sign in with <code>agent-sdk login</code>, or set <code>CURSOR_API_KEY</code> or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>. Discovery, <code>info</code>, <code>call</code>, and serve bring-up work without a key; model turns need one.</td></tr><tr><td>Replies quote rules or <code>AGENTS.md</code> from outside your agent project</td><td>The session workspace inherited parent-folder config. Nested git checkouts default <code>local.cwd</code> to a per-project cache directory under <code>~/.cache</code>. Point <code>defineAgent({ local: { cwd } })</code> at a checkout only when the agent should inherit that tree, or set <code>--state-root</code> to a clean directory (for example under <code>/tmp</code>).</td></tr><tr><td>Yellow box shows Datadog/Linear tools, but the model lists <code>GetDynamicTools</code> / IDE <code>cursor</code> tools and never calls them</td><td>Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set <code>advertiseTools: true</code> for named tools on local turns. Check <code>GET /v1/info</code> <code>local.cwd</code> and <code>connections[].advertiseTools</code>.</td></tr><tr><td>Server tools, skills, or workspace seed files never appear</td><td>Server tools and sandbox seeds apply on the local runtime (cloud server tools need <code>--public-url</code> / <code>--cloud-tools-url</code>). Skills reach cloud through the Agent Store when hosting or a personal <code>CURSOR_API_KEY</code> is available; otherwise only skills already in the cloud repo. <code>validate</code> warns when this combination is present.</td></tr><tr><td><code>validate</code> and <code>run</code> succeed, but typecheck fails in CI</td><td>The CLI runs TypeScript with type-stripping only. Keep tool <code>execute</code> return types as object literals or <code>type</code> aliases, not <code>interface</code> types.</td></tr><tr><td>Login works, but turns are rejected when using custom API hosts</td><td>Point login and model traffic at the same host (<code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>). A key from one host is rejected by the other.</td></tr></tbody></table><h2 id="what-if-the-http-api-returns-an-error" tabindex="-1">What if the HTTP API returns an error? <a class="header-anchor" href="#what-if-the-http-api-returns-an-error" aria-label="Permalink to &quot;What if the HTTP API returns an error?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>409</code> on a follow-up message</td><td>Refresh the <code>continuationToken</code> or confirm the session is a chat session. Task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit <code>--session</code> for a one-off call, or declare <code>effect: &quot;read&quot;</code> on a tool that only reads so it runs alongside turns.</td></tr><tr><td><code>403</code> on stream or follow-up</td><td>Use the same auth identity that created the session. Off localhost, pass <code>--bearer-token</code> and send it on every request.</td></tr><tr><td>Works on localhost; blocked through a tunnel or LAN</td><td>Default auth allows only direct loopback callers. Share the host with <code>--bearer-token &lt;secret&gt;</code> (or authored <code>bearerAuth</code>). Use <code>--allow-anonymous</code> only on a trusted private network.</td></tr><tr><td>A channel route fails to compile with a schema type error</td><td><code>GET</code> routes need a Zod <code>querySchema</code>. <code>POST</code> / <code>PUT</code> / <code>PATCH</code> need a Zod <code>bodySchema</code>. Use <code>z.object({})</code> or <code>z.unknown()</code> for open shapes.</td></tr></tbody></table><h2 id="what-if-github-webhooks-misbehave" tabindex="-1">What if GitHub webhooks misbehave? <a class="header-anchor" href="#what-if-github-webhooks-misbehave" aria-label="Permalink to &quot;What if GitHub webhooks misbehave?&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, but the hook was created</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command. The forwarder uses your <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …</code></td></tr><tr><td><code>Hook already exists</code> when starting a forwarder</td><td>GitHub allows one forwarder per repo. Run a single <code>github forward --dir &lt;parent&gt;</code> and stop stale forwarders.</td></tr><tr><td>Deliveries rejected outside <code>--dev</code></td><td>Set <code>GITHUB_WEBHOOK_SECRET</code> on the server and on the signer. Without a secret, the channel stays loopback-only.</td></tr><tr><td>You lack repo admin and can&#39;t forward</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>. It needs pull access only and posts signed test payloads.</td></tr></tbody></table><h2 id="what-if-slack-stays-quiet" tabindex="-1">What if Slack stays quiet? <a class="header-anchor" href="#what-if-slack-stays-quiet" aria-label="Permalink to &quot;What if Slack stays quiet?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs show <code>channel idle … missing credentials</code></td><td>Expected when tokens are missing. Run <code>agent-sdk slack create --dir &lt;agent&gt;</code> to provision the app and write the tokens, or <code>agent-sdk slack init --manual --dir &lt;agent&gt;</code> and paste the manifests at api.slack.com. Then set <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> per agent and run <code>agent-sdk slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td><code>slack create</code> reports the app needs admin approval</td><td>Open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link; the same URL is <strong>Send a reminder</strong> after you submit). Managed install does not file the request. Keep the CLI running, then click <strong>Retry</strong> in the dashboard after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Default engagement is mentions and DMs only. Enable <code>engagement.channelPosts</code> with an allowlist, and subscribe the app to <code>message.channels</code> / <code>message.groups</code>.</td></tr><tr><td>Approve / Deny buttons do nothing</td><td>Channels that post approval cards need <code>toolApprovals: true</code>. Recreate the app with <code>slack create</code> if interactivity is off.</td></tr></tbody></table><h2 id="what-if-host-mcp-oauth-fails" tabindex="-1">What if host MCP OAuth fails? <a class="header-anchor" href="#what-if-host-mcp-oauth-fails" aria-label="Permalink to &quot;What if host MCP OAuth 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>The connection file needs <code>oauth: true</code>, or you passed the wrong connection name to <code>agent-sdk mcp oauth</code>.</td></tr><tr><td>Local auth works; hosted calls unauthorized</td><td>Finish Connect on the hosted engine, or run <code>agent-sdk mcp oauth &lt;name&gt; --store</code>. Confirm names with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy.</td></tr><tr><td>Model asks for <code>mcp_auth</code> or IDE MCP for a connector it already has</td><td>Attached MCP is behind meta-tools. Set <code>advertiseTools: true</code> for named tools on local turns, or call it from a host tool via <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> and <a href="./skills/mcp-auth.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-if-a-secret-showed-up-in-a-terminal-transcript" tabindex="-1">What if a secret showed up in a terminal transcript? <a class="header-anchor" href="#what-if-a-secret-showed-up-in-a-terminal-transcript" aria-label="Permalink to &quot;What if a secret showed up in a terminal transcript?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>secrets set … NAME=VALUE</code> in an agent-captured terminal or shell history</td><td>Rotate the secret at the provider. Set it again with names only: <code>agent-sdk secrets set &lt;slug&gt; NAME</code> (hidden prompt) or pipe/redirect the value. <code>NAME=VALUE</code> requires <code>--from-argv</code> and still leaks into argv.</td></tr><tr><td>Alias token printed during first deploy or <code>rotate-token</code></td><td>Treat it as exposed if the transcript left your machine. Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new token outside agent transcripts, and update callers.</td></tr><tr><td>Someone verified a secret with <code>echo</code> / <code>printenv</code></td><td>Rotate it. Confirm presence with <code>agent-sdk secrets list &lt;slug&gt;</code> (names only), then redeploy and test the feature.</td></tr></tbody></table><h2 id="what-if-schedules-reminders-or-approvals-stall" tabindex="-1">What if schedules, reminders, or approvals stall? <a class="header-anchor" href="#what-if-schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;What if 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>Dev mode does not auto-fire. Trigger with <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code> or <code>POST /&lt;slug&gt;/v1/dev/reminders/&lt;id&gt;</code> (list reminders at <code>GET /v1/dev/reminders</code>).</td></tr><tr><td>A pending tool approval disappeared after restart</td><td>Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again.</td></tr><tr><td>A reminder is disarmed after restart (<code>handler_lost_on_restart</code>)</td><td>Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders.</td></tr></tbody></table><h2 id="how-do-i-read-a-session-trace" tabindex="-1">How do I read a session trace? <a class="header-anchor" href="#how-do-i-read-a-session-trace" aria-label="Permalink to &quot;How do I read a session trace?&quot;">​</a></h2><p>Look at <code>actions.requested</code> / <code>action.result</code> pairs for the tool trajectory. Count calls by tool name before blaming latency. Separate host-side work (channel <code>callTool</code>, preparation) from tools the model chose.</p><p><code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> means a follow-up or stop ended the turn on purpose.</p><p>If the model reads outside the session workspace, the prepared files don&#39;t match what the instructions expect. Fix the layout. See <a href="./hillclimbing.html">Hillclimbing</a>.</p><p><code>agent-sdk trajectory --events &lt;file&gt;</code> summarizes any saved NDJSON stream. The playground <strong>Open trace</strong> control does the same visually.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./concepts.html">Concepts</a>: the model behind these symptoms</li><li><a href="./hillclimbing.html">Hillclimbing</a>: when the agent runs but underperforms</li><li><a href="./deployment.html">Deployment</a>: auth and state on shared hosts</li></ul>',28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};
+import{_ as t,c as o,o as a,a3 as d}from"./chunks/framework.dypDpWZ3.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,c,i,l,h){return a(),o("div",null,[...e[0]||(e[0]=[d('<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 four checks, in order:</p><ol><li>Project discovery: <code>agent-sdk validate --dir .</code></li><li>Whether the serve process is running</li><li>What the playground or HTTP API shows</li><li>The session event stream (trace)</li></ol><p>Match your symptom below. Keep the commands as <code>agent-sdk</code>. If it is not on <code>PATH</code>, use <code>npx @cursor/july</code>.</p><h2 id="what-if-serve-or-the-playground-looks-wrong" tabindex="-1">What if serve or the playground looks wrong? <a class="header-anchor" href="#what-if-serve-or-the-playground-looks-wrong" aria-label="Permalink to &quot;What if serve or the playground looks wrong?&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> won&#39;t start</td><td>Run <code>agent-sdk validate --dir .</code> and fix the reported errors.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>The UI needs a running <code>serve</code> process. Building the playground assets alone is not enough.</td></tr><tr><td>The playground UI looks stale</td><td><code>serve --dev</code> prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY).</td></tr><tr><td>Sessions exist but the playground list is empty</td><td>The list shows sessions for the authenticated caller. In <code>--dev</code> on loopback the list is wider. Otherwise open <code>/&lt;slug&gt;/playground?sessionId=ses_…</code>.</td></tr><tr><td>Port 3000 is already in use</td><td>For the default serve port, the CLI tries the next free port and prints a notice. Pass <code>--port</code> to pick one, or <code>--port 0</code> for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port.</td></tr></tbody></table><h2 id="what-if-a-model-turn-goes-wrong" tabindex="-1">What if a model turn goes wrong? <a class="header-anchor" href="#what-if-a-model-turn-goes-wrong" aria-label="Permalink to &quot;What if a model turn goes wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Built-in file reads and greps fail; the turn retries for a long time</td><td>Run under Node 22.13+ (or <code>tsx</code>), never Bun. Look for <code>NGHTTP2_FRAME_SIZE_ERROR</code> in logs.</td></tr><tr><td>The turn fails immediately with an API-key error</td><td>Sign in with <code>agent-sdk login</code>, or set <code>CURSOR_API_KEY</code> or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>. Discovery, <code>info</code>, <code>call</code>, and serve bring-up work without a key; model turns need one.</td></tr><tr><td>Replies quote rules or <code>AGENTS.md</code> from outside your agent project</td><td>The session workspace inherited parent-folder config. Nested git checkouts default <code>local.cwd</code> to a per-project cache directory under <code>~/.cache</code>. Point <code>defineAgent({ local: { cwd } })</code> at a checkout only when the agent should inherit that tree, or set <code>--state-root</code> to a clean directory (for example under <code>/tmp</code>).</td></tr><tr><td>Yellow box shows Datadog/Linear tools, but the model lists <code>GetDynamicTools</code> / IDE <code>cursor</code> tools and never calls them</td><td>Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set <code>advertiseTools: true</code> for named tools on local turns. Check <code>GET /v1/info</code> <code>local.cwd</code> and <code>connections[].advertiseTools</code>.</td></tr><tr><td>Server tools, skills, or workspace seed files never appear</td><td>Server tools and sandbox seeds apply on the local runtime (cloud server tools need <code>--public-url</code> / <code>--cloud-tools-url</code>). Skills reach cloud through the Agent Store when hosting or a personal <code>CURSOR_API_KEY</code> is available; otherwise only skills already in the cloud repo. <code>validate</code> warns when this combination is present.</td></tr><tr><td><code>validate</code> and <code>run</code> succeed, but typecheck fails in CI</td><td>The CLI runs TypeScript with type-stripping only. Keep tool <code>execute</code> return types as object literals or <code>type</code> aliases, not <code>interface</code> types.</td></tr><tr><td>Login works, but turns are rejected when using custom API hosts</td><td>Point login and model traffic at the same host (<code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>). A key from one host is rejected by the other.</td></tr></tbody></table><h2 id="what-if-the-http-api-returns-an-error" tabindex="-1">What if the HTTP API returns an error? <a class="header-anchor" href="#what-if-the-http-api-returns-an-error" aria-label="Permalink to &quot;What if the HTTP API returns an error?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>409</code> on a follow-up message</td><td>Refresh the <code>continuationToken</code> or confirm the session is a chat session. Task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit <code>--session</code> for a one-off call, or declare <code>effect: &quot;read&quot;</code> on a tool that only reads so it runs alongside turns.</td></tr><tr><td><code>403</code> on stream or follow-up</td><td>Use the same auth identity that created the session. Off localhost, pass <code>--bearer-token</code> and send it on every request.</td></tr><tr><td>Works on localhost; blocked through a tunnel or LAN</td><td>Default auth allows only direct loopback callers. Share the host with <code>--bearer-token &lt;secret&gt;</code> (or authored <code>bearerAuth</code>). Use <code>--allow-anonymous</code> only on a trusted private network.</td></tr><tr><td>A channel route fails to compile with a schema type error</td><td><code>GET</code> routes need a Zod <code>querySchema</code>. <code>POST</code> / <code>PUT</code> / <code>PATCH</code> need a Zod <code>bodySchema</code>. Use <code>z.object({})</code> or <code>z.unknown()</code> for open shapes.</td></tr></tbody></table><h2 id="what-if-github-webhooks-misbehave" tabindex="-1">What if GitHub webhooks misbehave? <a class="header-anchor" href="#what-if-github-webhooks-misbehave" aria-label="Permalink to &quot;What if GitHub webhooks misbehave?&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, but the hook was created</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command. The forwarder uses your <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …</code></td></tr><tr><td><code>Hook already exists</code> when starting a forwarder</td><td>GitHub allows one forwarder per repo. Run a single <code>github forward --dir &lt;parent&gt;</code> and stop stale forwarders.</td></tr><tr><td>Deliveries rejected outside <code>--dev</code></td><td>Set <code>GITHUB_WEBHOOK_SECRET</code> on the server and on the signer. Without a secret, the channel stays loopback-only.</td></tr><tr><td>You lack repo admin and can&#39;t forward</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>. It needs pull access only and posts signed test payloads.</td></tr></tbody></table><h2 id="what-if-slack-stays-quiet" tabindex="-1">What if Slack stays quiet? <a class="header-anchor" href="#what-if-slack-stays-quiet" aria-label="Permalink to &quot;What if Slack stays quiet?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs show <code>channel idle … missing credentials</code></td><td>Expected when tokens are missing. Run <code>agent-sdk slack create --dir &lt;agent&gt;</code> to provision the app and write the tokens, or <code>agent-sdk slack init --manual --dir &lt;agent&gt;</code> and paste the manifests at api.slack.com. Then set <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> per agent and run <code>agent-sdk slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td><code>slack create</code> reports the app needs admin approval</td><td>Open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link; the same URL is <strong>Send a reminder</strong> after you submit). Managed install does not file the request. Keep the CLI running, then click <strong>Retry</strong> in the dashboard after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Default engagement is mentions and DMs only. Enable <code>engagement.channelPosts</code> with an allowlist, and subscribe the app to <code>message.channels</code> / <code>message.groups</code>.</td></tr><tr><td>Approve / Deny buttons do nothing</td><td>Channels that post approval cards need <code>toolApprovals: true</code>. Recreate the app with <code>slack create</code> if interactivity is off.</td></tr></tbody></table><h2 id="what-if-host-mcp-oauth-fails" tabindex="-1">What if host MCP OAuth fails? <a class="header-anchor" href="#what-if-host-mcp-oauth-fails" aria-label="Permalink to &quot;What if host MCP OAuth 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>The connection file needs <code>oauth: true</code>, or you passed the wrong connection name to <code>agent-sdk mcp oauth</code>.</td></tr><tr><td>Local auth works; hosted calls unauthorized</td><td>Finish Connect on the hosted engine, or run <code>agent-sdk mcp oauth &lt;name&gt; --store</code>. Confirm names with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy.</td></tr><tr><td>Model asks for <code>mcp_auth</code> or IDE MCP for a connector it already has</td><td>Attached MCP is behind meta-tools. Set <code>advertiseTools: true</code> for named tools on local turns, or call it from a host tool via <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> and <a href="./../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-if-a-secret-showed-up-in-a-terminal-transcript" tabindex="-1">What if a secret showed up in a terminal transcript? <a class="header-anchor" href="#what-if-a-secret-showed-up-in-a-terminal-transcript" aria-label="Permalink to &quot;What if a secret showed up in a terminal transcript?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>secrets set … NAME=VALUE</code> in an agent-captured terminal or shell history</td><td>Rotate the secret at the provider. Set it again with names only: <code>agent-sdk secrets set &lt;slug&gt; NAME</code> (hidden prompt) or pipe/redirect the value. <code>NAME=VALUE</code> requires <code>--from-argv</code> and still leaks into argv.</td></tr><tr><td>Alias token printed during first deploy or <code>rotate-token</code></td><td>Treat it as exposed if the transcript left your machine. Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new token outside agent transcripts, and update callers.</td></tr><tr><td>Someone verified a secret with <code>echo</code> / <code>printenv</code></td><td>Rotate it. Confirm presence with <code>agent-sdk secrets list &lt;slug&gt;</code> (names only), then redeploy and test the feature.</td></tr></tbody></table><h2 id="what-if-schedules-reminders-or-approvals-stall" tabindex="-1">What if schedules, reminders, or approvals stall? <a class="header-anchor" href="#what-if-schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;What if 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>Dev mode does not auto-fire. Trigger with <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code> or <code>POST /&lt;slug&gt;/v1/dev/reminders/&lt;id&gt;</code> (list reminders at <code>GET /v1/dev/reminders</code>).</td></tr><tr><td>A pending tool approval disappeared after restart</td><td>Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again.</td></tr><tr><td>A reminder is disarmed after restart (<code>handler_lost_on_restart</code>)</td><td>Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders.</td></tr></tbody></table><h2 id="how-do-i-read-a-session-trace" tabindex="-1">How do I read a session trace? <a class="header-anchor" href="#how-do-i-read-a-session-trace" aria-label="Permalink to &quot;How do I read a session trace?&quot;">​</a></h2><p>Look at <code>actions.requested</code> / <code>action.result</code> pairs for the tool trajectory. Count calls by tool name before blaming latency. Separate host-side work (channel <code>callTool</code>, preparation) from tools the model chose.</p><p><code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> means a follow-up or stop ended the turn on purpose.</p><p>If the model reads outside the session workspace, the prepared files don&#39;t match what the instructions expect. Fix the layout. See <a href="./hillclimbing.html">Hillclimbing</a>.</p><p><code>agent-sdk trajectory --events &lt;file&gt;</code> summarizes any saved NDJSON stream. The playground <strong>Open trace</strong> control does the same visually.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./hillclimbing.html">Hillclimbing</a>: when the agent runs but underperforms</li><li><a href="./deployment.html">Deployment</a>: auth and state on shared hosts</li></ul>',28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};

package/dist/docs/assets/{troubleshooting.md.CYEAO9bM.lean.js → troubleshooting.md.BcgNoYtJ.lean.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,ag as d}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,c,i,l,h){return a(),o("div",null,[...e[0]||(e[0]=[d("",28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};
+import{_ as t,c as o,o as a,a3 as d}from"./chunks/framework.dypDpWZ3.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,c,i,l,h){return a(),o("div",null,[...e[0]||(e[0]=[d("",28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};