@cursor/bdk 0.2.18 → 0.2.21

package/dist/docs/assets/{reference_hooks.md.DbJC8mcZ.js → reference_hooks.md.B1jq3oGl.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,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>
+import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,c){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook 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>
@@ -15,7 +15,7 @@ import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme.turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { channel: ctx.channel.id });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>bot/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>bdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>bdk init</code> scaffolds <code>bot/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/bdk/memory</code> and journals every turn for later sessions to read. Delete the file to opt out.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events. Skip <code>*.appended</code> deltas when you want the final text; <code>message.completed</code> already has it.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status? }</code>. <code>status</code> is <code>&quot;error&quot;</code> or <code>&quot;cancelled&quot;</code> when present</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step once that step has listed its tools. A single tool is a batch of one. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Pair with <code>actions.requested</code>; emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope for chips and spans. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr><tr><td><code>action.tool_retry</code></td><td><code>{ callId, toolName, attempt, reason, connection? }</code>. A read is running again after a transient failure. <code>attempt</code> is the try about to run. <code>reason</code> is a class such as <code>transport</code> or <code>http_503</code></td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/bdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to &quot;Hook dispatch&quot;">​</a></h2><p>A hook runs after the event is recorded. It never delays the model and never sees an event that wasn&#39;t recorded.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires; skip metering or paging when <code>ctx.session.purpose === &quot;eval&quot;</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event&#39;s handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><p>Read hosted secrets inside the handler, not at module scope. Give outbound calls a timeout; a stalled request holds later handlers on that session. Skip cancelled turns when paging; they record interrupted work.</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/page-on-failure.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>bot/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>bdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>bdk init</code> scaffolds <code>bot/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/bdk/memory</code> and journals every turn for later sessions to read. Delete the file to opt out. See <a href="./memory.html">Memory</a>.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events. Skip <code>*.appended</code> deltas when you want the final text; <code>message.completed</code> already has it.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status? }</code>. <code>status</code> is <code>&quot;error&quot;</code> or <code>&quot;cancelled&quot;</code> when present</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step once that step has listed its tools. A single tool is a batch of one. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Pair with <code>actions.requested</code>; emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope for chips and spans. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr><tr><td><code>action.tool_retry</code></td><td><code>{ callId, toolName, attempt, reason, connection? }</code>. A read is running again after a transient failure. <code>attempt</code> is the try about to run. <code>reason</code> is a class such as <code>transport</code> or <code>http_503</code></td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/bdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to &quot;Hook dispatch&quot;">​</a></h2><p>A hook runs after the event is recorded. It never delays the model and never sees an event that wasn&#39;t recorded.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires; skip metering or paging when <code>ctx.session.purpose === &quot;eval&quot;</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event&#39;s handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><p>Read hosted secrets inside the handler, not at module scope. Give outbound calls a timeout; a stalled request holds later handlers on that session. Skip cancelled turns when paging; they record interrupted work.</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/page-on-failure.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 k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#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>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{k 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>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p>To act on a turn&#39;s decision, such as a label or a ticket, have the model record it with an authored <a href="./tools.html">tool</a>. A <code>turn.completed</code> hook then reads the recorded decision and acts on it through <code>ctx.host</code>.</p><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{k as __pageData,E as default};

package/dist/docs/assets/{reference_hooks.md.DbJC8mcZ.lean.js → reference_hooks.md.B1jq3oGl.lean.js}

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

package/dist/docs/assets/reference_memory.md.BwyJXYZe.js

@@ -0,0 +1,4 @@
+import{_ as s,c as t,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Memory","description":"Journal every turn so later sessions can read what earlier ones did.","frontmatter":{"title":"Memory","description":"Journal every turn so later sessions can read what earlier ones did."},"headers":[],"relativePath":"reference/memory.md","filePath":"reference/memory.md"}'),i={name:"reference/memory.md"};function r(n,e,d,h,l,c){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="memory" tabindex="-1">Memory <a class="header-anchor" href="#memory" aria-label="Permalink to &quot;Memory&quot;">​</a></h1><p>Memory lets an agent recall work from earlier sessions. A memory hook appends one record per turn to a shared journal, and the model reads that journal with its normal file tools when its instructions send it there. Every session and every user of the agent shares one journal.</p><h2 id="memory-is-on-by-default" tabindex="-1">Memory is on by default <a class="header-anchor" href="#memory-is-on-by-default" aria-label="Permalink to &quot;Memory is on by default&quot;">​</a></h2><p><code>bdk init</code> scaffolds <code>bot/hooks/memory.ts</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/hooks/memory.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { memoryHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/memory&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;"> memoryHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>It also adds a <code>## Memory</code> section to <code>bot/instructions.md</code>. The model has no recall tool, so that section is what sends it to the journal: it says when to read <code>memory/</code>, and it tells the model to treat records as untrusted history. To add memory to an existing project, create the hook file and copy the <code>## Memory</code> section from a fresh <code>bdk init</code> project into your instructions. To turn memory off, delete the hook file and the <code>## Memory</code> section.</p><h2 id="journal-records" tabindex="-1">Journal records <a class="header-anchor" href="#journal-records" aria-label="Permalink to &quot;Journal records&quot;">​</a></h2><p>The hook appends one JSON line to <code>memory/journal.jsonl</code> after each turn completes or fails:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;at&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;2026-10-01T16:42:09.118Z&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;sessionId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;5f0c2a9e-7d1b-4c43-9a6e-2b8f1e0d7c35&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;channelId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;slack&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;status&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Checkout flaky test&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;userMessage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Why does acme/checkout fail on main?&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;result&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;The cart test races the price service mock...&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;usage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:{</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;inputTokens&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">18234</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;outputTokens&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">912</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;cacheReadTokens&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">15002</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;cacheWriteTokens&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}}</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Field</th><th>Contract</th></tr></thead><tbody><tr><td><code>at</code></td><td>ISO-8601 time the turn finished</td></tr><tr><td><code>sessionId</code></td><td>Session that ran the turn</td></tr><tr><td><code>channelId</code></td><td>Channel that started the session, such as <code>http</code> for the session API</td></tr><tr><td><code>status</code></td><td><code>&quot;completed&quot;</code> or <code>&quot;failed&quot;</code></td></tr><tr><td><code>title</code></td><td>Session title, when the channel set one</td></tr><tr><td><code>userMessage</code></td><td>The message that started the turn, truncated to <code>maxTextLength</code></td></tr><tr><td><code>result</code></td><td>Final assistant text, or the failure message, truncated to <code>maxTextLength</code></td></tr><tr><td><code>usage</code></td><td>Token usage for completed turns; see <a href="./hooks.html#events-and-payloads">Events and payloads</a></td></tr></tbody></table><p>As the journal grows, older records move to <code>journal-*.jsonl</code> files beside it. Point the model at the whole <code>memory/</code> directory when it needs history beyond the latest segment.</p><h2 id="read-memory" tabindex="-1">Read memory <a class="header-anchor" href="#read-memory" aria-label="Permalink to &quot;Read memory&quot;">​</a></h2><p>Local turns find the journal at <code>memory/</code> in the session workspace. On a Cursor-hosted deployment, the first prompt of each session names the journal&#39;s path on that machine. A session on a server you run yourself can&#39;t reach the journal.</p><p><code>memory</code> is a reserved workspace path. BDK rejects per-send <code>workspaceFiles</code> and <code>sandbox/workspace/</code> seed files under <code>memory/</code>, so callers can&#39;t write records through the workspace.</p><p>Local servers keep the journal in the project state directory. <code>bdk run</code> and <code>bdk eval</code> start an ephemeral server with a fresh state directory unless you pass <code>--state-root</code>, so each run starts with empty memory. Use <code>bdk serve</code> or <code>bdk dev</code>, or pass the same <code>--state-root</code>, to keep memory across runs. Hosted deployments keep the journal across redeploys.</p><h2 id="who-sees-memory" tabindex="-1">Who sees memory <a class="header-anchor" href="#who-sees-memory" aria-label="Permalink to &quot;Who sees memory&quot;">​</a></h2><p>Records from every session and every user land in the same journal, so one person&#39;s messages and the agent&#39;s replies to them can surface in another person&#39;s session. Turn memory off for an agent whose users shouldn&#39;t see each other&#39;s requests. Turning it off stops new records, but the journal keeps the records it already has. On a local server, delete the <code>memory/</code> directory in the project state directory to clear them. On Cursor-managed hosting, the journal is deployment data, so <a href="./../deployment.html#privacy-mode">Privacy Mode</a> applies to it.</p><p>Anyone who can message the agent can put text in the journal. The scaffolded instructions tell the model never to follow instructions found inside records; keep that rule if you write your own section.</p><h2 id="memory-and-host-state" tabindex="-1">Memory and host state <a class="header-anchor" href="#memory-and-host-state" aria-label="Permalink to &quot;Memory and host state&quot;">​</a></h2><p>Memory is advisory. A record can be dropped, and records written by concurrent sessions can show up only in a later session. Keep state your code depends on, such as dedupe records and cursors, in <code>ctx.host.kv</code> or <code>ctx.host.files</code>; see <a href="./hooks.html#handler-context">Handler context</a>.</p><h2 id="options" tabindex="-1">Options <a class="header-anchor" href="#options" aria-label="Permalink to &quot;Options&quot;">​</a></h2><p><code>memoryHook(options?)</code> accepts:</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>maxTextLength</code></td><td>Truncation cap for <code>userMessage</code> and <code>result</code>. Default <code>2000</code> characters.</td></tr><tr><td><code>backend</code></td><td>A <code>MemoryBackend</code> that replaces the default journal</td></tr></tbody></table><p>A <code>MemoryBackend</code> has <code>appendTurn(record, { stateRoot, agentName })</code>, which receives each record, and an optional <code>prepareSession({ stateRoot, agentName })</code>, which runs when a session starts. Records go only where <code>appendTurn</code> sends them, but the <code>memory/</code> directory and the hosted first-prompt path still point at the default journal. Give the model a tool or file to read your records, and write instructions that send it there instead of <code>memory/</code>.</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="./hooks.html">Hooks</a></li><li><a href="./instructions.html">Instructions</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./../deployment.html">Deployment</a></li></ul>`,26)])])}const u=s(i,[["render",r]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_memory.md.BwyJXYZe.lean.js

@@ -0,0 +1 @@
+import{_ as s,c as t,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Memory","description":"Journal every turn so later sessions can read what earlier ones did.","frontmatter":{"title":"Memory","description":"Journal every turn so later sessions can read what earlier ones did."},"headers":[],"relativePath":"reference/memory.md","filePath":"reference/memory.md"}'),i={name:"reference/memory.md"};function r(n,e,d,h,l,c){return a(),t("div",null,[...e[0]||(e[0]=[o("",26)])])}const u=s(i,[["render",r]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_project-layout.md.SNzIvnmC.js → reference_project-layout.md.mFcS8yDD.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>A Bot Development Kit (BDK) project keeps agent files under <code>bot/</code>. Each file&#39;s path 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>
+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"}'),n={name:"reference/project-layout.md"};function d(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>A Bot Development Kit (BDK) project keeps agent files under <code>bot/</code>. Each file&#39;s path 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>
@@ -20,6 +20,6 @@ import{_ as t,c as o,o as s,a3 as a}from"./chunks/framework.BNw1pucY.js";const u
 <span class="line"><span>│   └── hooks/</span></span>
 <span class="line"><span>│       └── audit.ts           # observe session events</span></span>
 <span class="line"><span>└── evals/</span></span>
-<span class="line"><span>    └── readiness.eval.ts      # regression cases</span></span></code></pre></div><p>Evals stay in <code>evals/</code> at the project root, as a sibling of <code>bot/</code>, never inside it. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path under <code>bot/</code></th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent.ts</code></td><td><code>defineAgent({ model?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for <code>ctx.host.mcp</code> and <code>mcp oauth</code>. The model never sees them.</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>extensions/&lt;ns&gt;.ts</code> or <code>extensions/&lt;ns&gt;/</code></td><td>A mounted extension or Cursor plugin; its contributions become <code>&lt;ns&gt;__&lt;name&gt;</code></td><td><a href="./extensions.html">Extensions</a></td></tr><tr><td><code>channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>result.ts</code></td><td><code>defineResult</code> host <code>commit</code> on the final assistant text (<code>throw</code> or <code>ctx.reject</code>)</td><td>None</td></tr><tr><td><code>schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>reminders/*.ts</code></td><td>Named reminder handlers that stay armed across restarts</td><td><a href="./schedules.html#reminders">Schedules</a></td></tr><tr><td><code>sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#local-session-workspace">Sessions</a></td></tr><tr><td><code>lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr></tbody></table><p>Evals use project-root paths:</p><table tabindex="0"><thead><tr><th>Project-root path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p>Use <code>bot/lib/</code> for shared imports. A <code>.ts</code> file in one of the listed discovery folders loads as a definition; unrecognized directories produce a validation warning.</p><h2 id="inspect-discovery" tabindex="-1">Inspect discovery <a class="header-anchor" href="#inspect-discovery" aria-label="Permalink to &quot;Inspect discovery&quot;">​</a></h2><p>Run <code>bdk validate --dir .</code> and <code>bdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</p><div class="language-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 validate --dir .    # diagnostics; non-zero exit on errors</span></span>
+<span class="line"><span>    └── readiness.eval.ts      # regression cases</span></span></code></pre></div><p>Evals stay in <code>evals/</code> at the project root, as a sibling of <code>bot/</code>, never inside it. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path under <code>bot/</code></th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent.ts</code></td><td><code>defineAgent({ model?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for <code>ctx.host.mcp</code> and <code>mcp oauth</code>. The model never sees them.</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>extensions/&lt;ns&gt;.ts</code> or <code>extensions/&lt;ns&gt;/</code></td><td>A mounted extension or Cursor plugin; its contributions become <code>&lt;ns&gt;__&lt;name&gt;</code></td><td><a href="./extensions.html">Extensions</a></td></tr><tr><td><code>channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>reminders/*.ts</code></td><td>Named reminder handlers that stay armed across restarts</td><td><a href="./schedules.html#reminders">Schedules</a></td></tr><tr><td><code>sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#local-session-workspace">Sessions</a></td></tr><tr><td><code>lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr></tbody></table><p>Discovery rejects a <code>bot/result.ts</code> file. To act on a turn&#39;s decision, have the model record it with an authored <a href="./tools.html">tool</a>, then act on it from a <code>turn.completed</code> <a href="./hooks.html">hook</a>.</p><p>Evals use project-root paths:</p><table tabindex="0"><thead><tr><th>Project-root path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p>Use <code>bot/lib/</code> for shared imports. A <code>.ts</code> file in one of the listed discovery folders loads as a definition; unrecognized directories produce a validation warning.</p><h2 id="inspect-discovery" tabindex="-1">Inspect discovery <a class="header-anchor" href="#inspect-discovery" aria-label="Permalink to &quot;Inspect discovery&quot;">​</a></h2><p>Run <code>bdk validate --dir .</code> and <code>bdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong extension.</p><div class="language-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 validate --dir .    # diagnostics; non-zero exit on errors</span></span>
 <span class="line"><span>bdk info --dir .        # human-readable surface</span></span>
-<span class="line"><span>bdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)</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="./agent-config.html">Agent config</a>: the config at the project root</li><li><a href="./tools.html">Tools</a>: add typed actions under <code>tools/</code></li><li><a href="./cli.html">CLI</a>: commands that discover this tree</li></ul>`,22)])])}const m=t(d,[["render",n]]);export{u as __pageData,m as default};
+<span class="line"><span>bdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)</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="./agent-config.html">Agent config</a>: the config at the project root</li><li><a href="./tools.html">Tools</a>: add typed actions under <code>tools/</code></li><li><a href="./cli.html">CLI</a>: commands that discover this tree</li></ul>`,23)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};

package/dist/docs/assets/{reference_project-layout.md.SNzIvnmC.lean.js → reference_project-layout.md.mFcS8yDD.lean.js}

@@ -1 +1 @@
-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("",22)])])}const m=t(d,[["render",n]]);export{u as __pageData,m as default};
+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"}'),n={name:"reference/project-layout.md"};function d(r,e,c,i,l,p){return s(),o("div",null,[...e[0]||(e[0]=[a("",23)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};

package/dist/docs/assets/{reference_sessions.md.C_uzIWuy.js → reference_sessions.md.C8FXuGwk.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('<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, 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>, <code>action.tool_retry</code></td><td>Tool names, validated arguments, outputs, and errors. <code>action.tool_retry</code> means a read is running again after a transient failure</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};
+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, 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>, <code>action.tool_retry</code></td><td>Tool names, validated arguments, outputs, and errors. <code>action.tool_retry</code> means a read is running again after a transient failure</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.</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_skills.md.Ckddg6KX.js → reference_skills.md.C2GWh7g8.js}

@@ -1,6 +1,6 @@
-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>
+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:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
+<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Use when a pull request needs a structured approval checklist.</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR review checklist</span></span>
 <span class="line"></span>

package/dist/docs/assets/{reference_subagents.md.gmPt5J-M.js → reference_subagents.md.ChNGh6HK.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,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>
+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(d,e,l,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>. <code>subagent.completed</code> has <code>isError: true</code> when the subagent failed or was cancelled.</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>

package/dist/docs/assets/{reference_subagents.md.gmPt5J-M.lean.js → reference_subagents.md.ChNGh6HK.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,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};
+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(d,e,l,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};

package/dist/docs/assets/{troubleshooting.md.PCafNCb5.js → troubleshooting.md.DFnoTDlQ.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as d,a3 as r}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough.","frontmatter":{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),a={name:"troubleshooting.md"};function s(n,e,c,i,h,l){return d(),o("div",null,[...e[0]||(e[0]=[r('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with three checks:</p><ol><li>Run <code>bdk validate --dir .</code>.</li><li>Confirm the expected agent and connections in <code>bdk info --dir . --json</code>.</li><li>Reproduce once, then inspect the serve log or session trace.</li></ol><p>Match the visible symptom below.</p><h2 id="serve-or-the-playground-will-not-work" tabindex="-1">Serve or the playground will not work <a class="header-anchor" href="#serve-or-the-playground-will-not-work" aria-label="Permalink to &quot;Serve or the playground will not work&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> exits before listening</td><td>Fix the errors from <code>bdk validate --dir .</code>, then start it again.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>Start <code>bdk serve</code>; built playground assets have no agent data without the server.</td></tr><tr><td>Agent-file edits do not appear</td><td>Open the URL printed by <code>serve --dev</code>, then press Enter in its TTY to reload after file changes.</td></tr><tr><td>Sessions exist but the list is empty</td><td>The list is scoped to the authenticated principal. Use the same identity that created the session; a <code>?sessionId=</code> deep link does not bypass authorization.</td></tr><tr><td>The preferred port is busy</td><td>Use the next port printed by the CLI, pass <code>--port &lt;number&gt;</code>, or pass <code>--port 0</code> for any free port.</td></tr></tbody></table><h2 id="a-model-turn-fails" tabindex="-1">A model turn fails <a class="header-anchor" href="#a-model-turn-fails" aria-label="Permalink to &quot;A model turn fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>File reads and greps fail repeatedly with <code>NGHTTP2_FRAME_SIZE_ERROR</code></td><td>Run the agent under Node 22.13 or newer, never Bun.</td></tr><tr><td>The turn immediately reports a missing API key</td><td>Set <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or run <code>bdk login</code>.</td></tr><tr><td>Login succeeds but the model host rejects the key</td><td>Point login and model traffic at the same API host; check <code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>.</td></tr><tr><td>The first turn reports <code>[resource_exhausted]</code></td><td>Treat it as a capacity-shaped error. For a GitHub wake, also check the connected GitHub credential and any GitHub <code>429</code> rate limit before assuming the model quota is exhausted.</td></tr></tbody></table><h2 id="a-turn-behaves-unexpectedly" tabindex="-1">A turn behaves unexpectedly <a class="header-anchor" href="#a-turn-behaves-unexpectedly" aria-label="Permalink to &quot;A turn behaves unexpectedly&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Replies quote an ancestor <code>AGENTS.md</code> or unrelated repository rules</td><td>Inspect <code>local.cwd</code> in <code>/v1/info</code>. Set <code>defineAgent({ local: { cwd } })</code> or the session workspace explicitly instead of inheriting the parent checkout.</td></tr><tr><td>The model lists IDE meta-tools but never calls named MCP tools</td><td>Set <code>advertiseTools: true</code> on the local model-visible connection and confirm it under <code>connections</code> in <code>/v1/info</code>.</td></tr><tr><td>Server tools, skills, or seed files are absent</td><td>Check the discovered project in <code>/v1/info</code>; follow the capability warning from <code>validate</code>.</td></tr><tr><td><code>validate</code> and <code>run</code> pass but CI type-checking fails</td><td>Run the project type check. Tool results must be JSON-shaped; prefer object literals or <code>type</code> aliases over <code>interface</code> return types.</td></tr></tbody></table><h2 id="http-returns-401-403-or-409" tabindex="-1">HTTP returns 401, 403, or 409 <a class="header-anchor" href="#http-returns-401-403-or-409" aria-label="Permalink to &quot;HTTP returns 401, 403, or 409&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>401</code> outside local development</td><td>Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only.</td></tr><tr><td><code>403</code> on a stream or follow-up</td><td>Use the same authenticated principal that created the session.</td></tr><tr><td>A custom channel route fails through a tunnel or LAN</td><td>Protect the shared host with <code>--bearer-token</code> or authored channel auth. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</td></tr><tr><td><code>409</code> on a follow-up</td><td>Refresh the rotating <code>continuationToken</code> and confirm the target is a chat session; task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> from <code>call --session</code></td><td>Wait for the turn, omit <code>--session</code>, or mark a read-only tool with <code>effect: &quot;read&quot;</code> so it can run concurrently.</td></tr><tr><td>A custom route fails schema type-checking</td><td>Add the required Zod <code>querySchema</code> for <code>GET</code>, or <code>bodySchema</code> for <code>POST</code>, <code>PUT</code>, and <code>PATCH</code>. See <a href="./reference/channels.html">Channels</a>.</td></tr></tbody></table><h2 id="a-hosted-deployment-fails-or-looks-stale" tabindex="-1">A hosted deployment fails or looks stale <a class="header-anchor" href="#a-hosted-deployment-fails-or-looks-stale" aria-label="Permalink to &quot;A hosted deployment fails or looks stale&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>validate</code> or <code>deploy</code> reports <code>architecture &quot;v2&quot; requires a named secret</code></td><td>A <code>githubChannel</code> credential or a GitLab or Bitbucket <code>webhookSecret</code> is a literal or a getter. Replace it with the quoted <code>{ secretName: &quot;NAME&quot; }</code> and set the value with <code>bdk secrets set &lt;slug&gt; NAME</code>. See <a href="./guides/github.html#other-hosts">Other hosts</a>.</td></tr><tr><td>Local changes do not appear after deploy</td><td><code>deploy</code> reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again.</td></tr><tr><td>The deployment never becomes running</td><td>Run <code>bdk deployment &lt;slug&gt;</code>, then act on the reported build or startup error.</td></tr><tr><td>A secret or egress change has no effect</td><td>Confirm the name with <code>secrets list</code>, verify the <code>hosting</code> block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy.</td></tr><tr><td>Cursor events stopped after redeploy</td><td>Each redeploy replaces the watched repositories. Pass every <code>--cursor-events-repo</code> value again; without the flag, the deployment watches only its GitHub source repository.</td></tr><tr><td><code>run --prod</code> prints a <code>deliveryId</code> but no <code>sessionId</code></td><td>Expected, with or without <code>--dry-run</code>: the session is created when the turn starts. Find it with <code>bdk logs --prod --once --slug &lt;slug&gt;</code>, then follow <a href="./deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</td></tr><tr><td><code>session &lt;sessionId&gt; --prod</code> shows a <code>running</code> run with no logs</td><td>Runs lag behind events, and a high-effort turn can take several minutes. Rerun the command; a growing event count means the turn is still working.</td></tr><tr><td>A dashboard link to a single session doesn&#39;t open</td><td>Check the session with <code>bdk session &lt;sessionId&gt; --prod --slug &lt;slug&gt;</code>.</td></tr><tr><td><code>chat</code>, <code>call</code>, <code>sessions</code>, <code>cost</code>, or <code>mcp</code> with <code>--prod</code> says the command is not supported</td><td>Hosted deployments accept <code>--prod</code> only on <code>run</code>, <code>session</code>, <code>logs</code>, and <code>playground</code>. See <a href="./deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</td></tr><tr><td><code>run --prod --session &lt;sessionId&gt;</code> reports the session belongs to another channel</td><td><code>--session</code> continues only sessions that <code>run --prod</code> or <code>session --prod</code> started. Reach Slack, SCM, and custom-route sessions through their own channel.</td></tr><tr><td>A custom route returns <code>202</code> with no body</td><td>Expected on managed hosting. The handler runs after the response, so deliver results from the channel. See <a href="./reference/channels.html#route-responses">Route responses</a>.</td></tr><tr><td>External HTTP rejects the alias token</td><td>Update the caller with the current token. If the token is lost or exposed, run <code>bdk rotate-token &lt;slug&gt;</code> and replace it everywhere.</td></tr><tr><td><code>deploy</code> says deployments are not available under legacy privacy mode</td><td>The team uses Privacy Mode (Legacy), which does not let Cursor store code. Managed hosting is not available with this setting.</td></tr><tr><td><code>deploy</code> says persistent deployments are limited to 1 per team</td><td>Another deployment of the team already sets <code>persistent: true</code>. Remove the setting from one agent, or delete that deployment.</td></tr><tr><td>A schedule does not fire on the hosted deployment</td><td>Make sure the deployment is running and its release has the schedule. Deploy again with <code>@cursor/bdk</code> 0.2.14 or newer.</td></tr><tr><td>A request to a custom route gets <code>429</code></td><td>The deployment received more requests than its limit. Wait for the time in <code>Retry-After</code>, then send the request again.</td></tr></tbody></table><p>See <a href="./deployment.html">Deployment</a> for source, credential, and redeployment boundaries.</p><h2 id="github-deliveries-fail" tabindex="-1">GitHub deliveries fail <a class="header-anchor" href="#github-deliveries-fail" aria-label="Permalink to &quot;GitHub deliveries fail&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery after creating the hook</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command so the forwarder uses the <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= bdk github forward ...</code>.</td></tr><tr><td><code>Hook already exists</code></td><td>Run one forwarder for the repository and stop the stale process.</td></tr><tr><td>Direct webhook deliveries are rejected outside <code>--dev</code></td><td>Configure the same <code>GITHUB_WEBHOOK_SECRET</code> on the signer and server. Cursor event pull needs no public webhook or webhook secret.</td></tr><tr><td>You cannot create a forwarder</td><td>Use <code>bdk github replay &lt;pr-url&gt;</code>; it needs pull access instead of repository administration.</td></tr></tbody></table><p>The <a href="./guides/github.html">GitHub guide</a> covers event pull, replay, and direct webhooks.</p><h2 id="slack-does-not-respond" tabindex="-1">Slack does not respond <a class="header-anchor" href="#slack-does-not-respond" aria-label="Permalink to &quot;Slack does not respond&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs say <code>channel idle ... missing credentials</code></td><td>Run <code>bdk slack create --dir &lt;agent&gt;</code>, then check the generated prefix with <code>bdk slack doctor</code>. Use <code>slack init --manual</code> only for an app you own.</td></tr><tr><td><code>slack create</code> is waiting for workspace approval</td><td>Keep the CLI running, open the <strong>Request approval</strong> link it prints, and select <strong>Retry</strong> in the dashboard&#39;s <strong>Add Slack</strong> wizard after an admin approves. See <a href="./guides/slack.html#connect">Slack</a>.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Configure <code>engagement.channelPosts</code>, create the app with <code>--channel-posts</code>, and invite it to every allowed channel.</td></tr></tbody></table><p>See the <a href="./guides/slack.html">Slack guide</a> for app setup and engagement choices.</p><h2 id="mcp-authorization-fails" tabindex="-1">MCP authorization fails <a class="header-anchor" href="#mcp-authorization-fails" aria-label="Permalink to &quot;MCP authorization fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>Add <code>oauth: true</code> to the named URL connection or correct the connection filename passed to <code>mcp oauth</code>.</td></tr><tr><td>Local auth works but hosted calls return unauthorized</td><td>Locally stored OAuth tokens don&#39;t reach a deployment. Use a <code>cursorAccount: true</code> connection and connect the server from <strong>Deployed Agents</strong> in the dashboard. See <a href="./guides/mcp-oauth.html#use-an-oauth-server-from-a-hosted-agent">Host MCP OAuth</a>.</td></tr><tr><td>The model invents <code>mcp_auth</code> instead of calling the server</td><td>Set <code>advertiseTools: true</code> for named local tools, or expose a host-side wrapper through <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> for the credential lifecycle.</p><h2 id="schedules-or-reminders-stall" tabindex="-1">Schedules or reminders stall <a class="header-anchor" href="#schedules-or-reminders-stall" aria-label="Permalink to &quot;Schedules or reminders stall&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Trigger it through the matching <code>/v1/dev/schedules/&lt;id&gt;</code> or <code>/v1/dev/reminders/&lt;id&gt;</code> route; development mode does not auto-fire.</td></tr><tr><td>A reminder is disarmed with <code>handler_lost_on_restart</code></td><td>Recreate handler-form reminders after restart, or use a prompt-form reminder.</td></tr><tr><td>The same schedule fires on several self-hosted processes</td><td>Enable schedules on one serving process per project and pass <code>--no-schedules</code> to the others.</td></tr></tbody></table><h2 id="a-credential-was-exposed" tabindex="-1">A credential was exposed <a class="header-anchor" href="#a-credential-was-exposed" aria-label="Permalink to &quot;A credential was exposed&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A secret value appears in a command, transcript, or shell history</td><td>Rotate it at the provider, set it again through hidden input or stdin, and test the feature.</td></tr><tr><td>An alias token appears outside its secure destination</td><td>Run <code>bdk rotate-token &lt;slug&gt;</code>, store the new value outside transcripts, and update every caller.</td></tr><tr><td>Someone printed a secret to verify it</td><td>Rotate it. Confirm only the name with <code>bdk secrets list &lt;slug&gt;</code>, then redeploy and exercise the feature.</td></tr></tbody></table><h2 id="read-the-session-trace" tabindex="-1">Read the session trace <a class="header-anchor" href="#read-the-session-trace" aria-label="Permalink to &quot;Read the session trace&quot;">​</a></h2><p>Start with <code>actions.requested</code> and <code>action.result</code>. Count calls by tool name, pair every request with its result, and separate host preparation from tools chosen by the model.</p><p><code>turn.failed</code> with <code>turn interrupted</code> usually means a follow-up or stop ended the turn deliberately. Other failures should have an error event near the tool or model boundary that produced them.</p><p>Use the trace path printed by <code>bdk run</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>bdk trajectory --events &lt;trace-path&gt;</span></span></code></pre></div><p>The playground&#39;s <strong>Open trace</strong> control renders the same trajectory. When the agent runs but makes poor decisions, move from diagnosis to a measured <a href="./hillclimbing.html">hillclimb</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="./deployment.html">Deployment</a>: hosted and self-hosted boundaries</li><li><a href="./reference/sessions.html">Sessions</a>: session ownership and event vocabulary</li><li><a href="./reference/cli.html">CLI reference</a>: command flags and exit behavior</li></ul>',36)])])}const m=t(a,[["render",s]]);export{p as __pageData,m as default};
+import{_ as t,c as o,o as d,a3 as r}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough.","frontmatter":{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),a={name:"troubleshooting.md"};function s(n,e,c,i,h,l){return d(),o("div",null,[...e[0]||(e[0]=[r('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with three checks:</p><ol><li>Run <code>bdk validate --dir .</code>.</li><li>Confirm the expected agent and connections in <code>bdk info --dir . --json</code>.</li><li>Reproduce once, then inspect the serve log or session trace.</li></ol><p>Match the visible symptom below.</p><h2 id="serve-or-the-playground-will-not-work" tabindex="-1">Serve or the playground will not work <a class="header-anchor" href="#serve-or-the-playground-will-not-work" aria-label="Permalink to &quot;Serve or the playground will not work&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> exits before listening</td><td>Fix the errors from <code>bdk validate --dir .</code>, then start it again.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>Start <code>bdk serve</code>; built playground assets have no agent data without the server.</td></tr><tr><td>Agent-file edits do not appear</td><td>Open the URL printed by <code>serve --dev</code>, then press Enter in its TTY to reload after file changes.</td></tr><tr><td>Sessions exist but the list is empty</td><td>The list is scoped to the authenticated principal. Use the same identity that created the session; a <code>?sessionId=</code> deep link does not bypass authorization.</td></tr><tr><td>The preferred port is busy</td><td>Use the next port printed by the CLI, pass <code>--port &lt;number&gt;</code>, or pass <code>--port 0</code> for any free port.</td></tr></tbody></table><h2 id="a-model-turn-fails" tabindex="-1">A model turn fails <a class="header-anchor" href="#a-model-turn-fails" aria-label="Permalink to &quot;A model turn fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>File reads and greps fail repeatedly with <code>NGHTTP2_FRAME_SIZE_ERROR</code></td><td>Run the agent under Node 22.13 or newer, never Bun.</td></tr><tr><td>The turn immediately reports a missing API key</td><td>Set <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or run <code>bdk login</code>.</td></tr><tr><td>Login succeeds but the model host rejects the key</td><td>Point login and model traffic at the same API host; check <code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>.</td></tr><tr><td>The first turn reports <code>[resource_exhausted]</code></td><td>Treat it as a capacity-shaped error. For a GitHub wake, also check the connected GitHub credential and any GitHub <code>429</code> rate limit before assuming the model quota is exhausted.</td></tr></tbody></table><h2 id="a-turn-behaves-unexpectedly" tabindex="-1">A turn behaves unexpectedly <a class="header-anchor" href="#a-turn-behaves-unexpectedly" aria-label="Permalink to &quot;A turn behaves unexpectedly&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Replies quote an ancestor <code>AGENTS.md</code> or unrelated repository rules</td><td>Inspect <code>local.cwd</code> in <code>/v1/info</code>. Set <code>defineAgent({ local: { cwd } })</code> or the session workspace explicitly instead of inheriting the parent checkout.</td></tr><tr><td>The model lists IDE meta-tools but never calls named MCP tools</td><td>Set <code>advertiseTools: true</code> on the local model-visible connection and confirm it under <code>connections</code> in <code>/v1/info</code>.</td></tr><tr><td>Server tools, skills, or seed files are absent</td><td>Check the discovered project in <code>/v1/info</code>; follow the capability warning from <code>validate</code>.</td></tr><tr><td><code>validate</code> and <code>run</code> pass but CI type-checking fails</td><td>Run the project type check. Tool results must be JSON-shaped; prefer object literals or <code>type</code> aliases over <code>interface</code> return types.</td></tr></tbody></table><h2 id="http-returns-401-403-or-409" tabindex="-1">HTTP returns 401, 403, or 409 <a class="header-anchor" href="#http-returns-401-403-or-409" aria-label="Permalink to &quot;HTTP returns 401, 403, or 409&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>401</code> outside local development</td><td>Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only.</td></tr><tr><td><code>403</code> on a stream or follow-up</td><td>Use the same authenticated principal that created the session.</td></tr><tr><td>A custom channel route fails through a tunnel or LAN</td><td>Protect the shared host with <code>--bearer-token</code> or authored channel auth. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</td></tr><tr><td><code>409</code> on a follow-up</td><td>Refresh the rotating <code>continuationToken</code> and confirm the target is a chat session; task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> from <code>call --session</code></td><td>Wait for the turn, omit <code>--session</code>, or mark a read-only tool with <code>effect: &quot;read&quot;</code> so it can run concurrently.</td></tr><tr><td>A custom route fails schema type-checking</td><td>Add the required Zod <code>querySchema</code> for <code>GET</code>, or <code>bodySchema</code> for <code>POST</code>, <code>PUT</code>, and <code>PATCH</code>. See <a href="./reference/channels.html">Channels</a>.</td></tr></tbody></table><h2 id="a-hosted-deployment-fails-or-looks-stale" tabindex="-1">A hosted deployment fails or looks stale <a class="header-anchor" href="#a-hosted-deployment-fails-or-looks-stale" aria-label="Permalink to &quot;A hosted deployment fails or looks stale&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>validate</code> or <code>deploy</code> reports <code>architecture &quot;v2&quot; requires a named secret</code></td><td>A <code>githubChannel</code> credential or a GitLab or Bitbucket <code>webhookSecret</code> is a literal or a getter. Replace it with the quoted <code>{ secretName: &quot;NAME&quot; }</code> and set the value with <code>bdk secrets set &lt;slug&gt; NAME</code>. See <a href="./guides/github.html#other-hosts">Other hosts</a>.</td></tr><tr><td>Local changes do not appear after deploy</td><td><code>deploy</code> reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again.</td></tr><tr><td>The deployment never becomes running</td><td>Run <code>bdk deployment &lt;slug&gt;</code>, then act on the reported build or startup error.</td></tr><tr><td>A secret or egress change has no effect</td><td>Confirm the name with <code>secrets list</code>, verify the <code>hosting</code> block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy.</td></tr><tr><td>Cursor events stopped after redeploy</td><td>Each redeploy replaces the watched repositories. Pass every <code>--cursor-events-repo</code> value again; without the flag, the deployment watches only its GitHub source repository.</td></tr><tr><td><code>run --prod</code> prints a <code>deliveryId</code> but no <code>sessionId</code></td><td>Expected, with or without <code>--dry-run</code>: the session is created when the turn starts. Find it with <code>bdk logs --prod --once --slug &lt;slug&gt;</code>, then follow <a href="./deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</td></tr><tr><td><code>session &lt;sessionId&gt; --prod</code> shows a <code>running</code> run with no logs</td><td>Runs lag behind events, and a high-effort turn can take several minutes. Rerun the command; a growing event count means the turn is still working.</td></tr><tr><td>A dashboard link to a single session doesn&#39;t open</td><td>Check the session with <code>bdk session &lt;sessionId&gt; --prod --slug &lt;slug&gt;</code>.</td></tr><tr><td><code>chat</code>, <code>call</code>, <code>sessions</code>, <code>cost</code>, or <code>mcp</code> with <code>--prod</code> says the command is not supported</td><td>Hosted deployments accept <code>--prod</code> only on <code>run</code>, <code>session</code>, <code>logs</code>, and <code>playground</code>. See <a href="./deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</td></tr><tr><td><code>run --prod --session &lt;sessionId&gt;</code> reports the session belongs to another channel</td><td><code>--session</code> continues only sessions that <code>run --prod</code> or <code>session --prod</code> started. Reach Slack, SCM, and custom-route sessions through their own channel.</td></tr><tr><td>A custom route returns <code>202</code> with no body</td><td>Expected on managed hosting. The handler runs after the response, so deliver results from the channel. See <a href="./reference/channels.html#route-responses">Route responses</a>.</td></tr><tr><td>External HTTP rejects the alias token</td><td>Update the caller with the current token. If the token is lost or exposed, run <code>bdk rotate-token &lt;slug&gt;</code> and replace it everywhere.</td></tr><tr><td><code>deploy</code>, a hosted session, or an eval run says it is not available with Privacy Mode (Legacy)</td><td>Switch to Privacy Mode, or ask a team admin if your team enforces this setting. A refused session does not store the message. See <a href="./deployment.html#privacy-mode">Privacy Mode</a>.</td></tr><tr><td><code>deploy</code> says persistent deployments are limited to 1 per team</td><td>Another deployment of the team already sets <code>persistent: true</code>. Remove the setting from one agent, or delete that deployment.</td></tr><tr><td>A schedule does not fire on the hosted deployment</td><td>Make sure the deployment is running and its release has the schedule. Deploy again with <code>@cursor/bdk</code> 0.2.14 or newer.</td></tr><tr><td>A request to a custom route gets <code>429</code></td><td>The deployment received more requests than its limit. Wait for the time in <code>Retry-After</code>, then send the request again.</td></tr></tbody></table><p>See <a href="./deployment.html">Deployment</a> for source, credential, and redeployment boundaries.</p><h2 id="github-deliveries-fail" tabindex="-1">GitHub deliveries fail <a class="header-anchor" href="#github-deliveries-fail" aria-label="Permalink to &quot;GitHub deliveries fail&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery after creating the hook</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command so the forwarder uses the <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= bdk github forward ...</code>.</td></tr><tr><td><code>Hook already exists</code></td><td>Run one forwarder for the repository and stop the stale process.</td></tr><tr><td>Direct webhook deliveries are rejected outside <code>--dev</code></td><td>Configure the same <code>GITHUB_WEBHOOK_SECRET</code> on the signer and server. Cursor event pull needs no public webhook or webhook secret.</td></tr><tr><td>You cannot create a forwarder</td><td>Use <code>bdk github replay &lt;pr-url&gt;</code>; it needs pull access instead of repository administration.</td></tr></tbody></table><p>The <a href="./guides/github.html">GitHub guide</a> covers event pull, replay, and direct webhooks.</p><h2 id="slack-does-not-respond" tabindex="-1">Slack does not respond <a class="header-anchor" href="#slack-does-not-respond" aria-label="Permalink to &quot;Slack does not respond&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs say <code>channel idle ... missing credentials</code></td><td>Run <code>bdk slack create --dir &lt;agent&gt;</code>, then check the generated prefix with <code>bdk slack doctor</code>. Use <code>slack init --manual</code> only for an app you own.</td></tr><tr><td><code>slack create</code> is waiting for workspace approval</td><td>Keep the CLI running, open the <strong>Request approval</strong> link it prints, and select <strong>Retry</strong> in the dashboard&#39;s <strong>Add Slack</strong> wizard after an admin approves. See <a href="./guides/slack.html#connect">Slack</a>.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Configure <code>engagement.channelPosts</code>, create the app with <code>--channel-posts</code>, and invite it to every allowed channel.</td></tr></tbody></table><p>See the <a href="./guides/slack.html">Slack guide</a> for app setup and engagement choices.</p><h2 id="mcp-authorization-fails" tabindex="-1">MCP authorization fails <a class="header-anchor" href="#mcp-authorization-fails" aria-label="Permalink to &quot;MCP authorization fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>Add <code>oauth: true</code> to the named URL connection or correct the connection filename passed to <code>mcp oauth</code>.</td></tr><tr><td>Local auth works but hosted calls return unauthorized</td><td>Locally stored OAuth tokens don&#39;t reach a deployment. Use a <code>cursorAccount: true</code> connection and connect the server from <strong>Deployed Agents</strong> in the dashboard. See <a href="./guides/mcp-oauth.html#use-an-oauth-server-from-a-hosted-agent">Host MCP OAuth</a>.</td></tr><tr><td>The model invents <code>mcp_auth</code> instead of calling the server</td><td>Set <code>advertiseTools: true</code> for named local tools, or expose a host-side wrapper through <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> for the credential lifecycle.</p><h2 id="schedules-or-reminders-stall" tabindex="-1">Schedules or reminders stall <a class="header-anchor" href="#schedules-or-reminders-stall" aria-label="Permalink to &quot;Schedules or reminders stall&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Trigger it through the matching <code>/v1/dev/schedules/&lt;id&gt;</code> or <code>/v1/dev/reminders/&lt;id&gt;</code> route; development mode does not auto-fire.</td></tr><tr><td>A reminder is disarmed with <code>handler_lost_on_restart</code></td><td>Recreate handler-form reminders after restart, or use a prompt-form reminder.</td></tr><tr><td>The same schedule fires on several self-hosted processes</td><td>Enable schedules on one serving process per project and pass <code>--no-schedules</code> to the others.</td></tr></tbody></table><h2 id="a-credential-was-exposed" tabindex="-1">A credential was exposed <a class="header-anchor" href="#a-credential-was-exposed" aria-label="Permalink to &quot;A credential was exposed&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A secret value appears in a command, transcript, or shell history</td><td>Rotate it at the provider, set it again through hidden input or stdin, and test the feature.</td></tr><tr><td>An alias token appears outside its secure destination</td><td>Run <code>bdk rotate-token &lt;slug&gt;</code>, store the new value outside transcripts, and update every caller.</td></tr><tr><td>Someone printed a secret to verify it</td><td>Rotate it. Confirm only the name with <code>bdk secrets list &lt;slug&gt;</code>, then redeploy and exercise the feature.</td></tr></tbody></table><h2 id="read-the-session-trace" tabindex="-1">Read the session trace <a class="header-anchor" href="#read-the-session-trace" aria-label="Permalink to &quot;Read the session trace&quot;">​</a></h2><p>Start with <code>actions.requested</code> and <code>action.result</code>. Count calls by tool name, pair every request with its result, and separate host preparation from tools chosen by the model.</p><p><code>turn.failed</code> with <code>turn interrupted</code> usually means a follow-up or stop ended the turn deliberately. Other failures should have an error event near the tool or model boundary that produced them.</p><p>Use the trace path printed by <code>bdk run</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>bdk trajectory --events &lt;trace-path&gt;</span></span></code></pre></div><p>The playground&#39;s <strong>Open trace</strong> control renders the same trajectory. When the agent runs but makes poor decisions, move from diagnosis to a measured <a href="./hillclimbing.html">hillclimb</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="./deployment.html">Deployment</a>: hosted and self-hosted boundaries</li><li><a href="./reference/sessions.html">Sessions</a>: session ownership and event vocabulary</li><li><a href="./reference/cli.html">CLI reference</a>: command flags and exit behavior</li></ul>',36)])])}const m=t(a,[["render",s]]);export{p as __pageData,m as default};