@cursor/bdk 0.2.4 → 0.2.6

package/dist/docs/assets/{reference_extensions.md.pa2tN-e4.js → reference_extensions.md.OUacPetl.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(o,s,p,h,d,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages capabilities that would otherwise live under <code>bot/</code>: tools, skills, instructions, connections, hooks, channels, schedules, subagents, artifacts, and workspace seeds. One mount file adds them under a namespace without copying their source into your project.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>Extensions and Cursor plugins execute as trusted host code. A namespace prevents name collisions; it does not sandbox the package or limit its side effects. Review the package before mounting it.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package and add one file under <code>bot/extensions/</code>. The filename becomes the namespace, so this mount contributes names such as <code>ci__failed_jobs</code> and <code>ci__triage</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:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci.ts</span></span>
+import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(p,s,o,h,d,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages capabilities that would otherwise live under <code>bot/</code>: tools, skills, instructions, connections, hooks, channels, schedules, subagents, artifacts, and workspace seeds. One mount file adds them under a namespace without copying their source into your project.</p><p>Extensions and Cursor plugins execute as trusted host code. A namespace prevents name collisions; it does not sandbox the package or limit its side effects. Review the package before mounting it.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package and add one file under <code>bot/extensions/</code>. The filename becomes the namespace, so this mount contributes names such as <code>ci__failed_jobs</code> and <code>ci__triage</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:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ci </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@acme/ci-triage&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;"> ci</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -23,7 +23,7 @@ import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci/tools/retry_job.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { disableTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions&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;"> disableTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>The first file replaces <code>ci__job_log</code>; the second removes <code>ci__retry_job</code>. Use the matching <code>disable*</code> helper for another slot, or generic <code>disable()</code> when the file location already identifies it. Validation fails when an overlay names a contribution the package does not provide.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p><code>cursorPlugin()</code> adapts a vendored Cursor or Claude plugin into the same namespace model. Skills, commands, agents, and MCP servers become Agent SDK skills, subagents, and connections.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/notion.ts</span></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;"> disableTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>The first file replaces <code>ci__job_log</code>; the second removes <code>ci__retry_job</code>. Use the matching <code>disable*</code> helper for another slot, or generic <code>disable()</code> when the file location already identifies it. Validation fails when an overlay names a contribution the package does not provide.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p><code>cursorPlugin()</code> adapts a vendored Cursor or Claude plugin into the same namespace model. Skills, commands, agents, and MCP servers become BDK skills, subagents, and connections.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/notion.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorPlugin } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions&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;"> cursorPlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -56,4 +56,4 @@ import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    logTailLines: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">positive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</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:#6F42C1;--shiki-dark:#B392F0;">  hosting</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;api.buildkite.com&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>Modules inside the package import this definition and read <code>extension.config</code>, which is already validated and has defaults applied. Publish the built entry point with its slot directories and prose assets beside it.</p><p><code>hosting</code> names the hosts the package calls and the secrets it reads from the environment. It receives the validated settings, and the mounting agent&#39;s <code>hosting.egressDomains</code> and <code>hosting.secretNames</code> gain whatever it returns, so a hosted deploy reaches Buildkite without the consumer listing <code>api.buildkite.com</code>. Leave out secrets that arrive through settings, such as <code>token</code> here; the consumer decides where that value comes from.</p><p>The <a href="./project-layout.html">Project layout</a> owns each contribution&#39;s authoring contract. Keep extension instructions and tool descriptions namespace-neutral because the consumer chooses the final prefix.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/cloud-agents.html">Cloud agents</a>: delegate repository work through an extension</li><li><a href="./../guides/grokbot-agents.html">Grok Bot agents</a>: consult named bots</li><li><a href="./../guides/jev.html">Jev</a>: typed answers, then gated writes</li><li><a href="./../guides/improve.html">Self-improvement</a>: propose source changes through pull requests</li><li><a href="./project-layout.html">Project layout</a>: contribution slots</li><li><a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>: capability contracts</li></ul>`,38)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Modules inside the package import this definition and read <code>extension.config</code>, which is already validated and has defaults applied. Publish the built entry point with its slot directories and prose assets beside it.</p><p><code>hosting</code> names the hosts the package calls and the secrets it reads from the environment. It receives the validated settings, and the mounting agent&#39;s <code>hosting.egressDomains</code> and <code>hosting.secretNames</code> gain whatever it returns, so a hosted deploy reaches Buildkite without the consumer listing <code>api.buildkite.com</code>. Leave out secrets that arrive through settings, such as <code>token</code> here; the consumer decides where that value comes from.</p><p>The <a href="./project-layout.html">Project layout</a> owns each contribution&#39;s authoring contract. Keep extension instructions and tool descriptions namespace-neutral because the consumer chooses the final prefix.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/cloud-agents.html">Cloud agents</a>: delegate repository work through an extension</li><li><a href="./../guides/grokbot-agents.html">Grok Bot agents</a>: consult named bots</li><li><a href="./../guides/jev.html">Jev</a>: typed answers, then gated writes</li><li><a href="./../guides/improve.html">Self-improvement</a>: propose source changes through pull requests</li><li><a href="./project-layout.html">Project layout</a>: contribution slots</li><li><a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>: capability contracts</li></ul>`,37)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_extensions.md.pa2tN-e4.lean.js → reference_extensions.md.OUacPetl.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(o,s,p,h,d,r){return e(),a("div",null,[...s[0]||(s[0]=[n("",38)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};
+import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(p,s,o,h,d,r){return e(),a("div",null,[...s[0]||(s[0]=[n("",37)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_hooks.md.DbthhtIR.js → reference_hooks.md.C5LCJ1R3.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=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,l,r,p){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 subscribes to selected session events and can run a side effect after each matching event is recorded: an audit line, a metric, a transcript copy, or derived state. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply; a handler that throws is logged and skipped.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>Treat the event as read-only. Later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong surface for anything that must run before the model or must fail a turn; see <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>bot/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
+import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=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,l,r,p){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 subscribes to selected session events and can run a side effect after each matching event is recorded: an audit line, a metric, a transcript copy, or derived state. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply; a handler that throws is logged and skipped.</p><p>Treat the event as read-only. Later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong surface for anything that must run before the model or must fail a turn; see <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>bot/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
 <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/bdk/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>
@@ -42,4 +42,4 @@ import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three 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></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test 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></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</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></ul>`,32)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three 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></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test 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></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</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></ul>`,31)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_hooks.md.DbthhtIR.lean.js → reference_hooks.md.C5LCJ1R3.lean.js}

@@ -1 +1 @@
-import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=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,l,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i("",32)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};
+import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=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,l,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i("",31)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_http-api.md.BZOvhCqY.js → reference_http-api.md.DbFNOubV.js}

@@ -8,4 +8,4 @@ import{_ as t,c as s,o,a3 as a}from"./chunks/framework.BNw1pucY.js";const p=JSON
 <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;input&quot;:{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;toolName&quot;:&quot;inspect_pr&quot;,&quot;callId&quot;:&quot;tool_inspect_pr_…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Body field</th><th>Contract</th></tr></thead><tbody><tr><td><code>input</code></td><td>Tool input; defaults to <code>{}</code></td></tr><tr><td><code>sessionId</code></td><td>Bind the call to an existing session</td></tr><tr><td><code>continuationToken</code></td><td>Bind the call by its wire continuation token; mutually exclusive with <code>sessionId</code></td></tr></tbody></table><p>Omit both identifiers for an unbound call. Agent-execution tools return <code>400</code>, and an unknown name returns <code>404</code> with the available names. See <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a> for session binding, busy-session rules, and error codes.</p><h2 id="discovery-routes" tabindex="-1">Discovery routes <a class="header-anchor" href="#discovery-routes" aria-label="Permalink to &quot;Discovery routes&quot;">​</a></h2><p>These read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics</td></tr><tr><td><code>GET /v1/tools</code></td><td>Return live server tools and advertised MCP tools as <code>{ name, title?, source? }</code>; bind tenant-scoped listings with <code>session</code> or <code>continuationToken</code></td></tr><tr><td><code>GET /v1/tools/:name</code></td><td>Return one tool&#39;s description, execution mode, approval and effect rules, schemas, and source</td></tr><tr><td><code>GET /v1/health</code></td><td>Return per-agent liveness; no auth</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Return recent server logs and the next polling cursor</td></tr></tbody></table><p>An unknown tool name returns <code>404</code> with available names. If an MCP connection can&#39;t list its tools, the catalog skips that connection and includes it in <code>connectionErrors</code>.</p><h2 id="list-and-download-artifacts" tabindex="-1">List and download artifacts <a class="header-anchor" href="#list-and-download-artifacts" aria-label="Permalink to &quot;List and download artifacts&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/artifacts</code></td><td>Return <code>{ artifacts }</code>, newest-updated first; filter with <code>kind</code>, <code>sessionId</code>, and a positive <code>limit</code></td></tr><tr><td><code>GET /v1/artifacts/:id/content</code></td><td>Download an artifact&#39;s file or blob as an attachment; return <code>404</code> when no content exists</td></tr></tbody></table><p>The list follows the same ownership rules as <code>GET /v1/sessions</code>. See <a href="./artifacts.html">Artifacts</a> for tagging and record fields.</p><h2 id="call-custom-channel-routes" tabindex="-1">Call custom channel routes <a class="header-anchor" href="#call-custom-channel-routes" aria-label="Permalink to &quot;Call custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with their declared methods and paths. The host validates their Zod body and query schemas before calling the handler, returning <code>400</code> on failure. Each channel&#39;s auth chain applies. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p>Both MCP routes use stateless streamable HTTP. Send protocol requests with <code>POST</code>; <code>GET</code> and <code>DELETE</code> return <code>405</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Tools and auth</th></tr></thead><tbody><tr><td><code>/v1/mcp</code></td><td><code>ask</code>, <code>check</code>, and <code>call_tool</code> when server tools exist; uses the session API auth chain</td></tr><tr><td><code>/v1/mcp/tools</code></td><td>Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain</td></tr></tbody></table><p>See <a href="./connections.html#peer-mcp-connection">MCP connections</a> to connect one agent to another.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>The playground Evals tab and remote eval commands use these routes:</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered cases and eval config</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots, newest first</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start <code>{ filterIds?, tags?, timeoutMs?, verbose? }</code>; return <code>202</code>, <code>404</code> for no match, or <code>409</code> while another run is active</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Return progress and the final snapshot</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel an active run; return <code>404</code> when unknown or <code>409</code> when no longer running</td></tr></tbody></table><p>Poll the run route until its status is <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics; when both fields are present, a case must match each group.</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes run them manually.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the playground. <code>--no-playground</code> removes both routes.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Built-in routes use these common status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>400</code></td><td>Invalid body, query, tool input, or request shape</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>The caller is authenticated but doesn&#39;t own the resource</td></tr><tr><td><code>404</code></td><td>A named resource doesn&#39;t exist, or an eval selection matches no cases</td></tr><tr><td><code>405</code></td><td>The route doesn&#39;t accept this method</td></tr><tr><td><code>409</code></td><td>The resource state rejects the request, such as a stale token or busy write</td></tr><tr><td><code>202</code></td><td>The request was accepted for asynchronous work</td></tr><tr><td><code>500</code></td><td>A write-effect tool can&#39;t create its session workspace (<code>workspace_unavailable</code>)</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./sessions.html">Sessions</a></li><li><a href="./channels.html">Channels</a></li><li><a href="./tools.html">Tools</a></li><li><a href="./../deployment.html">Deployment</a></li></ul>`,61)])])}const k=t(d,[["render",n]]);export{p as __pageData,k as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Body field</th><th>Contract</th></tr></thead><tbody><tr><td><code>input</code></td><td>Tool input; defaults to <code>{}</code></td></tr><tr><td><code>sessionId</code></td><td>Bind the call to an existing session</td></tr><tr><td><code>continuationToken</code></td><td>Bind the call by its wire continuation token; mutually exclusive with <code>sessionId</code></td></tr></tbody></table><p>Omit both identifiers for an unbound call. Agent-execution tools return <code>400</code>, and an unknown name returns <code>404</code> with the available names. See <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a> for session binding, busy-session rules, and error codes.</p><h2 id="discovery-routes" tabindex="-1">Discovery routes <a class="header-anchor" href="#discovery-routes" aria-label="Permalink to &quot;Discovery routes&quot;">​</a></h2><p>These read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics</td></tr><tr><td><code>GET /v1/tools</code></td><td>Return live server tools and advertised MCP tools as <code>{ name, title?, source? }</code>; bind session-specific listings with <code>session</code> or <code>continuationToken</code></td></tr><tr><td><code>GET /v1/tools/:name</code></td><td>Return one tool&#39;s description, execution mode, approval and effect rules, schemas, and source</td></tr><tr><td><code>GET /v1/health</code></td><td>Return per-agent liveness; no auth</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Return recent server logs and the next polling cursor</td></tr></tbody></table><p>An unknown tool name returns <code>404</code> with available names. If an MCP connection can&#39;t list its tools, the catalog skips that connection and includes it in <code>connectionErrors</code>.</p><h2 id="list-and-download-artifacts" tabindex="-1">List and download artifacts <a class="header-anchor" href="#list-and-download-artifacts" aria-label="Permalink to &quot;List and download artifacts&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/artifacts</code></td><td>Return <code>{ artifacts }</code>, newest-updated first; filter with <code>kind</code>, <code>sessionId</code>, and a positive <code>limit</code></td></tr><tr><td><code>GET /v1/artifacts/:id/content</code></td><td>Download an artifact&#39;s file or blob as an attachment; return <code>404</code> when no content exists</td></tr></tbody></table><p>The list follows the same ownership rules as <code>GET /v1/sessions</code>. See <a href="./artifacts.html">Artifacts</a> for tagging and record fields.</p><h2 id="call-custom-channel-routes" tabindex="-1">Call custom channel routes <a class="header-anchor" href="#call-custom-channel-routes" aria-label="Permalink to &quot;Call custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with their declared methods and paths. The host validates their Zod body and query schemas before calling the handler, returning <code>400</code> on failure. Each channel&#39;s auth chain applies. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p>Both MCP routes use stateless streamable HTTP. Send protocol requests with <code>POST</code>; <code>GET</code> and <code>DELETE</code> return <code>405</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Tools and auth</th></tr></thead><tbody><tr><td><code>/v1/mcp</code></td><td><code>ask</code>, <code>check</code>, and <code>call_tool</code> when server tools exist; uses the session API auth chain</td></tr><tr><td><code>/v1/mcp/tools</code></td><td>Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain</td></tr></tbody></table><p>See <a href="./connections.html#peer-mcp-connection">MCP connections</a> to connect one agent to another.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>The playground Evals tab and remote eval commands use these routes:</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered cases and eval config</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots, newest first</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start <code>{ filterIds?, tags?, timeoutMs?, verbose? }</code>; return <code>202</code>, <code>404</code> for no match, or <code>409</code> while another run is active</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Return progress and the final snapshot</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel an active run; return <code>404</code> when unknown or <code>409</code> when no longer running</td></tr></tbody></table><p>Poll the run route until its status is <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics; when both fields are present, a case must match each group.</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes run them manually.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the playground. <code>--no-playground</code> removes both routes.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Built-in routes use these common status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>400</code></td><td>Invalid body, query, tool input, or request shape</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>The caller is authenticated but doesn&#39;t own the resource</td></tr><tr><td><code>404</code></td><td>A named resource doesn&#39;t exist, or an eval selection matches no cases</td></tr><tr><td><code>405</code></td><td>The route doesn&#39;t accept this method</td></tr><tr><td><code>409</code></td><td>The resource state rejects the request, such as a stale token or busy write</td></tr><tr><td><code>202</code></td><td>The request was accepted for asynchronous work</td></tr><tr><td><code>500</code></td><td>A write-effect tool can&#39;t create its session workspace (<code>workspace_unavailable</code>)</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./sessions.html">Sessions</a></li><li><a href="./channels.html">Channels</a></li><li><a href="./tools.html">Tools</a></li><li><a href="./../deployment.html">Deployment</a></li></ul>`,61)])])}const k=t(d,[["render",n]]);export{p as __pageData,k as default};

package/dist/docs/assets/{reference_instructions.md.Bdwscs4G.js → reference_instructions.md.DrcHZXig.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o as i,a3 as e}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function l(o,s,r,h,d,p){return i(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="instructions" tabindex="-1">Instructions <a class="header-anchor" href="#instructions" aria-label="Permalink to &quot;Instructions&quot;">​</a></h1><p>Agent instructions form the always-on system prompt and reach the model on every turn. A root agent requires them; a subagent may inline <code>instructions</code> in <code>agent.ts</code> instead.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Form</th><th>Use it when</th></tr></thead><tbody><tr><td><code>bot/instructions.md</code></td><td>Plain Markdown for most agents</td></tr><tr><td><code>bot/instructions.ts</code></td><td>Generated prompts. Default-export <code>defineInstructions({ markdown })</code> or a plain string</td></tr><tr><td><code>bot/instructions/</code> directory</td><td>A long prompt split across files, composed in filename order</td></tr></tbody></table><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/instructions.ts</span></span>
+import{_ as t,c as i,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function l(o,s,r,h,d,p){return e(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="instructions" tabindex="-1">Instructions <a class="header-anchor" href="#instructions" aria-label="Permalink to &quot;Instructions&quot;">​</a></h1><p>Agent instructions form the always-on system prompt and reach the model on every turn. A root agent requires them; a subagent may inline <code>instructions</code> in <code>agent.ts</code> instead.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Form</th><th>Use it when</th></tr></thead><tbody><tr><td><code>bot/instructions.md</code></td><td>Plain Markdown for most agents</td></tr><tr><td><code>bot/instructions.ts</code></td><td>Generated prompts. Default-export <code>defineInstructions({ markdown })</code> or a plain string</td></tr><tr><td><code>bot/instructions/</code> directory</td><td>A long prompt split across files, composed in filename order</td></tr></tbody></table><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/instructions.ts</span></span>
 <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/bdk&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;"> defineInstructions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -11,4 +11,4 @@ import{_ as t,c as a,o as i,a3 as e}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Match your review to the complexity it reports.</span></span>
 <span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Never approve a draft.</span></span>
 <span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><p>Name the tools and the decision rule (&quot;use X before answering about Y&quot;), not general encouragement. State the output contract, including length, format, and fences, so your <a href="./../evals.html">evals</a> can gate it. Put multi-step workflows the model only sometimes needs in <code>bot/skills/</code>; they load on demand and keep the always-on prompt small.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./skills.html">Skills</a>: procedures the model loads only when relevant</li><li><a href="./agent-config.html">Agent config</a>: the file next to this one</li><li><a href="./../hillclimbing.html">Hillclimbing</a>: iterating on instructions with evidence</li></ul>`,14)])])}const u=t(n,[["render",l]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><p>Name the tools and the decision rule (&quot;use X before answering about Y&quot;), not general encouragement. State the output contract, including length, format, and fences, so your <a href="./../evals.html">evals</a> can gate it. Put multi-step workflows the model only sometimes needs in <code>bot/skills/</code>; they load on demand and keep the always-on prompt small.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./skills.html">Skills</a>: procedures the model loads only when relevant</li><li><a href="./agent-config.html">Agent config</a>: the file next to this one</li><li><a href="./../hillclimbing.html">Hillclimbing</a>: iterating on instructions with evidence</li></ul>`,13)])])}const u=t(n,[["render",l]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_instructions.md.Bdwscs4G.lean.js → reference_instructions.md.DrcHZXig.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o as i,a3 as e}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function l(o,s,r,h,d,p){return i(),a("div",null,[...s[0]||(s[0]=[e("",14)])])}const u=t(n,[["render",l]]);export{k as __pageData,u as default};
+import{_ as t,c as i,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function l(o,s,r,h,d,p){return e(),i("div",null,[...s[0]||(s[0]=[a("",13)])])}const u=t(n,[["render",l]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_playground.md.1hx0gcIu.js

@@ -0,0 +1 @@
+import{_ as t,c as a,o,a3 as r}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),d={name:"reference/playground.md"};function s(n,e,l,c,i,h){return o(),a("div",null,[...e[0]||(e[0]=[r('<h1 id="playground" tabindex="-1">Playground <a class="header-anchor" href="#playground" aria-label="Permalink to &quot;Playground&quot;">​</a></h1><p><code>bdk serve</code> enables a web playground at <code>http://127.0.0.1:3000/&lt;slug&gt;/playground</code> (or <code>/playground</code> in single mode). In multi-agent mode, each agent has its own playground, and <code>/</code> lists them all.</p><h2 id="playground-surfaces" tabindex="-1">Playground surfaces <a class="header-anchor" href="#playground-surfaces" aria-label="Permalink to &quot;Playground surfaces&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Surface</th><th>What you can do</th></tr></thead><tbody><tr><td>Chat</td><td>Talk to the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state</td></tr><tr><td>Slash commands</td><td>Custom channel routes without path parameters become composer commands; GitHub and Slack ingress routes are excluded. A <code>drive</code> route becomes <code>/drive &lt;pr-url&gt;</code>, with <code>/help</code> and autocomplete</td></tr><tr><td>Try</td><td>Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint, copies curl, and opens a session when the route creates one</td></tr><tr><td>Runs</td><td>Browse the sessions you own and eval runs. Search by title or identifier; open sessions in Chat, Trace, or Raw and eval runs in Evals</td></tr><tr><td>Approvals</td><td>Parked <code>needsApproval</code> tool calls render Approve / Deny buttons</td></tr><tr><td>Evals</td><td>List and run filesystem evals from the browser</td></tr><tr><td>Agent</td><td>Inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks</td></tr><tr><td>Raw</td><td>Inspect the selected session&#39;s event stream</td></tr><tr><td>Logs</td><td>Recent server log lines, polled from <code>GET /v1/logs</code></td></tr></tbody></table><p>In <code>--dev</code> on loopback, or with <code>--allow-anonymous</code>, the session list includes every principal.</p><h2 id="remote-access" tabindex="-1">Remote access <a class="header-anchor" href="#remote-access" aria-label="Permalink to &quot;Remote access&quot;">​</a></h2><p>The default <code>localDevStrict()</code> auth admits direct loopback calls only and rejects proxy-forwarding headers, so a tunnel or LAN address won&#39;t work until you pass <code>--bearer-token &lt;secret&gt;</code> (or <code>serve(dir, { authToken })</code>). Open the playground on the remote device and paste the token into the token field in the navbar. <code>--allow-anonymous</code> is the demo-only alternative for trusted networks.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./http-api.html">HTTP API</a>: the HTTP surface the playground uses</li><li><a href="./sessions.html">Sessions and streaming</a>: the streams it renders</li><li><a href="./tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: the approval buttons in context</li></ul>',9)])])}const m=t(d,[["render",s]]);export{p as __pageData,m as default};

package/dist/docs/assets/{reference_playground.md.BdQzRJc2.lean.js → reference_playground.md.1hx0gcIu.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o,a3 as r}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),d={name:"reference/playground.md"};function s(n,e,l,c,i,h){return o(),a("div",null,[...e[0]||(e[0]=[r("",10)])])}const m=t(d,[["render",s]]);export{p as __pageData,m as default};
+import{_ as t,c as a,o,a3 as r}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),d={name:"reference/playground.md"};function s(n,e,l,c,i,h){return o(),a("div",null,[...e[0]||(e[0]=[r("",9)])])}const m=t(d,[["render",s]]);export{p as __pageData,m as default};

package/dist/docs/assets/{reference_project-layout.md.CpLQ9j4K.js → reference_project-layout.md.C2JMRh7p.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as o,o as s,a3 as a}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Project layout","description":"The canonical bot/ folder layout and its path-derived naming rules.","frontmatter":{"title":"Project layout","description":"The canonical bot/ folder layout and its path-derived naming rules."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,c,i,l,p){return s(),o("div",null,[...e[0]||(e[0]=[a(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Grok Bot Development Kit (BDK) builds a project by walking the filesystem under <code>bot/</code>. The path a file lands in determines how BDK loads it.</p><p>Existing projects rooted at <code>agent/</code> remain supported.</p><h2 id="folder-structure" tabindex="-1">Folder structure <a class="header-anchor" href="#folder-structure" aria-label="Permalink to &quot;Folder structure&quot;">​</a></h2><p>For the capabilities below, identity comes from the path.</p><table tabindex="0"><thead><tr><th>Path under <code>bot/</code></th><th>Resolves to</th></tr></thead><tbody><tr><td><code>tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>host-connections/anytool.ts</code></td><td>Host MCP connection <code>anytool</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>extensions/ci.ts</code></td><td>extension mount <code>ci</code>; its contributions become <code>ci__&lt;name&gt;</code></td></tr><tr><td><code>extensions/notion.ts</code></td><td>Cursor plugin mount <code>notion</code> (<code>cursorPlugin</code>); its skills, agents, and MCP servers become <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-tree" tabindex="-1">Project tree <a class="header-anchor" href="#project-tree" aria-label="Permalink to &quot;Project tree&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
+import{_ as t,c as o,o as s,a3 as a}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Project layout","description":"The canonical bot/ folder layout and its path-derived naming rules.","frontmatter":{"title":"Project layout","description":"The canonical bot/ folder layout and its path-derived naming rules."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,c,i,l,p){return s(),o("div",null,[...e[0]||(e[0]=[a(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Grok Bot Development Kit (BDK) builds a project by walking the filesystem under <code>bot/</code>. The path a file lands in determines how BDK loads it.</p><p>Existing projects rooted at <code>agent/</code> remain supported.</p><h2 id="folder-structure" tabindex="-1">Folder structure <a class="header-anchor" href="#folder-structure" aria-label="Permalink to &quot;Folder structure&quot;">​</a></h2><p>For the capabilities below, identity comes from the path.</p><table tabindex="0"><thead><tr><th>Path under <code>bot/</code></th><th>Resolves to</th></tr></thead><tbody><tr><td><code>tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>host-connections/inventory.ts</code></td><td>Host MCP connection <code>inventory</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>extensions/ci.ts</code></td><td>extension mount <code>ci</code>; its contributions become <code>ci__&lt;name&gt;</code></td></tr><tr><td><code>extensions/notion.ts</code></td><td>Cursor plugin mount <code>notion</code> (<code>cursorPlugin</code>); its skills, agents, and MCP servers become <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-tree" tabindex="-1">Project tree <a class="header-anchor" href="#project-tree" aria-label="Permalink to &quot;Project tree&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
 <span class="line"><span>├── package.json</span></span>
 <span class="line"><span>├── bot/</span></span>
 <span class="line"><span>│   ├── agent.ts               # model and local harness config</span></span>
@@ -10,7 +10,7 @@ import{_ as t,c as o,o as s,a3 as a}from"./chunks/framework.BNw1pucY.js";const u
 <span class="line"><span>│   ├── mcp-connections/</span></span>
 <span class="line"><span>│   │   └── linear.ts          # tools from external MCP servers</span></span>
 <span class="line"><span>│   ├── host-connections/</span></span>
-<span class="line"><span>│   │   └── anytool.ts         # privileged MCP, host tools only</span></span>
+<span class="line"><span>│   │   └── inventory.ts       # host-only MCP tools</span></span>
 <span class="line"><span>│   ├── subagents/</span></span>
 <span class="line"><span>│   │   └── reviewer/</span></span>
 <span class="line"><span>│   │       ├── agent.ts</span></span>

package/dist/docs/assets/{reference_prompt.md.BQZB4eaV.js → reference_prompt.md.DqPh71XN.js}

@@ -1,9 +1,9 @@
-import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values.","frontmatter":{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function r(p,s,l,h,o,d){return a(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="prompt-strings" tabindex="-1">Prompt strings <a class="header-anchor" href="#prompt-strings" aria-label="Permalink to &quot;Prompt strings&quot;">​</a></h1><p>The <code>prompt</code> template tag keeps multi-line strings aligned with the surrounding TypeScript while returning dedented text. Use it for tool descriptions, reminder prompts, channel context, and errors. Import it from the package root or the dedicated entrypoint:</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;"> { prompt } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or: import { prompt } from &quot;@cursor/bdk/prompt&quot;;</span></span></code></pre></div><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="dedented-strings" tabindex="-1">Dedented strings <a class="header-anchor" href="#dedented-strings" aria-label="Permalink to &quot;Dedented strings&quot;">​</a></h2><p><code>prompt</code> returns one string. It removes the common leading whitespace and one newline immediately after the opening backtick.</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;">throw</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values.","frontmatter":{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function r(p,s,l,h,o,d){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="prompt-strings" tabindex="-1">Prompt strings <a class="header-anchor" href="#prompt-strings" aria-label="Permalink to &quot;Prompt strings&quot;">​</a></h1><p>The <code>prompt</code> template tag keeps multi-line strings aligned with the surrounding TypeScript while returning dedented text. Use it for tool descriptions, reminder prompts, channel context, and errors. Import it from the package root or the dedicated entrypoint:</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;"> { prompt } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or: import { prompt } from &quot;@cursor/bdk/prompt&quot;;</span></span></code></pre></div><h2 id="dedented-strings" tabindex="-1">Dedented strings <a class="header-anchor" href="#dedented-strings" aria-label="Permalink to &quot;Dedented strings&quot;">​</a></h2><p><code>prompt</code> returns one string. It removes the common leading whitespace and one newline immediately after the opening backtick.</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;">throw</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  It is outside business hours (Mon-Fri 9am-5pm ET).</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Use request_author_approval, or pass approval=human_request.</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Blank lines inside the body are preserved. Relative indentation after the common prefix is preserved, so nested lists keep their shape.</p><p>When interpolating multi-line values (for example a list of services), give those lines the same indent as the <code>prompt</code> body so dedent stays consistent.</p><h2 id="line-arrays" tabindex="-1">Line arrays <a class="header-anchor" href="#line-arrays" aria-label="Permalink to &quot;Line arrays&quot;">​</a></h2><p><code>prompt.lines</code> applies the same rules and returns <code>string[]</code>, with one entry per line. Use it when an API accepts separate context lines:</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;">context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: prompt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lines</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Merged PR detected: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pr</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;">} by \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">author</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Call plan_deploy, then follow its nextStep.</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span></code></pre></div><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./tools.html">Tools</a></li><li><a href="./channels.html">Channels</a></li></ul>`,14)])])}const g=e(n,[["render",r]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span></code></pre></div><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./tools.html">Tools</a></li><li><a href="./channels.html">Channels</a></li></ul>`,13)])])}const g=e(n,[["render",r]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_prompt.md.BQZB4eaV.lean.js → reference_prompt.md.DqPh71XN.lean.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values.","frontmatter":{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function r(p,s,l,h,o,d){return a(),i("div",null,[...s[0]||(s[0]=[t("",14)])])}const g=e(n,[["render",r]]);export{c as __pageData,g as default};
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values.","frontmatter":{"title":"Prompt strings","description":"Write indented multi-line strings without carrying source indentation into their values."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function r(p,s,l,h,o,d){return t(),i("div",null,[...s[0]||(s[0]=[a("",13)])])}const g=e(n,[["render",r]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_schedules.md.BVU5EFbz.js → reference_schedules.md.BuJ8fgMa.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),n={name:"reference/schedules.md"};function h(l,s,d,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>An agent can act without an inbound message in two ways. A schedule is deploy-time cron: &quot;every weekday at 09:00, summarize open incidents.&quot; A reminder is a runtime wake bound to one conversation: &quot;re-check this PR&#39;s CI in two hours.&quot; Schedules live in the filesystem; reminders are created by running code.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><p>Cron expressions are standard 5-field, evaluated in UTC with minute granularity.</p><h3 id="markdown-schedules" tabindex="-1">Markdown schedules <a class="header-anchor" href="#markdown-schedules" aria-label="Permalink to &quot;Markdown schedules&quot;">​</a></h3><p>A markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),n={name:"reference/schedules.md"};function h(l,s,d,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>An agent can act without an inbound message in two ways. A schedule is deploy-time cron: &quot;every weekday at 09:00, summarize open incidents.&quot; A reminder is a runtime wake bound to one conversation: &quot;re-check this PR&#39;s CI in two hours.&quot; Schedules live in the filesystem; reminders are created by running code.</p><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><p>Cron expressions are standard 5-field, evaluated in UTC with minute granularity.</p><h3 id="markdown-schedules" tabindex="-1">Markdown schedules <a class="header-anchor" href="#markdown-schedules" aria-label="Permalink to &quot;Markdown schedules&quot;">​</a></h3><p>A markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cron: &quot;0 9 * * 1-5&quot;</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"></span>
@@ -44,4 +44,4 @@ import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  handler: ciRecheck,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: { prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/checkout/pull/42&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>Use an anonymous <code>run</code> handler only for legacy projects that can re-arm it after a restart. New projects should use a named handler.</p><table tabindex="0"><thead><tr><th>Form</th><th>What it does</th><th>After a restart</th></tr></thead><tbody><tr><td>Prompt</td><td>Sends <code>prompt</code> into the session. <code>until</code> is the standing cancellation condition for the model</td><td>Stays armed</td></tr><tr><td>Named handler</td><td>Runs a discovered handler with serializable <code>args</code>; it starts a model turn only if the handler calls <code>followup</code></td><td>Stays armed</td></tr><tr><td>Anonymous <code>run</code></td><td>Host handler returns <code>stop</code>, <code>skip</code>, or <code>delivered</code> per tick; it starts a model turn only if it calls <code>followup</code></td><td>Must be re-armed</td></tr></tbody></table><p>The same API is <code>host.reminders</code> on channel handlers, tools, and schedule runs. <code>builtinTools: { reminders: true }</code> adds <code>reminders_create</code>, <code>reminders_list</code>, and <code>reminders_cancel</code> on the current conversation; see <a href="./agent-config.html#built-in-tools">Agent config: built-in tools</a>.</p><p><code>--dev</code> does not auto-fire reminders. Dispatch one by hand:</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:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/reminders</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">             # list</span></span>
-<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/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/reminders/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # fire one</span></span></code></pre></div><p><code>handle.dispatchReminder(id)</code> is the programmatic equivalent.</p><p>Cancel reminders when their subject dies, for example on <code>pull_request.closed</code>. Keep wake prompts generic so the agent re-reads live state instead of replaying a stale payload.</p><h2 id="schedules-vs-reminders" tabindex="-1">Schedules vs reminders <a class="header-anchor" href="#schedules-vs-reminders" aria-label="Permalink to &quot;Schedules vs reminders&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>at deploy time, <code>bot/schedules/*</code></td><td>at runtime, <code>createReminder</code> / <code>host.reminders</code></td></tr><tr><td>Scope</td><td>global to the agent</td><td>one channel continuation (one conversation)</td></tr><tr><td>Session</td><td>starts a new task session (or hands off through <code>receive</code>)</td><td>wakes an existing conversation</td></tr><tr><td>Cadence</td><td>cron (UTC)</td><td><code>every</code>, <code>cron</code>, <code>delay</code>, or <code>at</code></td></tr><tr><td>Dev mode</td><td>manual dispatch only</td><td>manual dispatch only (timers off)</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./channels.html">Channels</a>: <code>receive</code> and the delivery events</li><li><a href="./../guides/github.html">GitHub guide</a>: reminders in a real webhook loop</li><li><a href="./http-api.html#dev-mode-routes">HTTP API</a>: the dev dispatch routes</li></ul>`,34)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
+<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/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/reminders/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # fire one</span></span></code></pre></div><p><code>handle.dispatchReminder(id)</code> is the programmatic equivalent.</p><p>Cancel reminders when their subject dies, for example on <code>pull_request.closed</code>. Keep wake prompts generic so the agent re-reads live state instead of replaying a stale payload.</p><h2 id="schedules-vs-reminders" tabindex="-1">Schedules vs reminders <a class="header-anchor" href="#schedules-vs-reminders" aria-label="Permalink to &quot;Schedules vs reminders&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>at deploy time, <code>bot/schedules/*</code></td><td>at runtime, <code>createReminder</code> / <code>host.reminders</code></td></tr><tr><td>Scope</td><td>global to the agent</td><td>one channel continuation (one conversation)</td></tr><tr><td>Session</td><td>starts a new task session (or hands off through <code>receive</code>)</td><td>wakes an existing conversation</td></tr><tr><td>Cadence</td><td>cron (UTC)</td><td><code>every</code>, <code>cron</code>, <code>delay</code>, or <code>at</code></td></tr><tr><td>Dev mode</td><td>manual dispatch only</td><td>manual dispatch only (timers off)</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./channels.html">Channels</a>: <code>receive</code> and the delivery events</li><li><a href="./../guides/github.html">GitHub guide</a>: reminders in a real webhook loop</li><li><a href="./http-api.html#dev-mode-routes">HTTP API</a>: the dev dispatch routes</li></ul>`,33)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_schedules.md.BVU5EFbz.lean.js → reference_schedules.md.BuJ8fgMa.lean.js}

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

package/dist/docs/assets/reference_sessions.md.CM5zo3w4.js

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

package/dist/docs/assets/{reference_sessions.md.DeRUItHD.lean.js → reference_sessions.md.CM5zo3w4.lean.js}

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

package/dist/docs/assets/{reference_skills.md.Cy00QMKS.js → reference_skills.md.ClkMoQsV.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),l={name:"reference/skills.md"};function n(h,s,o,r,d,p){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to &quot;Skills&quot;">​</a></h1><p>A skill is an on-demand procedure following the <code>SKILL.md</code> convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Skills support three authoring forms.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>bot/skills/&lt;name&gt;.md</code></td><td>Static Markdown. Optional <code>description</code> frontmatter; the first body line is the fallback.</td></tr><tr><td><code>bot/skills/&lt;name&gt;/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files (<code>references/…</code>). Requires <code>description</code> frontmatter.</td></tr><tr><td><code>bot/skills/&lt;name&gt;.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@cursor/bdk/skills</code>.</td></tr></tbody></table><p>Use flat Markdown for static content:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
+import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),l={name:"reference/skills.md"};function n(h,s,r,o,d,p){return t(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to &quot;Skills&quot;">​</a></h1><p>A skill is an on-demand procedure following the <code>SKILL.md</code> convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Skills support three authoring forms.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>bot/skills/&lt;name&gt;.md</code></td><td>Static Markdown. Optional <code>description</code> frontmatter; the first body line is the fallback.</td></tr><tr><td><code>bot/skills/&lt;name&gt;/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files (<code>references/…</code>). Requires <code>description</code> frontmatter.</td></tr><tr><td><code>bot/skills/&lt;name&gt;.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@cursor/bdk/skills</code>.</td></tr></tbody></table><p>Use flat Markdown for static content:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">description: Use when a pull request needs a structured approval checklist.</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
 <span class="line"></span>
@@ -12,4 +12,4 @@ import{_ as i,c as e,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Research unfamiliar topics before answering.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Gather evidence first, then answer with the key facts.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  files: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;references/checklist.md&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;# Checklist</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">- Find sources.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="skill-delivery" tabindex="-1">Skill delivery <a class="header-anchor" href="#skill-delivery" aria-label="Permalink to &quot;Skill delivery&quot;">​</a></h2><p>Skills land in the session workspace at <code>.cursor/skills/&lt;name&gt;/SKILL.md</code>, and the harness advertises and loads them natively.</p><h2 id="skills-instructions-and-tools" tabindex="-1">Skills, instructions, and tools <a class="header-anchor" href="#skills-instructions-and-tools" aria-label="Permalink to &quot;Skills, instructions, and tools&quot;">​</a></h2><p>Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to follow something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.</p><p>A good skill description is a routing rule, not a title. Say when to use it, like &quot;Use when a pull request needs a structured approval checklist,&quot; because the description is all the model sees before deciding to load it.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./instructions.html">Instructions</a>: what stays always-on</li><li><a href="./tools.html">Tools</a>: when prose needs to become code</li><li><a href="./extensions.html">Extensions</a>: skills installed as a package under a namespace</li><li><a href="./project-layout.html">Project layout</a>: where skills sit in the tree</li></ul>`,17)])])}const u=i(l,[["render",n]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="skill-delivery" tabindex="-1">Skill delivery <a class="header-anchor" href="#skill-delivery" aria-label="Permalink to &quot;Skill delivery&quot;">​</a></h2><p>Skills land in the session workspace at <code>.cursor/skills/&lt;name&gt;/SKILL.md</code>, and the harness advertises and loads them natively.</p><h2 id="skills-instructions-and-tools" tabindex="-1">Skills, instructions, and tools <a class="header-anchor" href="#skills-instructions-and-tools" aria-label="Permalink to &quot;Skills, instructions, and tools&quot;">​</a></h2><p>Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to follow something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.</p><p>A good skill description is a routing rule, not a title. Say when to use it, like &quot;Use when a pull request needs a structured approval checklist,&quot; because the description is all the model sees before deciding to load it.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./instructions.html">Instructions</a>: what stays always-on</li><li><a href="./tools.html">Tools</a>: when prose needs to become code</li><li><a href="./extensions.html">Extensions</a>: skills installed as a package under a namespace</li><li><a href="./project-layout.html">Project layout</a>: where skills sit in the tree</li></ul>`,16)])])}const u=i(l,[["render",n]]);export{c as __pageData,u as default};

package/dist/docs/assets/{reference_skills.md.Cy00QMKS.lean.js → reference_skills.md.ClkMoQsV.lean.js}

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

package/dist/docs/assets/{reference_subagents.md.B8oyeXOI.js → reference_subagents.md.gmPt5J-M.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as a,o as t,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(l,e,d,r,c,p){return t(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one lives under <code>bot/subagents/&lt;id&gt;/</code> with a required <code>agent.ts</code>. Add <code>instructions.md</code> or inline <code>instructions</code> in <code>agent.ts</code> for a custom prompt. The parent model delegates through the <code>task</code> tool, and the stream records <code>subagent.called</code> and <code>subagent.completed</code>.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bot/subagents/researcher/</span></span>
+import{_ as s,c as a,o as t,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(l,e,d,r,c,h){return t(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one lives under <code>bot/subagents/&lt;id&gt;/</code> with a required <code>agent.ts</code>. Add <code>instructions.md</code> or inline <code>instructions</code> in <code>agent.ts</code> for a custom prompt. The parent model delegates through the <code>task</code> tool, and the stream records <code>subagent.called</code> and <code>subagent.completed</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bot/subagents/researcher/</span></span>
 <span class="line"><span>├── agent.ts            # description (required), model (optional)</span></span>
 <span class="line"><span>└── instructions.md     # optional custom system prompt</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/subagents/researcher/agent.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -7,4 +7,4 @@ import{_ as s,c as a,o as t,a3 as n}from"./chunks/framework.BNw1pucY.js";const u
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description:</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;Background research: climate history, records, comparisons across many cities.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // model: omit to inherit the parent&#39;s model</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="subagent-rules" tabindex="-1">Subagent rules <a class="header-anchor" href="#subagent-rules" aria-label="Permalink to &quot;Subagent rules&quot;">​</a></h2><p><code>description</code> is required. The parent model uses it to decide whether to delegate, so write it as a routing rule (&quot;Background research: …&quot;), following the same discipline as a <a href="./skills.html">skill</a> description. <code>model</code> is optional; omit it to inherit the parent&#39;s model, or set it to run the specialist on a different model.</p><p>Subagents inherit the parent&#39;s execution surface. Every per-subagent capability directory is reported as a warning and ignored: <code>tools/</code>, <code>skills/</code>, <code>extensions/</code>, <code>mcp-connections/</code>, <code>host-connections/</code>, <code>channels/</code>, <code>schedules/</code>, <code>reminders/</code>, <code>hooks/</code>, <code>sandbox/</code>, and nested <code>subagents/</code>.</p><p>Delegation needs both halves: the description makes it possible, and the parent&#39;s <a href="./instructions.html">instructions</a> make it happen. &quot;When a request needs background research, delegate to the <code>researcher</code> subagent.&quot; The parent routes; the specialist executes.</p><h2 id="subagents-and-peers" tabindex="-1">Subagents and peers <a class="header-anchor" href="#subagents-and-peers" aria-label="Permalink to &quot;Subagents and peers&quot;">​</a></h2><p>Subagents split one job into roles inside a single agent. When the specialist is independently useful, with its own tools, sessions, and playground, make it a full agent. See <a href="./../guides/agent-to-agent.html#peer-or-subagent">Peer agents</a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./skills.html">Skills</a>: when a procedure is enough and a child agent is overkill</li><li><a href="./../guides/agent-to-agent.html">Peer agents</a>: independently useful specialists</li><li><a href="./agent-config.html#harness-tools">Agent config</a>: <code>&quot;task&quot;</code> on the parent&#39;s tool allowlist</li></ul>`,13)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="subagent-rules" tabindex="-1">Subagent rules <a class="header-anchor" href="#subagent-rules" aria-label="Permalink to &quot;Subagent rules&quot;">​</a></h2><p><code>description</code> is required. The parent model uses it to decide whether to delegate, so write it as a routing rule (&quot;Background research: …&quot;), following the same discipline as a <a href="./skills.html">skill</a> description. <code>model</code> is optional; omit it to inherit the parent&#39;s model, or set it to run the specialist on a different model.</p><p>Subagents inherit the parent&#39;s execution surface. Every per-subagent capability directory is reported as a warning and ignored: <code>tools/</code>, <code>skills/</code>, <code>extensions/</code>, <code>mcp-connections/</code>, <code>host-connections/</code>, <code>channels/</code>, <code>schedules/</code>, <code>reminders/</code>, <code>hooks/</code>, <code>sandbox/</code>, and nested <code>subagents/</code>.</p><p>Delegation needs both halves: the description makes it possible, and the parent&#39;s <a href="./instructions.html">instructions</a> make it happen. &quot;When a request needs background research, delegate to the <code>researcher</code> subagent.&quot; The parent routes; the specialist executes.</p><h2 id="subagents-and-peers" tabindex="-1">Subagents and peers <a class="header-anchor" href="#subagents-and-peers" aria-label="Permalink to &quot;Subagents and peers&quot;">​</a></h2><p>Subagents split one job into roles inside a single agent. When the specialist is independently useful, with its own tools, sessions, and playground, make it a full agent. See <a href="./../guides/agent-to-agent.html#peer-or-subagent">Peer agents</a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./skills.html">Skills</a>: when a procedure is enough and a child agent is overkill</li><li><a href="./../guides/agent-to-agent.html">Peer agents</a>: independently useful specialists</li><li><a href="./agent-config.html#harness-tools">Agent config</a>: <code>&quot;task&quot;</code> on the parent&#39;s tool allowlist</li></ul>`,12)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_subagents.md.B8oyeXOI.lean.js → reference_subagents.md.gmPt5J-M.lean.js}

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