@cursor/july 0.1.107 → 0.1.108

package/dist/docs/assets/{skills_create-agent.md.BVoWPcan.js → skills_create-agent.md.Q3h6Je-e.js}

@@ -2,7 +2,7 @@ import{_ as t,c as s,o as i,ag as a}from"./chunks/framework.BCISBCiQ.js";const k
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">too</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{…}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsc</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --noEmit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>tsx does not typecheck. Tool <code>execute</code> must return JSON-shaped values: object literals or <code>type</code> aliases, not <code>interface</code> types.</p><p>Model turns need <code>CURSOR_API_KEY</code>. Without one, finish the key-free checks, confirm <code>run</code> fails with only the API-key error, and hand these over:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;fixture prompt&gt;&quot;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsc</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --noEmit</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>tsx does not typecheck. Tool <code>execute</code> must return JSON-shaped values: object literals or <code>type</code> aliases, not <code>interface</code> types.</p><p>Model turns need a Cursor credential (<code>CURSOR_API_KEY</code>, then <code>CURSOR_API_KEY_FILE</code>, then <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>agent-sdk login</code>). Without one, finish the key-free checks, confirm <code>run</code> fails with only the API-key error, and hand these over:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;fixture prompt&gt;&quot;</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> single</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># http://127.0.0.1:3000/playground</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Serve only this agent&#39;s directory. Session files land in the project state directory (<code>--state-root</code>). That is not harness cwd.</p><h2 id="channel-setup" tabindex="-1">Channel setup <a class="header-anchor" href="#channel-setup" aria-label="Permalink to &quot;Channel setup&quot;">​</a></h2><ul><li><strong>Slack.</strong> <code>skills/setup-slack/SKILL.md</code></li><li><strong>GitHub.</strong> <code>skills/github/SKILL.md</code></li><li><strong>Custom webhook.</strong> <code>POST /v1/channels/&lt;id&gt;/&lt;route&gt;</code>. Loopback-only until you add <code>bearerAuth(...)</code>.</li><li><strong>Schedules.</strong> Never auto-fire under <code>--dev</code>. <code>POST /v1/dev/schedules/&lt;id&gt;</code>.</li></ul><h2 id="hillclimb-handoff" tabindex="-1">Hillclimb handoff <a class="header-anchor" href="#hillclimb-handoff" aria-label="Permalink to &quot;Hillclimb handoff&quot;">​</a></h2><p>Once a smoke turn passes, agree fixtures, success criteria, and a freeze line, then follow <code>skills/hillclimb/SKILL.md</code>. Seed from the smoke session under the project state directory. GitHub: snapshot <code>agent-sdk github replay ... --dry-run --out fixtures/github</code>.</p><p>Do not deploy or post to real Slack/GitHub beyond the smoke the user asked for. If the plan grows past ~10 files, cut scope. Re-check the budget at hand-off.</p>`,35)])])}const g=t(o,[["render",n]]);export{k as __pageData,g as default};

package/dist/docs/assets/{skills_debug.md.CDbPhHfg.js → skills_debug.md.CVjCXMFF.js}

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

package/dist/docs/assets/{skills_debug.md.CDbPhHfg.lean.js → skills_debug.md.CVjCXMFF.lean.js}

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

package/dist/docs/assets/{skills_evals.md.723kpUmA.js → skills_evals.md.BhovOvrl.js}

@@ -1,7 +1,7 @@
 import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse('{"title":"Agent SDK evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first. Live A/B is defineAB (skills/ab), not defineEval.","frontmatter":{"name":"agentsdk-evals","description":"Author and run defineEval cases. Use when writing, fixing, seeding, or hillclimbing evals. Ask whether to generate samples or take uploaded data. Materialize API-backed fixtures first. Live A/B is defineAB (skills/ab), not defineEval."},"headers":[],"relativePath":"../skills/evals/SKILL.md","filePath":"../skills/evals/SKILL.md"}'),n={name:"../skills/evals/SKILL.md"};function l(h,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="agent-sdk-evals" tabindex="-1">Agent SDK evals <a class="header-anchor" href="#agent-sdk-evals" aria-label="Permalink to &quot;Agent SDK evals&quot;">​</a></h1><p>Fixed input, model turn, gates on the trajectory. Files live at project-root <code>evals/**/*.eval.ts</code>. <code>agent/evals/</code> is ignored.</p><p>Live traffic variants: <code>skills/ab/SKILL.md</code>. That is not a test runner.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather/nyc</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Form</th><th>Case id</th></tr></thead><tbody><tr><td><code>evals/weather.eval.ts</code> + <code>test</code></td><td><code>weather</code></td></tr><tr><td><code>evals/weather/nyc.eval.ts</code> + <code>test</code></td><td><code>weather/nyc</code></td></tr><tr><td><code>evals/weather.eval.ts</code> + <code>{ id: &quot;nyc&quot; }</code></td><td><code>weather/nyc</code></td></tr></tbody></table><p><code>eval</code> boots an ephemeral server and a temp state root. <code>--url</code> points at a running agent. Model turns need <code>CURSOR_API_KEY</code>.</p><h2 id="seeding" tabindex="-1">Seeding <a class="header-anchor" href="#seeding" aria-label="Permalink to &quot;Seeding&quot;">​</a></h2><p>Creating or expanding cases: <code>AskQuestion</code> first.</p><table tabindex="0"><thead><tr><th>Question</th><th>Options</th></tr></thead><tbody><tr><td><strong>How should we get eval samples?</strong></td><td>Generate test eval samples for me <code>(recommended)</code> · I will add / upload the data manually</td></tr></tbody></table><ol><li><strong>Manual.</strong> They provide files or paste. Show the shape below. Do not invent cases. Then <code>eval --list</code> and wire gates. API-backed pointers (PR URLs, SHAs, gold labels): materialize under <code>fixtures/</code> first.</li><li><strong>Generated.</strong> Ask count (<code>3</code> recommended). Append to an existing <code>cases</code> array when it fits. Never overwrite or weaken a datapoint. Create <code>evals/evals.config.ts</code> if missing (<code>maxConcurrency: 20</code>; cap 200).</li></ol><h2 id="api" tabindex="-1">API <a class="header-anchor" href="#api" aria-label="Permalink to &quot;API&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEval, includes, satisfies } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Form</th><th>Case id</th></tr></thead><tbody><tr><td><code>evals/weather.eval.ts</code> + <code>test</code></td><td><code>weather</code></td></tr><tr><td><code>evals/weather/nyc.eval.ts</code> + <code>test</code></td><td><code>weather/nyc</code></td></tr><tr><td><code>evals/weather.eval.ts</code> + <code>{ id: &quot;nyc&quot; }</code></td><td><code>weather/nyc</code></td></tr></tbody></table><p><code>eval</code> boots an ephemeral server and a temp state root. <code>--url</code> points at a running agent. Model turns need a Cursor credential (<code>CURSOR_API_KEY</code>, then <code>CURSOR_API_KEY_FILE</code>, then <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>agent-sdk login</code>).</p><h2 id="seeding" tabindex="-1">Seeding <a class="header-anchor" href="#seeding" aria-label="Permalink to &quot;Seeding&quot;">​</a></h2><p>Creating or expanding cases: <code>AskQuestion</code> first.</p><table tabindex="0"><thead><tr><th>Question</th><th>Options</th></tr></thead><tbody><tr><td><strong>How should we get eval samples?</strong></td><td>Generate test eval samples for me <code>(recommended)</code> · I will add / upload the data manually</td></tr></tbody></table><ol><li><strong>Manual.</strong> They provide files or paste. Show the shape below. Do not invent cases. Then <code>eval --list</code> and wire gates. API-backed pointers (PR URLs, SHAs, gold labels): materialize under <code>fixtures/</code> first.</li><li><strong>Generated.</strong> Ask count (<code>3</code> recommended). Append to an existing <code>cases</code> array when it fits. Never overwrite or weaken a datapoint. Create <code>evals/evals.config.ts</code> if missing (<code>maxConcurrency: 20</code>; cap 200).</li></ol><h2 id="api" tabindex="-1">API <a class="header-anchor" href="#api" aria-label="Permalink to &quot;API&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEval, includes, satisfies } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smoke&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>

package/dist/docs/assets/skills_framework-map.md.D-tFZhFS.js

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

package/dist/docs/assets/{skills_framework-map.md.haibFyoB.lean.js → skills_framework-map.md.D-tFZhFS.lean.js}

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

package/dist/docs/assets/{skills_github.md.D0JahM8c.js → skills_github.md.hgFX_oKY.js}

@@ -8,7 +8,7 @@ import{_ as i,c as t,o as a,ag as e}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    pr.action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;opened&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onCheckSuite</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">suite</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    suite.conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;failure&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> triage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Hooks: <code>onPullRequest</code>, <code>onComment</code>, <code>onIssue</code>, <code>onCheckSuite</code>, <code>onCheckRun</code>, <code>onWorkflowRun</code>, <code>onStatus</code>, plus <code>onEvent</code> and <code>onStart</code>/<code>onStop</code>.</p><table tabindex="0"><thead><tr><th>Return</th><th>Meaning</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Model turn. Session shows in the playground. <code>workspaceFiles</code> can be a function.</td></tr><tr><td><code>{ task }</code></td><td>Host work. No chat session. Use when the work can outlive a webhook timeout.</td></tr><tr><td><code>null</code></td><td>Skip</td></tr></tbody></table><p>To keep repo scope in deploy config, use <code>cursorAccount: true</code> and pass <code>--repo owner/name</code> at serve / <code>--cursor-events-repo</code> at deploy. Repos must share one GitHub owner.</p><h2 id="event-sources" tabindex="-1">Event sources <a class="header-anchor" href="#event-sources" aria-label="Permalink to &quot;Event sources&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Source</th><th>When</th></tr></thead><tbody><tr><td><code>cursorAccount</code> + <code>serve --cursor-events</code></td><td>Preferred. Signed-in host (<code>agent-sdk login</code> / <code>CURSOR_API_KEY</code>). Repos from the channel and from repeatable <code>--repo owner/name</code>. Cap 20, one GitHub owner</td></tr><tr><td>HTTP <code>POST /&lt;slug&gt;/v1/channels/github</code> with a webhook secret</td><td><code>allowAll()</code> + <code>X-Hub-Signature-256</code></td></tr><tr><td>HTTP, no secret</td><td>Loopback only. <code>serve --dev</code> also admits unsigned loopback (fixtures / forward)</td></tr></tbody></table><p><code>permissions</code>: <code>&quot;read&quot;</code> inspect; <code>&quot;pr-write&quot;</code> (default) comments / PR writes; <code>&quot;contents-write&quot;</code> push or merge-box checks. <code>progress.commitStatus</code> needs check-write; see the GitHub guide. Set <code>checks: true</code> when channel code posts its own Checks API runs through <code>ctx.github.createCheck</code>. The flag grants access. It does not post a check.</p><p>Without <code>cursorAccount</code>, outbound calls prefer App installation tokens (<code>GITHUB_APP_ID</code> + <code>GITHUB_APP_PRIVATE_KEY</code>). Local tests can use <code>GITHUB_TOKEN</code> / <code>gh auth login</code>.</p><p>The Cursor stream is metadata, not full webhook bodies. Re-read the PR from GitHub.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><ol><li><strong>Fixtures</strong> (offline, <code>--dev</code>, no signature):</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/channels/github</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Hooks: <code>onPullRequest</code>, <code>onComment</code>, <code>onIssue</code>, <code>onCheckSuite</code>, <code>onCheckRun</code>, <code>onWorkflowRun</code>, <code>onStatus</code>, plus <code>onEvent</code> and <code>onStart</code>/<code>onStop</code>.</p><table tabindex="0"><thead><tr><th>Return</th><th>Meaning</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Model turn. Session shows in the playground. <code>workspaceFiles</code> can be a function.</td></tr><tr><td><code>{ task }</code></td><td>Host work. No chat session. Use when the work can outlive a webhook timeout.</td></tr><tr><td><code>null</code></td><td>Skip</td></tr></tbody></table><p>To keep repo scope in deploy config, use <code>cursorAccount: true</code> and pass <code>--repo owner/name</code> at serve / <code>--cursor-events-repo</code> at deploy. Repos must share one GitHub owner.</p><h2 id="event-sources" tabindex="-1">Event sources <a class="header-anchor" href="#event-sources" aria-label="Permalink to &quot;Event sources&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Source</th><th>When</th></tr></thead><tbody><tr><td><code>cursorAccount</code> + <code>serve --cursor-events</code></td><td>Preferred. Signed-in host (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>). Repos from the channel and from repeatable <code>--repo owner/name</code>. Cap 20, one GitHub owner</td></tr><tr><td>HTTP <code>POST /&lt;slug&gt;/v1/channels/github</code> with a webhook secret</td><td><code>allowAll()</code> + <code>X-Hub-Signature-256</code></td></tr><tr><td>HTTP, no secret</td><td>Loopback only. <code>serve --dev</code> also admits unsigned loopback (fixtures / forward)</td></tr></tbody></table><p><code>permissions</code>: <code>&quot;read&quot;</code> inspect; <code>&quot;pr-write&quot;</code> (default) comments / PR writes; <code>&quot;contents-write&quot;</code> push or merge-box checks. <code>progress.commitStatus</code> needs check-write; see the GitHub guide. Set <code>checks: true</code> when channel code posts its own Checks API runs through <code>ctx.github.createCheck</code>. The flag grants access. It does not post a check.</p><p>Without <code>cursorAccount</code>, outbound calls prefer App installation tokens (<code>GITHUB_APP_ID</code> + <code>GITHUB_APP_PRIVATE_KEY</code>). Local tests can use <code>GITHUB_TOKEN</code> / <code>gh auth login</code>.</p><p>The Cursor stream is metadata, not full webhook bodies. Re-read the PR from GitHub.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><ol><li><strong>Fixtures</strong> (offline, <code>--dev</code>, no signature):</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/channels/github</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;x-github-event: pull_request&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @fixtures/github/pull_request.synchronize.json</span></span></code></pre></div><ol start="2"><li><strong>Replay</strong> (hillclimb tier; pull access is enough):</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owner/repo#123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">projec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>

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

@@ -0,0 +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};