@cursor/july 0.1.42 → 0.1.45

package/dist/docs/assets/{reference_agent-config.md.CRmkoxd6.js → reference_agent-config.md.XRpxctsA.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(d,s,l,r,h,c){return a(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (\`agent/agent.ts\`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root agent.</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as e,c as t,o as i,ag as a}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (\`agent/agent.ts\`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root agent.</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  model: {</span></span>
@@ -13,13 +13,18 @@ import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  //   repos: [{ url: &quot;https://github.com/org/repo&quot;, startingRef: &quot;main&quot; }],</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // },</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // local: { cwd: &quot;../harness&quot; },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="fields-on-defineagent" tabindex="-1">Fields on <code>defineAgent</code> <a class="header-anchor" href="#fields-on-defineagent" aria-label="Permalink to &quot;Fields on \`defineAgent\`&quot;">​</a></h2><p><code>defineAgent</code> accepts these fields.</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>runtime</code></td><td><code>&quot;local&quot;</code> or <code>&quot;cloud&quot;</code></td><td>Where turns execute. Default <code>&quot;local&quot;</code>.</td></tr><tr><td><code>cloud</code></td><td>object</td><td>Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when <code>runtime</code> is <code>&quot;cloud&quot;</code>, and as the base merged under per-session <code>cloud</code> send options.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults; ignored for cloud turns. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames? }</code></td><td>Managed-hosting declarations read by <code>agent-sdk deploy</code>: the pod&#39;s egress allowlist and the secret names the agent expects. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Engine-wide turn admission limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr></tbody></table><h2 id="choose-a-model" tabindex="-1">Choose a model <a class="header-anchor" href="#choose-a-model" aria-label="Permalink to &quot;Choose a model&quot;">​</a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. The SDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</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:#6F42C1;--shiki-dark:#B392F0;">model</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="fields-on-defineagent" tabindex="-1">Fields on <code>defineAgent</code> <a class="header-anchor" href="#fields-on-defineagent" aria-label="Permalink to &quot;Fields on \`defineAgent\`&quot;">​</a></h2><p><code>defineAgent</code> accepts these fields.</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>runtime</code></td><td><code>&quot;local&quot;</code> or <code>&quot;cloud&quot;</code></td><td>Where turns execute. Default <code>&quot;local&quot;</code>.</td></tr><tr><td><code>cloud</code></td><td>object</td><td>Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when <code>runtime</code> is <code>&quot;cloud&quot;</code>, and as the base merged under per-session <code>cloud</code> send options.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults; ignored for cloud turns. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames? }</code></td><td>Managed-hosting declarations read by <code>agent-sdk deploy</code>: the pod&#39;s egress allowlist and the secret names the agent expects. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Engine-wide turn admission limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr><tr><td><code>tools</code></td><td><code>ToolName[]</code></td><td>Allowlist of built-in harness tools offered to the model. Unset = the model&#39;s full standard toolset. See <a href="#allowlist-built-in-harness-tools">Allowlist built-in harness tools</a>.</td></tr></tbody></table><h2 id="choose-a-model" tabindex="-1">Choose a model <a class="header-anchor" href="#choose-a-model" aria-label="Permalink to &quot;Choose a model&quot;">​</a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. The SDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</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:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grok-4.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  params</span><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;effort&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;high&quot;</span><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;fast&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;true&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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A plain string works when you don&#39;t need params:</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:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="choose-a-runtime" tabindex="-1">Choose a runtime <a class="header-anchor" href="#choose-a-runtime" aria-label="Permalink to &quot;Choose a runtime&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (the default) runs turns on the Cursor SDK harness on this machine. The session id doubles as the SDK agent id, and server tools, skills, sandbox seeds, and tool approvals all apply.</p><p><code>runtime: &quot;cloud&quot;</code> runs turns on Cursor cloud agents (<code>bc-…</code> ids). Pass a <code>cloud</code> block with the repos the VM carries. Server tools stay reachable over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set (omitted with a warning otherwise), and instructions and agent-tool catalogs are prepended to the first prompt, because the local session workspace is not the cloud VM.</p><p><code>validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with agent tools, skills, or sandbox seeds, which only materialize into local session workspaces, and when the <code>cloud</code> block is missing. The full capability matrix and the patterns that hold up are in the <a href="./../guides/cloud-runtime.html">Cloud runtime guide</a>.</p><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to &quot;Local options&quot;">​</a></h2><p><code>local</code> sets local-harness defaults, all ignored for cloud turns.</p><p><code>local.workspaceDir</code> points every session at one shared harness cwd, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> still wins over both. The SDK keys its local executor (rules, skills, MCP, ignore mappings) on the harness cwd, so a shared directory resolves the workspace once per serve process instead of once per session. The trade: sessions share a working tree, so a file one turn writes is visible to the next.</p><p><code>local.sandbox</code> runs the harness inside Cursor&#39;s local sandbox. It&#39;s off by default, matching the SDK: shell then auto-approves and inherits the serve process environment, including any credentials the host holds. Turn it on for agents whose turns read untrusted input (webhook payloads, PR diffs, inbound chat); it&#39;s a real tool boundary rather than a prompt-level one.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;">​</a></h3><p><code>local.cwd</code> sets the default parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> (absolute, or relative to the project root) unless a per-send <code>workspaceDir</code> overrides it.</p><p>This is your control over ambient context. Session workspaces are real Cursor project directories, so the harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent inside a big monorepo that must not inherit the monorepo&#39;s rules points <code>cwd</code> outside it (or runs with <code>--state-root</code> under <code>/tmp</code>). An agent that <em>needs</em> a specific checkout&#39;s skills and rules points <code>cwd</code> inside that checkout.</p><h2 id="the-cloud-block" tabindex="-1">The <code>cloud</code> block <a class="header-anchor" href="#the-cloud-block" aria-label="Permalink to &quot;The \`cloud\` block&quot;">​</a></h2><p>Cloud agent defaults forwarded to the Cursor SDK: <code>repos</code> (each <code>{ url, startingRef? }</code>), environment selection, <code>envVars</code>, and the rest. A local agent uses the same block as the base config when a channel opens a cloud-attached session per send. That hybrid pattern is covered in <a href="./../guides/cloud-runtime.html#hybrid-local-agent-cloud-sessions">Cloud runtime</a>.</p><h2 id="concurrency" tabindex="-1">Concurrency <a class="header-anchor" href="#concurrency" aria-label="Permalink to &quot;Concurrency&quot;">​</a></h2><p><code>concurrency.maxRunningTurns</code> caps how many model turns run at once across all of the agent&#39;s sessions (positive integer, hard cap 200). When every slot is busy, newly admitted turns queue FIFO instead of failing: the stream records a durable <code>turn.queued</code> event with the queue position, <code>GET /v1/sessions</code> reports <code>queued: true</code>, and each queued turn starts as soon as a slot frees. A queued turn still counts as running for busy semantics: follow-ups preempt it, and direct tool calls get <code>409 session_busy</code>. Omit for unlimited.</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;"> defineAgent</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>A plain string works when you don&#39;t need params:</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:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="choose-a-runtime" tabindex="-1">Choose a runtime <a class="header-anchor" href="#choose-a-runtime" aria-label="Permalink to &quot;Choose a runtime&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (the default) runs turns on the Cursor SDK harness on this machine. The session id doubles as the SDK agent id, and server tools, skills, sandbox seeds, and tool approvals all apply.</p><p><code>runtime: &quot;cloud&quot;</code> runs turns on Cursor cloud agents (<code>bc-…</code> ids). Pass a <code>cloud</code> block with the repos the VM carries. Server tools stay reachable over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set (omitted with a warning otherwise), and instructions and agent-tool catalogs are prepended to the first prompt, because the local session workspace is not the cloud VM.</p><p><code>validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with agent tools, skills, or sandbox seeds, which only materialize into local session workspaces, and when the <code>cloud</code> block is missing. The full capability matrix and the patterns that hold up are in the <a href="./../guides/cloud-runtime.html">Cloud runtime guide</a>.</p><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to &quot;Local options&quot;">​</a></h2><p><code>local</code> sets local-harness defaults, all ignored for cloud turns.</p><p><code>local.workspaceDir</code> points every session at one shared harness cwd, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> still wins over both. The SDK keys its local executor (rules, skills, MCP, ignore mappings) on the harness cwd, so a shared directory resolves the workspace once per serve process instead of once per session. The trade: sessions share a working tree, so a file one turn writes is visible to the next.</p><p><code>local.sandbox</code> runs the harness inside Cursor&#39;s local sandbox. It&#39;s off by default, matching the SDK: shell then auto-approves and inherits the serve process environment, including any credentials the host holds. Turn it on for agents whose turns read untrusted input (webhook payloads, PR diffs, inbound chat); it&#39;s a real tool boundary rather than a prompt-level one.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;">​</a></h3><p><code>local.cwd</code> sets the default parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> (absolute, or relative to the project root) unless a per-send <code>workspaceDir</code> overrides it.</p><p>This is your control over ambient context. Session workspaces are real Cursor project directories, so the harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent inside a big monorepo that must not inherit the monorepo&#39;s rules points <code>cwd</code> outside it (or runs with <code>--state-root</code> under <code>/tmp</code>). An agent that <em>needs</em> a specific checkout&#39;s skills and rules points <code>cwd</code> inside that checkout.</p><h2 id="allowlist-built-in-harness-tools" tabindex="-1">Allowlist built-in harness tools <a class="header-anchor" href="#allowlist-built-in-harness-tools" aria-label="Permalink to &quot;Allowlist built-in harness tools&quot;">​</a></h2><p><code>tools</code> names which of the Cursor harness&#39;s built-in tools the model is offered, riding the SDK&#39;s <code>AgentOptions.tools</code>. It is opt-in by design: unset keeps the model&#39;s full standard toolset, and once set the agent gets exactly what it names — nothing more. <code>[]</code> removes every native built-in tool. There is deliberately no exclusion form: an agent that restricts tools states what it keeps, so tools the platform adds later stay off until someone opts in.</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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Read-only triage agent: search and read only.</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // No shell, no edits, no subagents.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;glob&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ls&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><p>One name is injected for you: <strong><code>&quot;mcp&quot;</code> is always granted alongside a configured allowlist</strong>. It is transport, not capability — this kit&#39;s authored server tools reach the model over the SDK custom-tool MCP path, so omitting it would silently strand <code>agent/tools/</code>. What MCP actually exposes stays governed by the second layer: the tools you author, the connections you declare, and the harness cwd&#39;s ambient <code>.cursor</code> config. An agent that must not see a checkout&#39;s MCP servers points <code>local.cwd</code> outside it (see <a href="#local-cwd">Local cwd</a>), and <code>local.sandbox</code> makes MCP tool calls fail closed.</p><p>The other names use the SDK&#39;s public tool vocabulary (<code>&quot;shell&quot;</code>, <code>&quot;read&quot;</code>, <code>&quot;edit&quot;</code>, <code>&quot;grep&quot;</code>, <code>&quot;glob&quot;</code>, <code>&quot;ls&quot;</code>, <code>&quot;task&quot;</code>, ...); unknown names fail the turn with a <code>ConfigurationError</code>. Two deserve care: <code>&quot;shell&quot;</code> is a capability group that also grants shell stdin writes — and is what <code>execution: &quot;agent&quot;</code> tool scripts run through, so an allowlist without it strands them (discovery warns about that combination). <code>&quot;task&quot;</code> gates subagents (which otherwise keep their own curated toolsets).</p><p>The allowlist states runtime-agnostic intent, but the SDK cannot enforce tool restrictions on cloud agents yet — and a restriction must never silently not apply. A <code>runtime: &quot;cloud&quot;</code> agent that sets <code>tools</code> fails at serve start with an error diagnostic, and a hybrid agent&#39;s per-send cloud sessions are refused (the turn errors) rather than run unrestricted. When the SDK lifts the limitation, the same field will simply start applying to cloud turns.</p><p>Not a security boundary against the serve host: like <code>local.sandbox</code>, the allowlist only shapes what the model can call; pair with <code>sandbox: true</code> when the concern is untrusted input steering the model.</p><h2 id="the-cloud-block" tabindex="-1">The <code>cloud</code> block <a class="header-anchor" href="#the-cloud-block" aria-label="Permalink to &quot;The \`cloud\` block&quot;">​</a></h2><p>Cloud agent defaults forwarded to the Cursor SDK: <code>repos</code> (each <code>{ url, startingRef? }</code>), environment selection, <code>envVars</code>, and the rest. A local agent uses the same block as the base config when a channel opens a cloud-attached session per send. That hybrid pattern is covered in <a href="./../guides/cloud-runtime.html#hybrid-local-agent-cloud-sessions">Cloud runtime</a>.</p><h2 id="concurrency" tabindex="-1">Concurrency <a class="header-anchor" href="#concurrency" aria-label="Permalink to &quot;Concurrency&quot;">​</a></h2><p><code>concurrency.maxRunningTurns</code> caps how many model turns run at once across all of the agent&#39;s sessions (positive integer, hard cap 200). When every slot is busy, newly admitted turns queue FIFO instead of failing: the stream records a durable <code>turn.queued</code> event with the queue position, <code>GET /v1/sessions</code> reports <code>queued: true</code>, and each queued turn starts as soon as a slot frees. A queued turn still counts as running for busy semantics: follow-ups preempt it, and direct tool calls get <code>409 session_busy</code>. Omit for unlimited.</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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  concurrency: { maxRunningTurns: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</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="built-in-tools" tabindex="-1">Built-in tools <a class="header-anchor" href="#built-in-tools" aria-label="Permalink to &quot;Built-in tools&quot;">​</a></h2><p><code>builtinTools</code> opts into framework-provided model-facing tools. Each enabled capability materializes as ordinary server tools at discovery time, so turns, direct calls, <code>info</code>, and the playground treat them like authored tools. Authored tools with the same name win, with a warning, and like all server tools they run on the local runtime.</p><p><code>builtinTools: { reminders: true }</code> adds three tools bound to the current conversation over <code>host.reminders</code>: <code>reminders_create</code>, <code>reminders_list</code>, and <code>reminders_cancel</code>. Sessions without a continuation key can&#39;t arm reminders. See <a href="./schedules.html#reminders">Schedules and reminders</a>.</p><h2 id="generate-instructions" tabindex="-1">Generate instructions <a class="header-anchor" href="#generate-instructions" aria-label="Permalink to &quot;Generate instructions&quot;">​</a></h2><p>When the system prompt must be computed, author <code>agent/instructions.ts</code> instead of markdown:</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineInstructions } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
@@ -33,4 +38,4 @@ import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`listening on \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">handle</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</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:#6A737D;--shiki-dark:#6A737D;">// handle.callTool(...), handle.dispatchSchedule(&quot;heartbeat&quot;),</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.project, await handle.close()</span></span></code></pre></div><p><code>ServeOptions</code> mirrors the CLI flags: <code>port</code>, <code>host</code>, <code>dev</code>, <code>stateRoot</code>, <code>apiKey</code>, <code>schedules</code>, <code>reminders</code>, <code>noControlPlane</code>, <code>playground</code>, <code>docs</code>, <code>authToken</code> (the <code>--bearer-token</code> equivalent), <code>allowAnonymous</code>, <code>allowAnonymousCursorGithub</code>, <code>allowAnonymousCursorAccountMcp</code>, <code>cursorGithubProxy</code>, <code>publicUrl</code>, <code>cloudToolsUrl</code>, <code>cursorEvents</code>, and <code>logger</code>. <code>serve()</code> additionally accepts <code>discovery</code> (project-loading options) and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. The Cursor credential resolves in one order everywhere: explicit <code>apiKey</code>, then <code>CURSOR_API_KEY</code>, then the key stored by <code>agent-sdk login</code>.</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><p>Continue with these pages:</p><ul><li><a href="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./../guides/cloud-runtime.html">Cloud runtime</a>: when and how to leave the host</li><li><a href="./cli.html">CLI</a>: the flags <code>ServeOptions</code> mirrors</li></ul>`,41)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.project, await handle.close()</span></span></code></pre></div><p><code>ServeOptions</code> mirrors the CLI flags: <code>port</code>, <code>host</code>, <code>dev</code>, <code>stateRoot</code>, <code>apiKey</code>, <code>schedules</code>, <code>reminders</code>, <code>noControlPlane</code>, <code>playground</code>, <code>docs</code>, <code>authToken</code> (the <code>--bearer-token</code> equivalent), <code>allowAnonymous</code>, <code>allowAnonymousCursorGithub</code>, <code>allowAnonymousCursorAccountMcp</code>, <code>cursorGithubProxy</code>, <code>publicUrl</code>, <code>cloudToolsUrl</code>, <code>cursorEvents</code>, and <code>logger</code>. <code>serve()</code> additionally accepts <code>discovery</code> (project-loading options) and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. The Cursor credential resolves in one order everywhere: explicit <code>apiKey</code>, then <code>CURSOR_API_KEY</code>, then the key stored by <code>agent-sdk login</code>.</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><p>Continue with these pages:</p><ul><li><a href="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./../guides/cloud-runtime.html">Cloud runtime</a>: when and how to leave the host</li><li><a href="./cli.html">CLI</a>: the flags <code>ServeOptions</code> mirrors</li></ul>`,48)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_agent-config.md.CRmkoxd6.lean.js → reference_agent-config.md.XRpxctsA.lean.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(d,s,l,r,h,c){return a(),i("div",null,[...s[0]||(s[0]=[t("",41)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as e,c as t,o as i,ag as a}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,r,h,c){return i(),t("div",null,[...s[0]||(s[0]=[a("",48)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_channels.md.BIabFUAI.js → reference_channels.md.MN8iDy8V.js}

@@ -50,4 +50,4 @@ import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k
 <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:#6A737D;--shiki-dark:#6A737D;">  // auth: [...], state: {...}, onStart(...), onStop(...)</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This example assumes <code>agent/tools/inspect_pr.ts</code> exists. The handler calls it before the model turn, so every review starts with validated PR data. It also derives a stable conversation key from the PR URL and writes the tool result to <code>pr.json</code>. Instructions can ask the model to inspect a PR, but host code guarantees it.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p><code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, and <code>DELETE</code> helpers build routes. Their schemas are Zod, enforced at compile time:</p><table tabindex="0"><thead><tr><th>Verb</th><th>Required schema</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>querySchema</code></td></tr><tr><td><code>POST</code> / <code>PUT</code> / <code>PATCH</code></td><td><code>bodySchema</code> (optional <code>querySchema</code>)</td></tr><tr><td><code>DELETE</code></td><td>both optional</td></tr></tbody></table><p>Plain JSON Schema objects won&#39;t type-check; use <code>z.object({})</code> or <code>z.unknown()</code> for intentionally open surfaces. The host validates before the handler runs. Handlers receive typed <code>args.body</code> and <code>args.query</code>, and empty POST bodies are coerced to <code>{}</code> first. Declared schemas are projected on <code>GET /v1/info</code>, which powers the playground&#39;s <strong>Try</strong> buttons and composer <strong>slash commands</strong>.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>Handlers receive the Fetch <code>Request</code> and an args object:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Run a model turn on this channel; returns the session handle (options below)</td></tr><tr><td><code>getSession(sessionId)</code></td><td>Look up an existing session on this channel</td></tr><tr><td><code>receive(channelDefinition, input)</code></td><td>Hand off to another channel (schedules use this)</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td>Deterministic server-tool call (<a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>)</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated payloads and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> resolved by this route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address</td></tr><tr><td><code>host</code></td><td>Shared services: <code>host.mcp</code>, <code>host.github</code>, <code>host.slack</code>, <code>host.kv</code>, <code>host.files</code>, <code>host.reminders</code></td></tr><tr><td><code>waitUntil(promise)</code></td><td>Background work that outlives the response</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Absolute playground + trace URLs for a session on this mount</td></tr><tr><td><code>artifacts</code></td><td>Unbound <a href="./artifacts.html">artifacts</a> facade; pass <code>sessionId</code> in <code>tag</code> input to attribute one</td></tr></tbody></table><p><code>send</code> options: <code>continuationToken</code> (the conversation key), <code>admission</code> (<code>&quot;preempt&quot;</code> interrupts a busy session, the default; <code>&quot;coalesce&quot;</code> enqueues behind the running turn, the <a href="./sessions.html#what-happens-when-i-send-a-follow-up">Slack policy</a>), <code>workspaceFiles</code>, <code>workspaceDir</code>, <code>cloud</code> (attach cloud repos for this session), <code>auth</code> (defaults to the request principal), <code>sdkAgentId</code> (resume a specific SDK agent), <code>state</code> (starting channel state for new sessions), <code>title</code> (session display title), <code>purpose</code> (<code>&quot;eval&quot;</code> skips sticky A/B enrollment), and <code>coalesceSourceTs</code> (dedupe key for coalesce queue items already delivered mid-turn).</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Keys are event types from the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>, or <code>&quot;*&quot;</code>. Handlers receive <code>(event, channel, ctx)</code>, where <code>channel.state</code> is the per-session adapter state and <code>ctx</code> exposes session info and host services. This is where a channel delivers replies back to its surface.</p><h2 id="state-and-lifecycle" tabindex="-1">State and lifecycle <a class="header-anchor" href="#state-and-lifecycle" aria-label="Permalink to &quot;State and lifecycle&quot;">​</a></h2><p><code>state</code> declares the starting per-session adapter state (JSON), persisted on the session record. Routes and event handlers read and mutate it through <code>channel.state</code>. <code>onStart(args)</code> runs when the channel mounts; the Slack pack opens its Socket Mode connection here. <code>onStop()</code> runs when the server drains.</p><p><code>onStart</code> receives the route helpers (<code>send</code>, <code>getSession</code>, <code>receive</code>, <code>callTool</code>, <code>host</code>, <code>waitUntil</code>, <code>artifacts</code>, and a <code>logger</code> that respects the server&#39;s log sink) plus a set that exists for long-lived transports:</p><ul><li><code>emitAssistantMessage(sessionId, text)</code> appends an assistant message without a model turn, for host tasks that already produced the final text.</li><li><code>hasContinuationSession(token)</code> and <code>isContinuationBusy(token)</code> report whether a continuation token has a live session and whether a turn is in flight on it.</li><li><code>getContinuationLastBotMessageTs(token)</code> reads the Slack warm-delta watermark from channel state.</li><li><code>interruptContinuation(token)</code> stops the in-flight turn and clears coalesced follow-ups queued behind it.</li><li><code>resolveApproval(sessionId, callId, decision, auth, options?)</code> approves or denies a parked tool call, how Slack Block Kit buttons unblock a turn without the HTTP approvals route.</li></ul><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs an auth-policy chain: the channel&#39;s <code>auth</code> array, or <code>[localDevStrict()]</code> when unset. A policy is a function <code>(request, info) =&gt; AuthContext | null</code> (async allowed); the first non-null wins, and a request no policy admits gets <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback callers with no proxy-forwarding headers (<code>X-Forwarded-For</code>, <code>X-Real-IP</code>, <code>Forwarded</code>, and <code>X-Forwarded-Host</code> are all rejected, so tunnels and same-host reverse proxies don&#39;t silently re-expose the route), plus a loopback <code>Host</code> header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname.</td></tr><tr><td><code>localDev()</code></td><td>Like <code>localDevStrict()</code> but without the <code>Host</code> check. An explicit, weaker opt-in.</td></tr><tr><td><code>loopbackOnly()</code></td><td>A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like <code>gh webhook forward</code>.</td></tr><tr><td><code>bearerAuth(token)</code></td><td><code>Authorization: Bearer &lt;token&gt;</code>, compared in constant time. Also accepts a verifier function mapping a presented token to an <code>AuthContext</code>.</td></tr><tr><td><code>allowAll()</code></td><td>Everyone, as an <code>anonymous</code> principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.</td></tr></tbody></table><p>The resolved <code>AuthContext</code> (<code>{ authenticator, principalId, principalType, attributes? }</code>) becomes the request principal. Sessions bind to the principal that created them, and follow-up, stream, and list routes enforce ownership (<code>403</code> otherwise).</p><p>Server flags interact with authored auth: <code>--bearer-token</code> swaps the default <code>localDevStrict()</code> for <code>bearerAuth(...)</code> on channels that don&#39;t author their own chain, and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>. Authored <code>auth</code> arrays always win over both. A channel that declares <code>[localDevStrict()]</code> stays loopback-only even on an <code>--allow-anonymous</code> host.</p><h2 id="first-class-channels" tabindex="-1">First class channels <a class="header-anchor" href="#first-class-channels" aria-label="Permalink to &quot;First class channels&quot;">​</a></h2><p><strong>Slack</strong> (<code>@cursor/july/channels/slack</code>): Socket Mode transport, streaming replies, engagement rules, approval cards, and a default block on Slack Connect / guest / other-workspace senders. Author <code>agent/channels/slack.ts</code> with <code>slackChannel()</code>. Guide: <a href="./../guides/slack.html">Slack</a>.</p><p><strong>GitHub</strong> (<code>@cursor/july/channels/github</code>): webhook dispatch with signature verification, per-event hooks returning <code>{ auth }</code> (a model turn), <code>{ task }</code> (host work), or <code>null</code>, and CLI tooling for replay and live forwarding. Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code>. Guide: <a href="./../guides/github.html">GitHub</a>.</p><p>For other platforms like Discord or Teams, use the authored <code>defineChannel</code> webhook form.</p><h2 id="continuation-semantics" tabindex="-1">Continuation semantics <a class="header-anchor" href="#continuation-semantics" aria-label="Permalink to &quot;Continuation semantics&quot;">​</a></h2><p>Channels own their continuation-token format. The built-in HTTP channel mints opaque rotating tokens, Slack uses <code>channelId:threadTs</code>, and PR automations use keys like <code>pr:owner/repo#N</code>. Same token, same durable session; one active continuation per session; the HTTP channel returns <code>409</code> for stale tokens. For the full session model, see <a href="./sessions.html">Sessions</a>.</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><p>Continue with these pages:</p><ul><li><a href="./../guides/webhooks.html">Webhooks guide</a>: the same API, walked through</li><li><a href="./http-api.html">HTTP API</a>: the built-in routes precisely</li><li><a href="./sessions.html">Sessions and streaming</a>: the events channels subscribe to</li></ul>`,38)])])}const E=e(n,[["render",h]]);export{k as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This example assumes <code>agent/tools/inspect_pr.ts</code> exists. The handler calls it before the model turn, so every review starts with validated PR data. It also derives a stable conversation key from the PR URL and writes the tool result to <code>pr.json</code>. Instructions can ask the model to inspect a PR, but host code guarantees it.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p><code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, and <code>DELETE</code> helpers build routes. Their schemas are Zod, enforced at compile time:</p><table tabindex="0"><thead><tr><th>Verb</th><th>Required schema</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>querySchema</code></td></tr><tr><td><code>POST</code> / <code>PUT</code> / <code>PATCH</code></td><td><code>bodySchema</code> (optional <code>querySchema</code>)</td></tr><tr><td><code>DELETE</code></td><td>both optional</td></tr></tbody></table><p>Plain JSON Schema objects won&#39;t type-check; use <code>z.object({})</code> or <code>z.unknown()</code> for intentionally open surfaces. The host validates before the handler runs. Handlers receive typed <code>args.body</code> and <code>args.query</code>, and empty POST bodies are coerced to <code>{}</code> first. Declared schemas are projected on <code>GET /v1/info</code>, which powers the playground&#39;s <strong>Try</strong> buttons and composer <strong>slash commands</strong>.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>Handlers receive the Fetch <code>Request</code> and an args object:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Run a model turn on this channel; returns the session handle (options below)</td></tr><tr><td><code>getSession(sessionId)</code></td><td>Look up an existing session on this channel</td></tr><tr><td><code>receive(channelDefinition, input)</code></td><td>Hand off to another channel (schedules use this)</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td>Deterministic server-tool call (<a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>)</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated payloads and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> resolved by this route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address</td></tr><tr><td><code>host</code></td><td>Shared services: <code>host.mcp</code>, <code>host.github</code>, <code>host.slack</code>, <code>host.kv</code>, <code>host.files</code>, <code>host.reminders</code></td></tr><tr><td><code>waitUntil(promise)</code></td><td>Background work that outlives the response</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Absolute playground + trace URLs for a session on this mount</td></tr><tr><td><code>artifacts</code></td><td>Unbound <a href="./artifacts.html">artifacts</a> facade; pass <code>sessionId</code> in <code>tag</code> input to attribute one</td></tr></tbody></table><p><code>send</code> options: <code>continuationToken</code> (the conversation key), <code>admission</code> (<code>&quot;preempt&quot;</code> interrupts a busy session, the default; <code>&quot;coalesce&quot;</code> enqueues behind the running turn, the <a href="./sessions.html#what-happens-when-i-send-a-follow-up">Slack policy</a>), <code>workspaceFiles</code>, <code>workspaceDir</code>, <code>cloud</code> (attach cloud repos for this session), <code>auth</code> (defaults to the request principal), <code>sdkAgentId</code> (resume a specific SDK agent), <code>state</code> (starting channel state for new sessions), <code>title</code> (session display title), <code>purpose</code> (<code>&quot;eval&quot;</code> skips sticky A/B enrollment), and <code>coalesceSourceTs</code> (dedupe key for coalesce queue items already delivered mid-turn).</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Keys are event types from the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>, or <code>&quot;*&quot;</code>. Handlers receive <code>(event, channel, ctx)</code>, where <code>channel.state</code> is the per-session adapter state and <code>ctx</code> exposes session info and host services. This is where a channel delivers replies back to its surface.</p><h2 id="state-and-lifecycle" tabindex="-1">State and lifecycle <a class="header-anchor" href="#state-and-lifecycle" aria-label="Permalink to &quot;State and lifecycle&quot;">​</a></h2><p><code>state</code> declares the starting per-session adapter state (JSON), persisted on the session record. Routes and event handlers read and mutate it through <code>channel.state</code>. <code>onStart(args)</code> runs when the channel mounts; the Slack pack opens its Socket Mode connection here. <code>onStop()</code> runs when the server drains.</p><p><code>onStart</code> receives the route helpers (<code>send</code>, <code>getSession</code>, <code>receive</code>, <code>callTool</code>, <code>host</code>, <code>waitUntil</code>, <code>artifacts</code>, and a <code>logger</code> that respects the server&#39;s log sink) plus a set that exists for long-lived transports:</p><ul><li><code>emitAssistantMessage(sessionId, text)</code> appends an assistant message without a model turn, for host tasks that already produced the final text.</li><li><code>hasContinuationSession(token)</code> and <code>isContinuationBusy(token)</code> report whether a continuation token has a live session and whether a turn is in flight on it.</li><li><code>getContinuationLastBotMessageTs(token)</code> reads the Slack warm-delta watermark from channel state.</li><li><code>interruptContinuation(token)</code> stops the in-flight turn and clears coalesced follow-ups queued behind it.</li><li><code>resolveApproval(sessionId, callId, decision, auth, options?)</code> approves or denies a parked tool call, how Slack Block Kit buttons unblock a turn without the HTTP approvals route.</li></ul><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs an auth-policy chain: the channel&#39;s <code>auth</code> array, or <code>[localDevStrict()]</code> when unset. A policy is a function <code>(request, info) =&gt; AuthContext | null</code> (async allowed); the first non-null wins, and a request no policy admits gets <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback callers with no proxy-forwarding headers (<code>X-Forwarded-For</code>, <code>X-Real-IP</code>, <code>Forwarded</code>, and <code>X-Forwarded-Host</code> are all rejected, so tunnels and same-host reverse proxies don&#39;t silently re-expose the route), plus a loopback <code>Host</code> header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname.</td></tr><tr><td><code>localDev()</code></td><td>Like <code>localDevStrict()</code> but without the <code>Host</code> check. An explicit, weaker opt-in.</td></tr><tr><td><code>loopbackOnly()</code></td><td>A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like <code>gh webhook forward</code>.</td></tr><tr><td><code>bearerAuth(token)</code></td><td><code>Authorization: Bearer &lt;token&gt;</code>, compared in constant time. Also accepts a verifier function mapping a presented token to an <code>AuthContext</code>.</td></tr><tr><td><code>allowAll()</code></td><td>Everyone, as an <code>anonymous</code> principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.</td></tr></tbody></table><p>The resolved <code>AuthContext</code> (<code>{ authenticator, principalId, principalType, attributes? }</code>) becomes the request principal. Sessions bind to the principal that created them, and follow-up, stream, and list routes enforce ownership (<code>403</code> otherwise).</p><p>Server flags interact with authored auth: <code>--bearer-token</code> swaps the default <code>localDevStrict()</code> for <code>bearerAuth(...)</code> on channels that don&#39;t author their own chain, and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>. Authored <code>auth</code> arrays always win over both. A channel that declares <code>[localDevStrict()]</code> stays loopback-only even on an <code>--allow-anonymous</code> host.</p><h2 id="first-class-channels" tabindex="-1">First class channels <a class="header-anchor" href="#first-class-channels" aria-label="Permalink to &quot;First class channels&quot;">​</a></h2><p><strong>Slack</strong> (<code>@cursor/july/channels/slack</code>): Socket Mode transport, streaming replies, engagement rules, approval cards, and a default block on Slack Connect / guest / other-workspace senders. Author <code>agent/channels/slack.ts</code> with <code>slackChannel()</code>. Guide: <a href="./../guides/slack.html">Slack</a>.</p><p><strong>GitHub</strong> (<code>@cursor/july/channels/github</code>): webhook dispatch with signature verification, per-event hooks returning <code>{ auth }</code> (a model turn), <code>{ task }</code> (host work), or <code>null</code>, and CLI tooling for replay and live forwarding. Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code>. Opt-in <code>progress.commitStatus</code> and <code>progress.banner</code> converge a merge-box check and sticky PR comment from default stream events. Guide: <a href="./../guides/github.html">GitHub</a>.</p><p>For other platforms like Discord or Teams, use the authored <code>defineChannel</code> webhook form.</p><h2 id="continuation-semantics" tabindex="-1">Continuation semantics <a class="header-anchor" href="#continuation-semantics" aria-label="Permalink to &quot;Continuation semantics&quot;">​</a></h2><p>Channels own their continuation-token format. The built-in HTTP channel mints opaque rotating tokens, Slack uses <code>channelId:threadTs</code>, and PR automations use keys like <code>pr:owner/repo#N</code>. Same token, same durable session; one active continuation per session; the HTTP channel returns <code>409</code> for stale tokens. For the full session model, see <a href="./sessions.html">Sessions</a>.</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><p>Continue with these pages:</p><ul><li><a href="./../guides/webhooks.html">Webhooks guide</a>: the same API, walked through</li><li><a href="./http-api.html">HTTP API</a>: the built-in routes precisely</li><li><a href="./sessions.html">Sessions and streaming</a>: the events channels subscribe to</li></ul>`,38)])])}const E=e(n,[["render",h]]);export{k as __pageData,E as default};

package/dist/docs/assets/{reference_cli.md.DqEqQpGn.js → reference_cli.md.BDmjPPAm.js}

@@ -7,8 +7,8 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--cursor-github-proxy] [--no-control-plane]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--no-schedules] [--no-playground]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--no-docs] [--cursor-events --repo owner/name]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span></span></code></pre></div><p>If <code>--dir</code> is an agent project, it mounts under its directory name. If it contains agent projects, each child mounts separately. The index lives at <code>/</code>. Each agent is available at <code>/&lt;slug&gt;/v1/*</code> and <code>/&lt;slug&gt;/playground</code>. On a TTY, press Enter to reload agent code. Unless <code>--state-root</code> is set, each mount uses <code>&lt;agent-project&gt;/.agent-serve</code>; slugged mounts use <code>&lt;agent-project&gt;/.agent-serve/&lt;slug&gt;</code>.</p><table tabindex="0"><thead><tr><th>Flag</th><th>Meaning</th></tr></thead><tbody><tr><td><code>--port</code></td><td>Listen on this port. <code>0</code> selects an available port. The default is <code>3000</code>. When the default is taken, serve tries the next free port and prints a notice; an explicit <code>--port</code> fails with a next-port hint instead.</td></tr><tr><td><code>--host</code></td><td>Bind this host. The default is loopback-only <code>127.0.0.1</code>.</td></tr><tr><td><code>--dev</code></td><td>Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, widen playground session access on loopback, and start Vite HMR when available.</td></tr><tr><td><code>--mode</code></td><td>Use <code>multi</code> for slugged routes and an index, or <code>single</code> for one agent at the unslugged <code>/v1/*</code>. The default is <code>multi</code>.</td></tr><tr><td><code>--api-key</code></td><td>Use this Cursor API key. The command falls back to <code>CURSOR_API_KEY</code>, then the stored login.</td></tr><tr><td><code>--state-root</code></td><td>Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository.</td></tr><tr><td><code>--bearer-token</code></td><td>Require this bearer token on routes without authored auth. Mutually exclusive with <code>--allow-anonymous</code>.</td></tr><tr><td><code>--allow-anonymous</code></td><td>Admit every caller as one <code>anonymous</code> principal. Use only behind a trusted network boundary.</td></tr><tr><td><code>--allow-anonymous-cursor-github</code></td><td>Allow anonymous callers to drive sessions holding a Cursor account&#39;s repo-scoped GitHub credential. Use only behind an authenticating proxy.</td></tr><tr><td><code>--allow-anonymous-cursor-account-mcp</code></td><td>Allow anonymous callers to drive Cursor account MCP connectors (<code>defineConnection({ cursorAccount: true })</code>). Use only behind an authenticating proxy (hosted alias token counts).</td></tr><tr><td><code>--public-url</code></td><td>Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server.</td></tr><tr><td><code>--cloud-tools-url</code></td><td>Authenticated HTTP MCP URL for this deployment&#39;s direct server-tool endpoint. Hosted deployments configure it automatically.</td></tr><tr><td><code>--cursor-github-proxy</code></td><td>Route <code>githubChannel({ cursorAccount })</code> API calls through the Cursor backend&#39;s GitHub forwarder instead of minting raw installation tokens into this process. <code>AGENT_SERVE_GITHUB_PROXY_URL</code> overrides the base URL.</td></tr><tr><td><code>--no-control-plane</code></td><td>Skip the bundled schedule and reminder clocks. Cursor hosting passes this so the platform fires timed work through internal routes instead.</td></tr><tr><td><code>--no-schedules</code></td><td>Disable the cron runner outside dev mode.</td></tr><tr><td><code>--no-playground</code></td><td>Skip the web playground and its build or HMR process.</td></tr><tr><td><code>--no-docs</code></td><td>Skip the documentation site at <code>/docs</code> and its build.</td></tr><tr><td><code>--cursor-events</code></td><td>Pull SCM events from Cursor&#39;s <code>/v0/scm-events</code> in addition to authored webhook routes. Requires a signed-in host. Pass repeatable <code>--repo owner/name</code> values; repos declared by <code>githubChannel({ cursorAccount })</code> also enable the relay. State lives under <code>&lt;state-root&gt;/cursor-events/</code>.</td></tr></tbody></table><p>Multi-agent slugs must start with a letter or digit, then contain only letters, digits, <code>_</code>, or <code>-</code>. The reserved slugs are <code>v1</code>, <code>playground</code>, and <code>docs</code>.</p><h2 id="dev" tabindex="-1">dev <a class="header-anchor" href="#dev" aria-label="Permalink to &quot;dev&quot;">​</a></h2><p><code>dev</code> is the local-development shortcut for <code>serve --dev</code>. Pass the agent folder as a positional path, or run it from inside the project:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-approver</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./pr-approver</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --port</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3000</span></span></code></pre></div><p><code>dev</code> accepts the same flags as <a href="#serve"><code>serve</code></a>. You can use <code>--dir</code> instead of the positional path. Dev mode is always on: schedules and reminders wait for manual dispatch, GitHub accepts unsigned loopback deliveries, and Vite HMR starts when the toolchain is present. Prefer this over <code>serve --dev</code> while iterating. Pass at most one positional path. Don&#39;t combine a positional path with a different <code>--dir</code>.</p><h2 id="chat" tabindex="-1">chat <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;chat&quot;">​</a></h2><p><code>chat</code> talks to a running agent from the terminal. It never starts a server.</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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/pr-approver</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./sdk-pr-reviewer</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./sdk-pr-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --port</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3000</span></span></code></pre></div><p><code>dev</code> accepts the same flags as <a href="#serve"><code>serve</code></a>. You can use <code>--dir</code> instead of the positional path. Dev mode is always on: schedules and reminders wait for manual dispatch, GitHub accepts unsigned loopback deliveries, and Vite HMR starts when the toolchain is present. Prefer this over <code>serve --dev</code> while iterating. Pass at most one positional path. Don&#39;t combine a positional path with a different <code>--dir</code>.</p><h2 id="chat" tabindex="-1">chat <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;chat&quot;">​</a></h2><p><code>chat</code> talks to a running agent from the terminal. It never starts a server.</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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/pr-approver</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is the PR ready to approve?&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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Inspect PR 42&quot;</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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pr-approver</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --team</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 123</span></span></code></pre></div><p><code>chat</code> streams text, tool calls, and a per-turn usage footer. On a TTY, <code>--message</code> seeds the interactive REPL. With non-TTY input, <code>--message</code> runs one turn and exits; without it, <code>chat</code> reads newline-delimited messages until EOF. <code>--json</code> requires <code>--message</code>, runs one turn, and prints <code>{ ok, sessionId, continuationToken, trajectory }</code>. <code>--text</code> prints a compact trajectory when combined with <code>--json</code>. <code>--no-color</code> forces plain interactive output.</p><p>Use <code>--session &lt;id&gt;</code> to reattach a stored session. The command looks up its continuation token when you omit <code>--continuation-token</code>. Use <code>--resume</code> to select the most recently updated session with a continuation token.</p><h2 id="resume" tabindex="-1">resume <a class="header-anchor" href="#resume" aria-label="Permalink to &quot;resume&quot;">​</a></h2><p><code>resume</code> is the direct way to reattach the chat REPL.</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;"> resume</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ses_123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/pr-approver</span></span>

package/dist/docs/assets/{reference_hooks.md.B40QAG6m.js → reference_hooks.md.4cbRRIIu.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,r,l,c){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook is an observe-only subscriber to the session event stream. Hooks run after each event is recorded and fanned out (file persistence flushes in the background). That makes them the home for audit logging, metrics, mirroring transcripts into your own store, and maintaining derived state. Handler errors are logged and never fatal. A hook can&#39;t modify events, inject context into the next turn, or block a turn.</p><p>For deterministic context composition before the model runs, use the host path that already owns the wake: channel handlers (fetch, <code>callTool</code>, <code>workspaceFiles</code>, and the message you pass to <code>send</code>), plus <code>instructions.md</code>, skills, and <code>sandbox/workspace/</code> seed files. Hooks observe what happened; they do not assemble the prompt.</p><p>Author <code>agent/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/july/hooks</code>:</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/hooks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),o={name:"reference/hooks.md"};function n(d,e,r,h,l,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook is an observe-only subscriber to the session event stream. Hooks run after each event is recorded and fanned out (file persistence flushes in the background). That makes them the home for audit logging, metrics, mirroring transcripts into your own store, and maintaining derived state. Handler errors are logged and never fatal. A hook can&#39;t modify events, inject context into the next turn, or block a turn.</p><p>For deterministic context composition before the model runs, use the host path that already owns the wake: channel handlers (fetch, <code>callTool</code>, <code>workspaceFiles</code>, and the message you pass to <code>send</code>), plus <code>instructions.md</code>, skills, and <code>sandbox/workspace/</code> seed files. Hooks observe what happened; they do not assemble the prompt.</p><p>Author <code>agent/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/july/hooks</code>:</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/hooks&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;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
@@ -11,4 +11,4 @@ import{_ as e,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // page, count, or record</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><p>Keys are event types (the full list is in the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>), or <code>&quot;*&quot;</code> for everything. Handlers receive the event with its envelope (<code>index</code>, <code>sessionId</code>, <code>turnId?</code>, <code>at</code>) and a <code>HookContext</code>:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code> for the owning channel</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root; hooks maintaining derived state write here</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services; same as a tool&#39;s <code>ctx.host</code>. Pull JSON with <code>ctx.host.kv</code> and file-shaped state with <code>ctx.host.files</code> (session-bound by default; pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files)</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><h2 id="hooks-channel-events-evals-or-a-b" tabindex="-1">Hooks, channel events, evals, or A/B? <a class="header-anchor" href="#hooks-channel-events-evals-or-a-b" aria-label="Permalink to &quot;Hooks, channel events, evals, or A/B?&quot;">​</a></h2><p>All of them consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th><th>A/B (<code>defineAB</code>)</th></tr></thead><tbody><tr><td>Scope</td><td>every session on the agent</td><td>sessions the channel owns</td><td>one test turn</td><td>every live session; enrollment at creation, metrics on each turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td><td><code>ab.assigned</code> + fold stream → <code>onSample</code></td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td><td>yes through arm instructions or <code>session.abs</code>; collection is observe-only</td></tr><tr><td>Authored at</td><td><code>agent/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td><td><a href="./../ab.html"><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></a></td></tr></tbody></table><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Usage metering: subscribe to <code>turn.completed</code> and forward <code>event.data.usage</code> (token counts) to your metrics system.</p><p>Failure alerting: <code>turn.failed</code> carries the message, and <code>ctx.session.id</code> points at the trace.</p><p>Derived state: <code>agent.bound</code> fires when the Cursor SDK agent id is known (<code>bc-…</code> on cloud). A PR agent can record PR → agent id from it in a hook, so later webhook wakes resume the same cloud conversation.</p><p>Transcript export: subscribe to <code>&quot;*&quot;</code> and append to your own store. The NDJSON envelope is already ordered and replayable.</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><p>Continue with these pages:</p><ul><li><a href="./sessions.html">Sessions and streaming</a>: every event a hook can see</li><li><a href="./../deployment.html#observability">Deployment</a>: hooks as the metrics export path</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li><li><a href="./../ab.html">Live A/B metrics</a>: sticky variants over the same event stream</li></ul>`,18)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Keys are event types (the full list is in the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>), or <code>&quot;*&quot;</code> for everything. Handlers receive the event with its envelope (<code>index</code>, <code>sessionId</code>, <code>turnId?</code>, <code>at</code>) and a <code>HookContext</code>:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code> for the owning channel</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root. Prefer <code>ctx.host.kv</code> / <code>ctx.host.files</code> for derived state; this tree resets on hosted replace</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services; same as a tool&#39;s <code>ctx.host</code>. Pull JSON with <code>ctx.host.kv</code> and file-shaped state with <code>ctx.host.files</code> (session-bound by default; pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files)</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><p>Hook context includes <code>ctx.host</code>, the same shared services a tool gets. Persist JSON with <code>ctx.host.kv</code> and file-shaped state with <code>ctx.host.files</code>. Hooks observe; they do not own delivery surfaces.</p><h2 id="hooks-channel-events-evals-or-a-b" tabindex="-1">Hooks, channel events, evals, or A/B? <a class="header-anchor" href="#hooks-channel-events-evals-or-a-b" aria-label="Permalink to &quot;Hooks, channel events, evals, or A/B?&quot;">​</a></h2><p>All of them consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th><th>A/B (<code>defineAB</code>)</th></tr></thead><tbody><tr><td>Scope</td><td>every session on the agent</td><td>sessions the channel owns</td><td>one test turn</td><td>every live session; enrollment at creation, metrics on each turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td><td><code>ab.assigned</code> + fold stream → <code>onSample</code></td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td><td>yes through arm instructions or <code>session.abs</code>; collection is observe-only</td></tr><tr><td>Authored at</td><td><code>agent/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td><td><a href="./../ab.html"><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></a></td></tr></tbody></table><p>For GitHub commit status and sticky PR banners, use <code>githubChannel({ progress: { commitStatus, banner } })</code> from <code>@cursor/july/channels/github</code>. That is the supported Autofix-style path. See <a href="./../guides/github.html#show-pr-progress">GitHub: Show PR progress</a>. Override channel <code>events</code> only when the lifecycle is custom (for example <a href="./../example-agents/approval-buddy.html">Approval Buddy</a>&#39;s never-red status from tool output). Do not use <code>defineHook</code> for those writes.</p><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Usage metering: subscribe to <code>turn.completed</code> and forward <code>event.data.usage</code> (token counts) to your metrics system.</p><p>Failure alerting: <code>turn.failed</code> carries the message, and <code>ctx.session.id</code> points at the trace.</p><p>Derived state: <code>agent.bound</code> fires when the Cursor SDK agent id is known (<code>bc-…</code> on cloud). A PR agent can record PR → agent id from it in a hook with <code>ctx.host.kv</code>, so later webhook wakes resume the same cloud conversation. Prefer <code>ctx.host.kv</code> or <code>ctx.host.files</code> for ids that must survive hosted replace. <code>stateRoot</code> resets on replace.</p><p>Transcript export: subscribe to <code>&quot;*&quot;</code> and append to your own store. The NDJSON envelope is already ordered and replayable.</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><p>Continue with these pages:</p><ul><li><a href="./sessions.html">Sessions and streaming</a>: every event a hook can see</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li><li><a href="./../ab.html">Live A/B metrics</a>: sticky variants over the same event stream</li></ul>`,20)])])}const u=s(o,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_hooks.md.B40QAG6m.lean.js → reference_hooks.md.4cbRRIIu.lean.js}

@@ -1 +1 @@
-import{_ as e,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,r,l,c){return a(),t("div",null,[...s[0]||(s[0]=[i("",18)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),o={name:"reference/hooks.md"};function n(d,e,r,h,l,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",20)])])}const u=s(o,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_project-layout.md._XdeMahr.js → reference_project-layout.md.D3MdHM2z.js}

@@ -17,6 +17,7 @@ import{_ as t,c as a,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const u
 <span class="line"><span>│   │   └── github.ts          # the GitHub webhook channel pack</span></span>
 <span class="line"><span>│   ├── hooks/</span></span>
 <span class="line"><span>│   │   └── audit.ts           # observe the runtime event stream</span></span>
+<span class="line"><span>│   ├── otel.ts                # optional OpenTelemetry export</span></span>
 <span class="line"><span>│   ├── ab.ts                  # optional live A/B experiment</span></span>
 <span class="line"><span>│   ├── ab/</span></span>
 <span class="line"><span>│   │   └── concise.ts         # optional: more experiments</span></span>
@@ -26,6 +27,6 @@ import{_ as t,c as a,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const u
 <span class="line"><span>│   └── lib/                   # shared code (import-only, never discovered)</span></span>
 <span class="line"><span>└── evals/</span></span>
 <span class="line"><span>    ├── evals.config.ts        # required when evals exist (maxConcurrency)</span></span>
-<span class="line"><span>    └── readiness.eval.ts      # filesystem evals</span></span></code></pre></div><p>Evals live in <code>evals/</code> at the project root, a sibling of <code>agent/</code>, never inside it. <code>agent/evals/</code> is silently ignored. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>agent/skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>agent/ab.ts</code>, <code>agent/ab/*.ts</code></td><td><code>defineAB</code> experiments with sticky variants and live metrics</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/ab.config.ts</code></td><td><code>defineABConfig</code> shared A/B settings</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/storage.ts</code></td><td><code>defineStorage</code> backend for the durable <code>host.kv</code> / <code>host.files</code> APIs</td><td><a href="./../storage.html">Storage</a></td></tr><tr><td><code>agent/artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>agent/sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#what-goes-into-a-local-session-workspace">Sessions</a></td></tr><tr><td><code>agent/playground/</code></td><td>Custom playground tool chips for the Vite dev playground</td><td><a href="./playground.html">Playground</a></td></tr><tr><td><code>agent/lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><code>agent/lib/</code> is the only place for shared code. Everything else under <code>agent/</code> is discovery surface. A stray <code>.ts</code> file in one of these folders is treated as a definition.</p><h2 id="why-didn-t-the-agent-sdk-discover-my-file" tabindex="-1">Why didn&#39;t the Agent SDK discover my file? <a class="header-anchor" href="#why-didn-t-the-agent-sdk-discover-my-file" aria-label="Permalink to &quot;Why didn&#39;t the Agent SDK discover my file?&quot;">​</a></h2><p>Run <code>agent-sdk validate --dir .</code> and <code>agent-sdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings, such as cloud runtime combined with local-only capabilities, print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # diagnostics; non-zero exit on errors</span></span>
+<span class="line"><span>    └── readiness.eval.ts      # filesystem evals</span></span></code></pre></div><p>Evals live in <code>evals/</code> at the project root, a sibling of <code>agent/</code>, never inside it. <code>agent/evals/</code> is silently ignored. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>agent/skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>agent/otel.ts</code></td><td><code>defineOtel</code> OTLP export (traces, metrics, optional logs)</td><td><a href="./../guides/opentelemetry.html">OpenTelemetry</a></td></tr><tr><td><code>agent/ab.ts</code>, <code>agent/ab/*.ts</code></td><td><code>defineAB</code> experiments with sticky variants and live metrics</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/ab.config.ts</code></td><td><code>defineABConfig</code> shared A/B settings</td><td><a href="./../ab.html">Live A/B metrics</a></td></tr><tr><td><code>agent/storage.ts</code></td><td><code>defineStorage</code> backend for the durable <code>host.kv</code> / <code>host.files</code> APIs</td><td><a href="./../storage.html">Storage</a></td></tr><tr><td><code>agent/artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>agent/sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#what-goes-into-a-local-session-workspace">Sessions</a></td></tr><tr><td><code>agent/playground/</code></td><td>Custom playground tool chips for the Vite dev playground</td><td><a href="./playground.html">Playground</a></td></tr><tr><td><code>agent/lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><code>agent/lib/</code> is the only place for shared code. Everything else under <code>agent/</code> is discovery surface. A stray <code>.ts</code> file in one of these folders is treated as a definition.</p><h2 id="why-didn-t-the-agent-sdk-discover-my-file" tabindex="-1">Why didn&#39;t the Agent SDK discover my file? <a class="header-anchor" href="#why-didn-t-the-agent-sdk-discover-my-file" aria-label="Permalink to &quot;Why didn&#39;t the Agent SDK discover my file?&quot;">​</a></h2><p>Run <code>agent-sdk validate --dir .</code> and <code>agent-sdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings, such as cloud runtime combined with local-only capabilities, print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # diagnostics; non-zero exit on errors</span></span>
 <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:#6A737D;--shiki-dark:#6A737D;">        # human-readable surface</span></span>
 <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:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # machine-readable manifest (same shape as GET /v1/info)</span></span></code></pre></div><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><p>Continue with these pages:</p><ul><li><a href="./agent-config.html">Agent config</a>: the runtime config at the root</li><li><a href="./tools.html">Tools</a>: add typed actions under <code>agent/tools/</code></li><li><a href="./../ab.html">Live A/B metrics</a>: compare variants from <code>agent/ab.ts</code> or <code>agent/ab/</code></li><li><a href="./../concepts.html">Concepts</a>: why the filesystem is the interface</li></ul>`,20)])])}const g=t(d,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_tools.md.lSrsTxYJ.js → reference_tools.md.kJfJAP2m.js}

@@ -22,7 +22,7 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prUrl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { prUrl };</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><h3 id="the-ctx-parameter" tabindex="-1">The <code>ctx</code> parameter <a class="header-anchor" href="#the-ctx-parameter" aria-label="Permalink to &quot;The \`ctx\` parameter&quot;">​</a></h3><p><code>execute</code> receives a <code>ctx</code> with the runtime accessors:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.toolCallId</code></td><td>The call id, matching the <code>actions.requested</code> / <code>action.result</code> stream events</td></tr><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session&#39;s workspace directory</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root, shared across every session</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services (see below)</td></tr><tr><td><code>ctx.send(channelId, message, options?)</code></td><td>Start or resume a session on any channel: the cross-channel handoff primitive, e.g. a chat tool opening a <code>drive</code> cloud session for a PR. <code>auth</code> defaults to this call&#39;s session principal</td></tr><tr><td><code>ctx.getSession(channelId, sessionId)</code></td><td>Look up a session on a channel, e.g. refresh <code>sdkAgentId</code> after a turn</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><p><code>ctx.host</code> carries the shared host services: <code>host.mcp</code> (authored MCP connections: <code>names()</code>, <code>listTools(name)</code>, <code>callTool(name, tool, args)</code>), <code>host.github</code> and <code>host.slack</code> (shared platform clients), <code>host.kv</code> and <code>host.files</code> (durable <a href="./../storage.html">storage</a>), <code>host.reminders</code> (per-session wakes, when attached), <code>host.evals</code> (playground eval batches, when attached), and <code>host.slackNudges</code> (Slack ask-dedupe helpers).</p><h3 id="return-values" tabindex="-1">Return values <a class="header-anchor" href="#return-values" aria-label="Permalink to &quot;Return values&quot;">​</a></h3><p><code>execute</code> may return a string (passed to the model verbatim), a JSON-shaped value (serialized), or the envelope <code>{ content: [...], isError? }</code> for rich results. Returns must be JSON-shaped: use object literals or <code>type</code> aliases. An <code>interface</code> type fails assignability (no index signature), and tsx won&#39;t catch it. Your typecheck will.</p><p>Throwing inside <code>execute</code> reports an error result to the model (<code>isError: true</code>). The turn and the server keep running.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. Use this flavor when the tool must run next to the checkout the agent works in; on cloud, server tools stay available too through the host&#39;s HTTP MCP endpoint.</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="the-ctx-parameter" tabindex="-1">The <code>ctx</code> parameter <a class="header-anchor" href="#the-ctx-parameter" aria-label="Permalink to &quot;The \`ctx\` parameter&quot;">​</a></h3><p><code>execute</code> receives a <code>ctx</code> with the runtime accessors:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.toolCallId</code></td><td>The call id, matching the <code>actions.requested</code> / <code>action.result</code> stream events</td></tr><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session&#39;s workspace directory</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent&#39;s durable state root, shared across every session</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services (see below)</td></tr><tr><td><code>ctx.send(channelId, message, options?)</code></td><td>Start or resume a session on any channel: the cross-channel handoff primitive, e.g. a chat tool opening a <code>drive</code> cloud session for a PR. <code>auth</code> defaults to this call&#39;s session principal</td></tr><tr><td><code>ctx.getSession(channelId, sessionId)</code></td><td>Look up a session on a channel, e.g. refresh <code>sdkAgentId</code> after a turn</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><p><code>ctx.host</code> carries the shared host services: <code>host.mcp</code> (authored MCP connections: <code>names()</code>, <code>listTools(name)</code>, <code>callTool(name, tool, args)</code>), <code>host.github</code> and <code>host.slack</code> (shared platform clients), <code>host.kv</code> and <code>host.files</code> (durable <a href="./../storage.html">storage</a>), <code>host.otel</code> (custom metrics and session tags; see <a href="./../guides/opentelemetry.html">OpenTelemetry</a>), <code>host.reminders</code> (per-session wakes, when attached), <code>host.evals</code> (playground eval batches, when attached), and <code>host.slackNudges</code> (Slack ask-dedupe helpers).</p><h3 id="return-values" tabindex="-1">Return values <a class="header-anchor" href="#return-values" aria-label="Permalink to &quot;Return values&quot;">​</a></h3><p><code>execute</code> may return a string (passed to the model verbatim), a JSON-shaped value (serialized), or the envelope <code>{ content: [...], isError? }</code> for rich results. Returns must be JSON-shaped: use object literals or <code>type</code> aliases. An <code>interface</code> type fails assignability (no index signature), and tsx won&#39;t catch it. Your typecheck will.</p><p>Throwing inside <code>execute</code> reports an error result to the model (<code>isError: true</code>). The turn and the server keep running.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. Use this flavor when the tool must run next to the checkout the agent works in; on cloud, server tools stay available too through the host&#39;s HTTP MCP endpoint.</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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/templates_triage.md.CConZt1z.js

@@ -0,0 +1,11 @@
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Ship a triage agent from the template","description":"Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting.","frontmatter":{"title":"Ship a triage agent from the template","description":"Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function h(r,e,o,l,p,d){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="ship-a-triage-agent-from-the-template" tabindex="-1">Ship a triage agent from the template <a class="header-anchor" href="#ship-a-triage-agent-from-the-template" aria-label="Permalink to &quot;Ship a triage agent from the template&quot;">​</a></h1><p>The triage template is a working agent you own from the first command. It reads a report, classifies it as a bug, a question, or feedback, judges severity against a rubric, records a structured verdict, and replies with the next step. This page walks the whole arc: scaffold, first verdict, customize, prove, wire Slack, deploy.</p><p>Every file the template ships is yours to edit. The only dependency is <code>@cursor/july</code> itself, pinned to the version the template was tested against. Nothing phones home to a template registry.</p><h2 id="scaffold-it" tabindex="-1">Scaffold it <a class="header-anchor" href="#scaffold-it" aria-label="Permalink to &quot;Scaffold it&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./triage-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage</span></span></code></pre></div><p>One command with no prior install. It writes twelve files, runs <code>npm install</code>, puts <code>agent-sdk</code> on your PATH, and offers a browser sign-in when the machine has no Cursor credential. Model turns need that credential, so sign in now rather than mid-flow:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span></code></pre></div><p>The scaffold is a plain directory. Commit it to your own repo.</p><h2 id="get-the-first-verdict" tabindex="-1">Get the first verdict <a class="header-anchor" href="#get-the-first-verdict" aria-label="Permalink to &quot;Get the first verdict&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-agent</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>Open the playground URL it prints and type a real report:</p><blockquote><p>Export to CSV has returned 500s since this morning. Request id 41ac. Retrying does not help.</p></blockquote><p>Watch the turn. The agent reads the <code>triage-rubric</code> skill, calls <code>record_triage</code> with a structured verdict, and replies in six lines or fewer. The tool call renders inline, so you see the exact kind, severity, and next step it recorded.</p><p>Integrations use the same door your playground does. The <code>intake</code> channel accepts reports over HTTP:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/triage-agent/v1/channels/intake/report</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;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;How do I rotate staging API keys?&quot;,&quot;reporter&quot;:&quot;dana&quot;}&#39;</span></span></code></pre></div><p>The composer also autocompletes <code>/report</code>, which drives this route.</p><h2 id="make-the-rubric-yours" tabindex="-1">Make the rubric yours <a class="header-anchor" href="#make-the-rubric-yours" aria-label="Permalink to &quot;Make the rubric yours&quot;">​</a></h2><p><code>agent/skills/triage-rubric.md</code> holds the judgment: what counts as a bug, the tie-breakers, and the severity ladder. Edit it first. Your team&#39;s definition of <code>urgent</code> belongs there, in plain markdown, and the next turn uses it without a restart step.</p><p><code>agent/instructions.md</code> owns the flow around the rubric: when to ask a clarifying question, the one-call <code>record_triage</code> rule, and the reply shape.</p><h2 id="prove-it-with-evals" tabindex="-1">Prove it with evals <a class="header-anchor" href="#prove-it-with-evals" aria-label="Permalink to &quot;Prove it with evals&quot;">​</a></h2><p>The template ships three smoke cases, one per kind. Run them after every rubric edit:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span></span></code></pre></div><p>Each case sends a realistic report and asserts a verdict was recorded with the expected kind. When you tighten the rubric, add a case for the report style you tightened it for. The eval suite is the regression net for prompt changes, so grow it with the rubric.</p><h2 id="file-verdicts-into-your-tracker" tabindex="-1">File verdicts into your tracker <a class="header-anchor" href="#file-verdicts-into-your-tracker" aria-label="Permalink to &quot;File verdicts into your tracker&quot;">​</a></h2><p><code>agent/tools/record_triage.ts</code> defines the verdict shape with a zod schema and returns it. Point its <code>execute</code> at Linear, GitHub Issues, or a webhook to file real tickets. Test the tool without a model turn:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> record_triage</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;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;kind&quot;: &quot;bug&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;severity&quot;: &quot;high&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;title&quot;: &quot;CSV export 500s&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;summary&quot;: &quot;Export returns 500 since this morning.&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;nextStep&quot;: &quot;Check export service logs.&quot;</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&#39;</span></span></code></pre></div><p>The call validates against the schema and runs your <code>execute</code> body in-process, so tracker wiring gets a fast loop.</p><h2 id="wire-it-to-slack" tabindex="-1">Wire it to Slack <a class="header-anchor" href="#wire-it-to-slack" aria-label="Permalink to &quot;Wire it to Slack&quot;">​</a></h2><p>The <code>slack</code> channel idles until its tokens exist, so local work never blocks on Slack. When you want it live:</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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span></span></code></pre></div><p>The guided flow creates the Slack app and writes the token pair to <code>.env.local</code>. Restart <code>agent-sdk dev</code>, invite the bot to a channel, and @mention it with a report. The <a href="./../guides/slack.html">Slack guide</a> covers channel watching and approvals when you outgrow mentions.</p><h2 id="deploy-it" tabindex="-1">Deploy it <a class="header-anchor" href="#deploy-it" aria-label="Permalink to &quot;Deploy it&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span></span></code></pre></div><p>From your git checkout, <code>deploy</code> infers the repo, ref, and slug, builds the ref on Cursor-managed hosting, and prints the hosted URL plus a one-time alias token. Store the token. Production Slack tokens go in as deployment secrets:</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;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> SLACK_BOT_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> SLACK_APP_TOKEN</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triage-agent</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span></span></code></pre></div><p>Check on it with <code>agent-sdk deployments</code>. The <a href="./../deployment.html">deployment guide</a> covers self-hosting, storage, and auth when you need them.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li>Add a GitHub intake with the <a href="./../guides/github.html">GitHub guide</a>, so issue comments triage themselves.</li><li>Persist verdicts across restarts with <a href="./../storage.html">storage</a>.</li><li>Measure rubric changes on live traffic with <a href="./../ab.html">A/B metrics</a>.</li></ul>`,38)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/templates_triage.md.CConZt1z.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Ship a triage agent from the template","description":"Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting.","frontmatter":{"title":"Ship a triage agent from the template","description":"Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting."},"headers":[],"relativePath":"templates/triage.md","filePath":"templates/triage.md"}'),n={name:"templates/triage.md"};function h(r,e,o,l,p,d){return a(),t("div",null,[...e[0]||(e[0]=[i("",38)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};