@cursor/july 0.1.107 → 0.1.109

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_deploy.md.CWqi_ZxW.js

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

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

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

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

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

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

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

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

@@ -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/otel.ts</code></td><td>OpenTelemetry (<code>defineOtel</code>)</td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron. Never auto-fire under <code>--dev</code></td></tr><tr><td><code>agent/sandbox/workspace/</code></td><td>Session seed files (local only)</td></tr><tr><td><code>agent/lib/</code></td><td>Import-only. Never discovered</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Case id is the path under <code>evals/</code></td></tr></tbody></table><h2 id="local-vs-cloud" tabindex="-1">Local vs cloud <a class="header-anchor" href="#local-vs-cloud" aria-label="Permalink to &quot;Local vs cloud&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (default) runs on the serve host. <code>runtime: &quot;cloud&quot;</code> needs <code>cloud: { repos: [...] }</code>.</p><table tabindex="0"><thead><tr><th>Capability</th><th>local</th><th>cloud</th></tr></thead><tbody><tr><td>Server tools</td><td>yes</td><td>yes on managed hosting; self-hosted needs <code>--public-url</code></td></tr><tr><td>Tool approvals</td><td>yes</td><td>no</td></tr><tr><td>Agent tools / skills</td><td>yes</td><td>yes</td></tr><tr><td>sandbox seeds</td><td>yes</td><td>no</td></tr><tr><td>Checkout</td><td>you arrange it</td><td>the VM carries it</td></tr></tbody></table><p>Use cloud when the job needs a checkout at scale. <code>validate</code> warns when cloud is combined with local-only capabilities.</p><h2 id="sessions" tabindex="-1">Sessions <a class="header-anchor" href="#sessions" aria-label="Permalink to &quot;Sessions&quot;">​</a></h2><ul><li><strong>continuationToken</strong> continues a conversation. HTTP follow-ups rotate it. Stale tokens return <code>409</code>.</li><li><strong>sessionId</strong> is the inspect handle (<code>GET /v1/session/:id/stream?startIndex=N</code>).</li></ul><p>A follow-up to a busy HTTP/MCP session interrupts the in-flight turn. Slack coalesces. Routes: <code>docs/reference/http-api.md</code>. Session files live under the project state directory (<code>--state-root</code>).</p><h2 id="where-logic-belongs" tabindex="-1">Where logic belongs <a class="header-anchor" href="#where-logic-belongs" aria-label="Permalink to &quot;Where logic belongs&quot;">​</a></h2><p>Code: side-effect gates, write dedupe, auth, evidence seeding, hard API caps. Model: formatting, summarizing, classification, replies. Budget: <code>skills/create-agent/SKILL.md</code>.</p><p>Loop: <code>validate</code> / <code>info</code> / <code>call</code> / <code>run</code> / <code>eval</code> / <code>serve</code>. Serve only this agent&#39;s directory.</p><table tabindex="0"><thead><tr><th>Task</th><th>Skill</th></tr></thead><tbody><tr><td>Scaffold</td><td><code>skills/create-agent/SKILL.md</code></td></tr><tr><td>Evals</td><td><code>skills/evals/SKILL.md</code></td></tr><tr><td>OpenTelemetry</td><td><code>skills/otel/SKILL.md</code></td></tr><tr><td>GitHub</td><td><code>skills/github/SKILL.md</code></td></tr><tr><td>Slack</td><td><code>skills/setup-slack/SKILL.md</code></td></tr><tr><td>Host MCP OAuth</td><td><code>skills/mcp-auth/SKILL.md</code></td></tr><tr><td>Managed deployment</td><td><code>skills/deploy/SKILL.md</code></td></tr><tr><td>Local triage</td><td><code>skills/debug/SKILL.md</code></td></tr><tr><td>Measured improvement</td><td><code>skills/hillclimb/SKILL.md</code></td></tr></tbody></table>',20)])])}const p=t(c,[["render",s]]);export{g as __pageData,p as default};

package/dist/docs/assets/{skills_framework-map.md.haibFyoB.lean.js → skills_framework-map.md.BxLSOhSY.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/skills_index.md.DL7EHaQ-.js

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

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

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

package/dist/docs/assets/{storage.md.BOHeqk2M.js → storage.md.BUrhJ-Zz.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage.","frontmatter":{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage."},"headers":[],"relativePath":"storage.md","filePath":"storage.md"}`),n={name:"storage.md"};function o(d,s,h,r,l,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="storage" tabindex="-1">Storage <a class="header-anchor" href="#storage" aria-label="Permalink to &quot;Storage&quot;">​</a></h1><p>The Agent SDK owns durable storage for sessions, continuation tokens, reminders, playground eval history, and live A/B samples. It chooses the keys, when to read and write, and how to restore after restart.</p><p>The Agent SDK owns key encoding. Backends must accept the keys they are given. Do not fail <code>put</code> to enforce a shorter cap.</p><p>By default that storage lives under <code>--state-root</code> on local disk. Fine for one machine; it does not survive replacing the host.</p><p>To keep the same framework storage across hosts, plug in a key-value backend with <code>agent/storage.ts</code>. You provide <code>put</code> / <code>get</code> / <code>delete</code> / <code>list</code>. The optional <code>cas</code> group adds conditional writes (see <a href="#conditional-writes-the-cas-group">Conditional writes</a>).</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts</span></span>
+import{_ as i,c as e,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage.","frontmatter":{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage."},"headers":[],"relativePath":"storage.md","filePath":"storage.md"}`),n={name:"storage.md"};function o(h,s,r,l,d,p){return t(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="storage" tabindex="-1">Storage <a class="header-anchor" href="#storage" aria-label="Permalink to &quot;Storage&quot;">​</a></h1><p>The Agent SDK owns durable storage for sessions, continuation tokens, reminders, and playground eval history. It chooses the keys, when to read and write, and how to restore after restart.</p><p>The Agent SDK owns key encoding. Backends must accept the keys they are given. Do not fail <code>put</code> to enforce a shorter cap.</p><p>By default that storage lives under <code>--state-root</code> on local disk. Fine for one machine; it does not survive replacing the host.</p><p>To keep the same framework storage across hosts, plug in a key-value backend with <code>agent/storage.ts</code>. You provide <code>put</code> / <code>get</code> / <code>delete</code> / <code>list</code>. The optional <code>cas</code> group adds conditional writes (see <a href="#conditional-writes-the-cas-group">Conditional writes</a>).</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage&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;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -12,7 +12,7 @@ import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    putIfVersion</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">key</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">value</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">expected</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> db.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">casUpdate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(key, value, expected),</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    listKeys</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> db.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">listKeysByPrefix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(prefix),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="which-fields-to-provide" tabindex="-1">Which fields to provide <a class="header-anchor" href="#which-fields-to-provide" aria-label="Permalink to &quot;Which fields to provide&quot;">​</a></h2><p>Implement the small KV core (<code>put</code>/<code>get</code>/<code>delete</code>/<code>list</code> plus the <code>cas</code> group) and you get <strong>full functionality</strong>: eval-run and A/B history are derived over the core automatically. The dedicated <code>evals</code> / <code>abs</code> groups are backend-native optimizations, not required-or-lose-history hooks.</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>put</code></td><td>Yes</td><td>Write or update a value</td></tr><tr><td><code>cas</code></td><td>Optional</td><td>Conditional writes; see <a href="#conditional-writes-the-cas-group">Conditional writes</a></td></tr><tr><td><code>get</code></td><td>For restore</td><td>Look up one key</td></tr><tr><td><code>list</code></td><td>For restore</td><td>Return entries under a prefix, in key order</td></tr><tr><td><code>delete</code></td><td>For cleanup</td><td>Remove a key</td></tr><tr><td><code>name</code></td><td>No</td><td>Label surfaced on <code>GET /v1/info</code> diagnostics</td></tr><tr><td><code>policy</code></td><td>No</td><td>Timing knobs; see <a href="#policy">Policy</a></td></tr><tr><td><code>evals</code></td><td>No</td><td>Backend-native eval-runs table; derived over the core when omitted. See <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr><tr><td><code>abs</code></td><td>No</td><td>Backend-native A/B metrics table; derived over the core when omitted. See <a href="#eval-and-a-b-tables">Eval and A/B tables</a></td></tr></tbody></table><p>A throwing <code>put</code> is logged and dropped. It never fails a turn. When resolving a missing continuation token, a throwing <code>get</code> fails the follow-up so a store outage does not open a new session. Return <code>undefined</code> only for a real miss.</p><h2 id="eval-and-a-b-tables" tabindex="-1">Eval and A/B tables <a class="header-anchor" href="#eval-and-a-b-tables" aria-label="Permalink to &quot;Eval and A/B tables&quot;">​</a></h2><p>Two dedicated table groups carry structured rows instead of opaque KV values. Both are <strong>optional optimizations</strong>: when a group is not authored, <code>defineStorage</code> derives it over the KV core, so a backend that implements only the core loses nothing. Author a group only when the backend has a better native shape (a real database table, an analytics pipeline). The built-in <code>fileKv</code> and <code>cursorHostedStorage</code> both do.</p><p><code>evals</code> keeps playground eval batches across restarts (<code>put</code>, <code>delete</code>, <code>list</code> over run snapshots keyed by <code>runId</code>). A core missing <code>delete</code> or <code>list</code> leaves eval history in memory until restart. See <a href="./evals.html#configure-eval-runs">Evals</a>.</p><p><code>abs</code> exports live A/B metrics: <code>putSample</code> appends one cumulative metric sample per enrolled experiment on each completed or failed turn; optional <code>putSnapshot</code> / <code>getSnapshot</code> store and serve back the latest aggregate so a replacement host can still serve the A/Bs surface. <code>putSample</code> and <code>putSnapshot</code> need only core <code>put</code>; <code>getSnapshot</code> needs core <code>get</code>. Session event logs remain the assignment source of truth either way. See <a href="./ab.html">Live A/B metrics</a>.</p><h2 id="policy" tabindex="-1">Policy <a class="header-anchor" href="#policy" aria-label="Permalink to &quot;Policy&quot;">​</a></h2><p>Two knobs change behavior:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</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><h2 id="which-fields-to-provide" tabindex="-1">Which fields to provide <a class="header-anchor" href="#which-fields-to-provide" aria-label="Permalink to &quot;Which fields to provide&quot;">​</a></h2><p>Implement the small KV core (<code>put</code>/<code>get</code>/<code>delete</code>/<code>list</code> plus the <code>cas</code> group) and you get <strong>full functionality</strong>: eval-run history is derived over the core automatically. The dedicated <code>evals</code> group is a backend-native optimization, not a required-or-lose-history hook.</p><table tabindex="0"><thead><tr><th>Field</th><th>Required</th><th>Role</th></tr></thead><tbody><tr><td><code>put</code></td><td>Yes</td><td>Write or update a value</td></tr><tr><td><code>cas</code></td><td>Optional</td><td>Conditional writes; see <a href="#conditional-writes-the-cas-group">Conditional writes</a></td></tr><tr><td><code>get</code></td><td>For restore</td><td>Look up one key</td></tr><tr><td><code>list</code></td><td>For restore</td><td>Return entries under a prefix, in key order</td></tr><tr><td><code>delete</code></td><td>For cleanup</td><td>Remove a key</td></tr><tr><td><code>name</code></td><td>No</td><td>Label surfaced on <code>GET /v1/info</code> diagnostics</td></tr><tr><td><code>policy</code></td><td>No</td><td>Timing knobs; see <a href="#policy">Policy</a></td></tr><tr><td><code>evals</code></td><td>No</td><td>Backend-native eval-runs table; derived over the core when omitted. See <a href="#eval-table">Eval table</a></td></tr></tbody></table><p>A throwing <code>put</code> is logged and dropped. It never fails a turn. When resolving a missing continuation token, a throwing <code>get</code> fails the follow-up so a store outage does not open a new session. Return <code>undefined</code> only for a real miss.</p><h2 id="eval-table" tabindex="-1">Eval table <a class="header-anchor" href="#eval-table" aria-label="Permalink to &quot;Eval table&quot;">​</a></h2><p>The dedicated <code>evals</code> table group carries structured rows instead of opaque KV values. It is an <strong>optional optimization</strong>: when the group is not authored, <code>defineStorage</code> derives it over the KV core, so a backend that implements only the core loses nothing. Author the group only when the backend has a better native shape (a real database table, an analytics pipeline). The built-in <code>fileKv</code> and <code>cursorHostedStorage</code> both do.</p><p><code>evals</code> keeps playground eval batches across restarts (<code>put</code>, <code>delete</code>, <code>list</code> over run snapshots keyed by <code>runId</code>). A core missing <code>delete</code> or <code>list</code> leaves eval history in memory until restart. See <a href="./evals.html#configure-eval-runs">Evals</a>.</p><h2 id="policy" tabindex="-1">Policy <a class="header-anchor" href="#policy" aria-label="Permalink to &quot;Policy&quot;">​</a></h2><p>Two knobs change behavior:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: {</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // Batch event writes while the session is busy (default: once per turn)</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    debounceMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">30_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -20,11 +20,11 @@ import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    restore: { maxSessions: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">500</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // put / get / delete / list …</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Knob</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>debounceMs</code></td><td>unset (once per turn)</td><td>Wait this long after activity before writing event batches</td></tr><tr><td><code>restore</code></td><td>caps below</td><td>How much to load at serve start</td></tr><tr><td><code>restore.maxSessions</code></td><td><code>1000</code></td><td>Max sessions loaded at serve start</td></tr><tr><td><code>restore.maxAgeMs</code></td><td>30 days</td><td>Skip older sessions at serve start</td></tr><tr><td><code>restore.maxTotalBytes</code></td><td>1 GiB</td><td>Stop loading once this budget is reached</td></tr></tbody></table><p>Set <code>restore: &quot;off&quot;</code> on high-traffic hosts. Sessions then load when a follow-up arrives instead of at startup.</p><h2 id="restore-after-restart" tabindex="-1">Restore after restart <a class="header-anchor" href="#restore-after-restart" aria-label="Permalink to &quot;Restore after restart&quot;">​</a></h2><p>With <code>get</code> and <code>list</code>, serve can rebuild local state from your store:</p><ul><li>At startup, the Agent SDK loads recent sessions up to the restore caps.</li><li>On demand, a missing continuation token resolves through the store and resumes that session.</li><li>Playground eval history and A/B aggregates can load from the same sink.</li></ul><p>A turn in flight at crash time is not replayed. The next follow-up resumes from the last flushed state.</p><h2 id="author-kv-ctx-host-kv" tabindex="-1">Author KV (<code>ctx.host.kv</code>) <a class="header-anchor" href="#author-kv-ctx-host-kv" aria-label="Permalink to &quot;Author KV (\`ctx.host.kv\`)&quot;">​</a></h2><p>Handlers can store their own JSON under the same sink without minting framework keys:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">put</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { updated: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Knob</th><th>Default</th><th>Meaning</th></tr></thead><tbody><tr><td><code>debounceMs</code></td><td>unset (once per turn)</td><td>Wait this long after activity before writing event batches</td></tr><tr><td><code>restore</code></td><td>caps below</td><td>How much to load at serve start</td></tr><tr><td><code>restore.maxSessions</code></td><td><code>1000</code></td><td>Max sessions loaded at serve start</td></tr><tr><td><code>restore.maxAgeMs</code></td><td>30 days</td><td>Skip older sessions at serve start</td></tr><tr><td><code>restore.maxTotalBytes</code></td><td>1 GiB</td><td>Stop loading once this budget is reached</td></tr></tbody></table><p>Set <code>restore: &quot;off&quot;</code> on high-traffic hosts. Sessions then load when a follow-up arrives instead of at startup.</p><h2 id="restore-after-restart" tabindex="-1">Restore after restart <a class="header-anchor" href="#restore-after-restart" aria-label="Permalink to &quot;Restore after restart&quot;">​</a></h2><p>With <code>get</code> and <code>list</code>, serve can rebuild local state from your store:</p><ul><li>At startup, the Agent SDK loads recent sessions up to the restore caps.</li><li>On demand, a missing continuation token resolves through the store and resumes that session.</li><li>Playground eval history can load from the same sink.</li></ul><p>A turn in flight at crash time is not replayed. The next follow-up resumes from the last flushed state.</p><h2 id="author-kv-ctx-host-kv" tabindex="-1">Author KV (<code>ctx.host.kv</code>) <a class="header-anchor" href="#author-kv-ctx-host-kv" aria-label="Permalink to &quot;Author KV (\`ctx.host.kv\`)&quot;">​</a></h2><p>Handlers can store their own JSON under the same sink without minting framework keys:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">put</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { updated: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prior</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.kv.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;alert-memory/abc&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Writes <strong>await</strong> the sink and propagate errors, unlike session mirrors, which are at-most-once.</p><p>Without <code>agent/storage.ts</code>, <code>host.kv</code> is local-only and does not survive replacing the host. Hosted agents should author <code>cursorHostedStorage()</code> so session and <code>host.kv</code> records survive replace.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/storage.ts: Cursor-managed hosting</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorHostedStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/storage/cursor-hosted&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;"> defineStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  ...</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cursorHostedStorage</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>Built-in helpers:</p><table tabindex="0"><thead><tr><th>Import</th><th>Backend</th></tr></thead><tbody><tr><td><code>@cursor/july/storage/file-kv</code></td><td>File-per-key under the project state directory</td></tr><tr><td><code>@cursor/july/storage/cursor-hosted</code></td><td>Cursor-managed hosting; records survive replace</td></tr></tbody></table><h2 id="bring-your-own-backend" tabindex="-1">Bring your own backend <a class="header-anchor" href="#bring-your-own-backend" aria-label="Permalink to &quot;Bring your own backend&quot;">​</a></h2><p>Any durable store works if it can put, get, delete, list by prefix, and optionally compare-and-set. Implement the <code>StorageConfig</code> methods (and the optional <code>cas</code> group) against that store. The contract, defined at <code>@cursor/july/kv</code>: version tokens are opaque strings that change on every successful write, including plain <code>put</code>, so a stale token fences instead of clobbering; conditional writes are atomic; <code>listKeys</code> returns every key under the prefix.</p><h2 id="conditional-writes-the-cas-group" tabindex="-1">Conditional writes (the <code>cas</code> group) <a class="header-anchor" href="#conditional-writes-the-cas-group" aria-label="Permalink to &quot;Conditional writes (the \`cas\` group)&quot;">​</a></h2><p>The <code>cas</code> group is compare-and-swap over the same keyspace: <code>getWithVersion</code> / <code>putIfAbsent</code> / <code>putIfVersion</code> / <code>listKeys</code>, defined backend-agnostically at <code>@cursor/july/kv</code>. Plain storage works without it, so an existing backend keeps working across a platform upgrade. <code>defineStorage</code> rejects a partial group. Implement all four methods or none. Version tokens are opaque strings that must change on every write (a counter column, a row version, a content hash). The built-in backends both include the group.</p>`,35)])])}const g=e(n,[["render",o]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Built-in helpers:</p><table tabindex="0"><thead><tr><th>Import</th><th>Backend</th></tr></thead><tbody><tr><td><code>@cursor/july/storage/file-kv</code></td><td>File-per-key under the project state directory</td></tr><tr><td><code>@cursor/july/storage/cursor-hosted</code></td><td>Cursor-managed hosting; records survive replace</td></tr></tbody></table><h2 id="bring-your-own-backend" tabindex="-1">Bring your own backend <a class="header-anchor" href="#bring-your-own-backend" aria-label="Permalink to &quot;Bring your own backend&quot;">​</a></h2><p>Any durable store works if it can put, get, delete, list by prefix, and optionally compare-and-set. Implement the <code>StorageConfig</code> methods (and the optional <code>cas</code> group) against that store. The contract, defined at <code>@cursor/july/kv</code>: version tokens are opaque strings that change on every successful write, including plain <code>put</code>, so a stale token fences instead of clobbering; conditional writes are atomic; <code>listKeys</code> returns every key under the prefix.</p><h2 id="conditional-writes-the-cas-group" tabindex="-1">Conditional writes (the <code>cas</code> group) <a class="header-anchor" href="#conditional-writes-the-cas-group" aria-label="Permalink to &quot;Conditional writes (the \`cas\` group)&quot;">​</a></h2><p>The <code>cas</code> group is compare-and-swap over the same keyspace: <code>getWithVersion</code> / <code>putIfAbsent</code> / <code>putIfVersion</code> / <code>listKeys</code>, defined backend-agnostically at <code>@cursor/july/kv</code>. Plain storage works without it, so an existing backend keeps working across a platform upgrade. <code>defineStorage</code> rejects a partial group. Implement all four methods or none. Version tokens are opaque strings that must change on every write (a counter column, a row version, a content hash). The built-in backends both include the group.</p>`,34)])])}const g=i(n,[["render",o]]);export{c as __pageData,g as default};

package/dist/docs/assets/{storage.md.BOHeqk2M.lean.js → storage.md.BUrhJ-Zz.lean.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage.","frontmatter":{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage."},"headers":[],"relativePath":"storage.md","filePath":"storage.md"}`),n={name:"storage.md"};function o(d,s,h,r,l,p){return t(),i("div",null,[...s[0]||(s[0]=[a("",35)])])}const g=e(n,[["render",o]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as t,ag as a}from"./chunks/framework.BCISBCiQ.js";const c=JSON.parse(`{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage.","frontmatter":{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage."},"headers":[],"relativePath":"storage.md","filePath":"storage.md"}`),n={name:"storage.md"};function o(h,s,r,l,d,p){return t(),e("div",null,[...s[0]||(s[0]=[a("",34)])])}const g=i(n,[["render",o]]);export{c as __pageData,g as default};

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};