@cursor/bdk 0.2.1

package/dist/docs/assets/reference_evals.md.DqNyHMA6.js

@@ -0,0 +1,56 @@
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results.","frontmatter":{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function d(l,s,h,r,o,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h1><p>Evals run fixed cases against an agent and record whether its turns, tools, events, and output meet a contract. Files under the project-root <code>evals/</code> directory define cases with <code>@cursor/bdk/evals</code>; the runner discovers their IDs, executes them, and reports every assertion. See the <a href="./../evals.html">Evals guide</a> for the regression workflow.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="eval-discovery-and-case-ids" tabindex="-1">Eval discovery and case IDs <a class="header-anchor" href="#eval-discovery-and-case-ids" aria-label="Permalink to &quot;Eval discovery and case IDs&quot;">​</a></h2><p>Eval files live under the project-root <code>evals/</code> directory and end in <code>.eval.ts</code> or <code>.eval.js</code>. The path under that directory becomes the eval ID:</p><ul><li><code>evals/readiness.eval.ts</code> becomes <code>readiness</code>.</li><li><code>evals/builds/api.eval.ts</code> becomes <code>builds/api</code>.</li><li><code>evals/builds/index.eval.ts</code> becomes <code>builds</code>.</li></ul><p>Export one <code>defineEval</code> with either <code>test</code> or <code>cases</code>, not both. A case ID appends one path segment to the file ID:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smoke&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cases: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;checkout&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review checkout PR 42.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</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;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review search PR 7.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</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>Those cases are <code>prs/checkout</code> and <code>prs/search</code> when the file is <code>evals/prs.eval.ts</code>. Case IDs must be unique single path segments.</p><p>A file can also export an array of <code>defineEval</code> calls. The runner names them with zero-padded indexes such as <code>sql/0000</code>. Named <code>cases</code> give handwritten scenarios stable IDs; arrays fit loaded datasets.</p><p><code>iterations</code> repeats one datapoint from 1 to 100 times. For <code>iterations: 3</code>, <code>weather/nyc</code> expands to <code>weather/nyc/1</code>, <code>weather/nyc/2</code>, and <code>weather/nyc/3</code>; selecting <code>weather/nyc</code> runs all three.</p><h2 id="eval-configuration" tabindex="-1">Eval configuration <a class="header-anchor" href="#eval-configuration" aria-label="Permalink to &quot;Eval configuration&quot;">​</a></h2><p>Every running suite needs <code>evals/evals.config.ts</code> with <code>maxConcurrency</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEvalConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineEvalConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  maxConcurrency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  timeoutMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">180_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  judge: { model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gpt-5.4-mini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>maxConcurrency</code></td><td>Required; concurrent authored datapoints, from 1 to 200</td></tr><tr><td><code>timeoutMs</code></td><td>Per-case timeout; case/file, CLI, then config precedence</td></tr><tr><td><code>judge</code></td><td>Default model for <code>t.judge</code></td></tr><tr><td><code>reporters</code></td><td>Objects notified as cases and runs complete</td></tr><tr><td><code>maxPlaygroundRuns</code></td><td>Number of server-side batches kept in playground history; defaults to 20</td></tr></tbody></table><p>A case can override <code>description</code>, <code>tags</code>, <code>timeoutMs</code>, <code>iterations</code>, <code>judge</code>, <code>reporters</code>, and <code>metadata</code>. Case metadata merges over file-level metadata; case reporters add to the file&#39;s reporters.</p><h2 id="send-turns-in-a-case" tabindex="-1">Send turns in a case <a class="header-anchor" href="#send-turns-in-a-case" aria-label="Permalink to &quot;Send turns in a case&quot;">​</a></h2><p><code>await t.send(message, options?)</code> runs one turn and waits until it finishes, fails, or parks for approval. Several sends in one test share the session.</p><p>The returned turn exposes its assistant <code>message</code>, <code>sessionId</code>, <code>events</code>, ordered <code>toolCalls</code>, <code>ok</code>, and one-based <code>index</code>. Assertions on the turn inspect only that turn; assertions on <code>t</code> inspect the whole case. Run values include <code>t.reply</code>, <code>t.events</code>, <code>t.turns</code>, <code>t.sessionId</code>, <code>t.iteration</code>, <code>t.iterations</code>, and the timeout <code>t.signal</code>.</p><p>These options apply on the first send because they shape the session:</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>workspaceFiles</code></td><td>Relative path-to-content map seeded into the session workspace</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute working directory for a new local session</td></tr></tbody></table><p>Use <code>turn.expectOk()</code> when later test steps depend on the turn succeeding. It throws when the turn failed.</p><h2 id="trajectory-assertions" tabindex="-1">Trajectory assertions <a class="header-anchor" href="#trajectory-assertions" aria-label="Permalink to &quot;Trajectory assertions&quot;">​</a></h2><p>Assertions record failures without stopping the test, so one case reports every violated contract.</p><table tabindex="0"><thead><tr><th>Assertion</th><th>Checks</th></tr></thead><tbody><tr><td><code>t.succeeded()</code></td><td>Run finished without failure or an unanswered approval</td></tr><tr><td><code>t.parked()</code></td><td>Run stopped on an unanswered approval</td></tr><tr><td><code>t.calledTool(name, matcher?)</code></td><td>Matching tool request occurred</td></tr><tr><td><code>t.notCalledTool(name)</code></td><td>No request for that tool occurred</td></tr><tr><td><code>t.loadedSkill(name)</code></td><td>Agent opened a named skill</td></tr><tr><td><code>t.toolOrder(names)</code></td><td>Tool requests appeared in relative order</td></tr><tr><td><code>t.usedNoTools()</code></td><td>No tool was requested</td></tr><tr><td><code>t.maxToolCalls(max)</code></td><td>Tool-call count stayed under the bound</td></tr><tr><td><code>t.noFailedActions()</code></td><td>No tool result failed</td></tr><tr><td><code>t.calledSubagent(name, matcher?)</code></td><td>Matching subagent call occurred</td></tr><tr><td><code>t.taggedArtifact(kind?, predicate?)</code></td><td>Matching durable artifact was tagged</td></tr><tr><td><code>t.event(type, matcher?)</code></td><td>Matching session event occurred</td></tr><tr><td><code>t.notEvent(type, matcher?)</code></td><td>Matching session event did not occur</td></tr><tr><td><code>t.eventOrder(matchers)</code></td><td>Event groups appeared in relative order</td></tr><tr><td><code>t.eventsSatisfy(label, predicate)</code></td><td>Predicate accepted the event stream</td></tr><tr><td><code>t.check(value, expectation)</code></td><td>Value met an expectation builder</td></tr><tr><td><code>t.score(name, value)</code></td><td>Recorded a numeric score from 0 to 1</td></tr></tbody></table><p><code>t.requireToolCall</code>, <code>t.requireInputRequest</code>, and <code>t.require</code> return the matched value and stop the remaining test body when no match exists.</p><h2 id="tool-and-event-matchers" tabindex="-1">Tool and event matchers <a class="header-anchor" href="#tool-and-event-matchers" aria-label="Permalink to &quot;Tool and event matchers&quot;">​</a></h2><p>Tool matchers can narrow by <code>input</code>, <code>output</code>, <code>status</code>, and <code>count</code>. Values accept literals, regular expressions, or predicates. Object literals partial-deep-match:</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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input: { verdict: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  status: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  count: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Tool status is <code>completed</code>, <code>failed</code>, <code>pending</code>, or <code>rejected</code>. Subagent matchers accept <code>output</code>, <code>status</code>, <code>count</code>, and <code>callId</code>. Event matchers accept <code>data</code> and <code>count</code>.</p><h2 id="expectation-builders" tabindex="-1">Expectation builders <a class="header-anchor" href="#expectation-builders" aria-label="Permalink to &quot;Expectation builders&quot;">​</a></h2><p>Import builders from <code>@cursor/bdk/evals</code>:</p><table tabindex="0"><thead><tr><th>Builder</th><th>Default severity</th></tr></thead><tbody><tr><td>\`includes(string</td><td>RegExp)\`</td></tr><tr><td><code>equals(value)</code></td><td>Hard gate</td></tr><tr><td><code>matches(schema)</code></td><td>Hard gate</td></tr><tr><td><code>satisfies(predicate, label)</code></td><td>Hard gate</td></tr><tr><td><code>similarity(expected)</code></td><td>Soft score</td></tr></tbody></table><p><code>matches</code> accepts Standard Schema implementations such as Zod. <code>normalizedSimilarity(value, expected)</code> returns the same 0-to-1 value used by <code>similarity</code>.</p><h2 id="severity-and-verdicts" tabindex="-1">Severity and verdicts <a class="header-anchor" href="#severity-and-verdicts" aria-label="Permalink to &quot;Severity and verdicts&quot;">​</a></h2><p>Every assertion returns a severity handle:</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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">soft</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">similarity</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Expected answer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">closedQA</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;names the failing step&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><ul><li><code>.gate(threshold?)</code> fails the case when it misses.</li><li><code>.soft(threshold?)</code> records a value without failing.</li><li><code>.atLeast(threshold)</code> records a soft bar; a miss produces a <code>scored</code> verdict.</li></ul><p>Case verdicts are <code>passed</code>, <code>failed</code>, <code>scored</code>, or <code>skipped</code>. The CLI exits 1 for a failed gate. A scored result exits 0 unless <code>--strict</code> is set. Exit 2 means the selection matched no cases.</p><h2 id="judges" tabindex="-1">Judges <a class="header-anchor" href="#judges" aria-label="Permalink to &quot;Judges&quot;">​</a></h2><p>Use a judge for meaning that deterministic checks cannot express:</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:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">factuality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">summarizes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">closedQA</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;names the root cause&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sql</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.9</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Each grades <code>t.reply</code> by default; pass <code>{ on }</code> to grade another value. Judge configuration can live in the project config, eval, case, or call, with the nearest value winning.</p><p><code>t.judge.model(prompt)</code> returns a raw model reply for custom grading. Treat agent output as untrusted input: wrap it with <code>fenceUntrusted</code> and include <code>EVAL_JUDGE_INJECTION_GUARD</code> in the judge prompt.</p><h2 id="datasets-and-fixtures" tabindex="-1">Datasets and fixtures <a class="header-anchor" href="#datasets-and-fixtures" aria-label="Permalink to &quot;Datasets and fixtures&quot;">​</a></h2><p>Load committed JSON, JSONL, or YAML relative to the project root:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEval, includes } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { loadYaml } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/evals/loaders&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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> rows</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> loadYaml</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{ </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string; </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string; </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">expected</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string }</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;evals/data/cases.yaml&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:#24292E;--shiki-dark:#E1E4E8;"> rows.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">row</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    description: row.task,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(row.prompt);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(row.expected));</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="reporters-and-results" tabindex="-1">Reporters and results <a class="header-anchor" href="#reporters-and-results" aria-label="Permalink to &quot;Reporters and results&quot;">​</a></h2><p>Built-in reporters include <code>JUnit({ filePath, suiteName? })</code> and <code>Artifacts({ dir })</code>. Custom reporters can expose <code>onRunStart</code>, <code>onEvalComplete</code>, and <code>onRunComplete</code>.</p><p>JSON output contains run totals and one result per case. Results include the case ID, verdict, assertions, session ID, inputs, final text, tools, tool calls, metrics, logs, duration, metadata, tags, and any error or skip reason.</p><h2 id="select-cases" tabindex="-1">Select cases <a class="header-anchor" href="#select-cases" aria-label="Permalink to &quot;Select cases&quot;">​</a></h2><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 eval --dir . --list</span></span>
+<span class="line"><span>bdk eval --dir .</span></span>
+<span class="line"><span>bdk eval --dir . builds/checkout</span></span>
+<span class="line"><span>bdk eval --dir . --tag smoke</span></span></code></pre></div><p>ID filters match an exact ID and its descendants. Repeated IDs use OR; repeated tags use OR. When both are present, a case must match both groups.</p><h2 id="inspect-run-artifacts" tabindex="-1">Inspect run artifacts <a class="header-anchor" href="#inspect-run-artifacts" aria-label="Permalink to &quot;Inspect run artifacts&quot;">​</a></h2><p>Default run artifacts go under <code>evals/&lt;stamp&gt;/</code> in the project state directory and include <code>summary.json</code>, <code>results.jsonl</code>, and <code>evals/&lt;case-id&gt;.json</code>. <code>--artifacts &lt;dir&gt;</code> chooses another destination; <code>--no-artifacts</code> disables them. This location is independent of <code>--state-root</code>.</p><h2 id="run-evals-against-a-server" tabindex="-1">Run evals against a server <a class="header-anchor" href="#run-evals-against-a-server" aria-label="Permalink to &quot;Run evals against a server&quot;">​</a></h2><p>The playground <strong>Evals</strong> view starts batches on its running server. <code>--url</code> targets a named running server, and <code>--prod --slug &lt;slug&gt;</code> targets a hosted deployment.</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 eval --prod --slug vulnerability-scanner --tag smoke</span></span>
+<span class="line"><span>bdk eval status &lt;eval-id&gt; --prod --slug vulnerability-scanner</span></span>
+<span class="line"><span>bdk eval cancel &lt;eval-id&gt; --prod --slug vulnerability-scanner</span></span></code></pre></div><p>Server-side batches use the target&#39;s discovered cases and return an eval ID for <code>status</code> or <code>cancel</code>. Local reporter and concurrency flags don&#39;t apply to <code>--url</code> or <code>--prod</code> runs.</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="./../evals.html">Evals guide</a></li><li><a href="./cli.html#eval">CLI reference</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./artifacts.html">Artifacts</a></li></ul>`,61)])])}const E=e(n,[["render",d]]);export{k as __pageData,E as default};

package/dist/docs/assets/reference_evals.md.DqNyHMA6.lean.js

@@ -0,0 +1 @@
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results.","frontmatter":{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function d(l,s,h,r,o,p){return i(),a("div",null,[...s[0]||(s[0]=[t("",61)])])}const E=e(n,[["render",d]]);export{k as __pageData,E as default};

package/dist/docs/assets/reference_extensions.md.CPPrkWlJ.js

@@ -0,0 +1,58 @@
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(p,s,o,h,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages capabilities that would otherwise live under <code>bot/</code>: tools, skills, instructions, connections, hooks, channels, schedules, subagents, artifacts, and workspace seeds. One mount file adds them under a namespace without copying their source into your project.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>Extensions and Cursor plugins execute as trusted host code. A namespace prevents name collisions; it does not sandbox the package or limit its side effects. Review the package before mounting it.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package and add one file under <code>bot/extensions/</code>. The filename becomes the namespace, so this mount contributes names such as <code>ci__failed_jobs</code> and <code>ci__triage</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ci </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@acme/ci-triage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ci</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  org: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  token: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BUILDKITE_TOKEN</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The extension validates its configuration while the project loads. Missing or mistyped settings fail <code>bdk validate</code> before a turn can call the contributed code.</p><p>Extension instructions are appended to the root agent&#39;s instructions. The root agent still needs its own <code>bot/instructions.md</code>.</p><h2 id="inspect-a-mount" tabindex="-1">Inspect a mount <a class="header-anchor" href="#inspect-a-mount" aria-label="Permalink to &quot;Inspect a mount&quot;">​</a></h2><p>Run discovery after mounting or upgrading an 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 .</span></span>
+<span class="line"><span>bdk info --dir . --json</span></span></code></pre></div><p><code>info</code> lists each mount and its namespaced tools, skills, connections, hooks, channels, schedules, subagents, and artifact kinds. The same data appears under <code>extensions</code> in <code>GET /v1/info</code>.</p><p>Names inside the extension stay short. A tool authored as <code>tools/failed_jobs.ts</code> appears to the mounting agent as <code>&lt;namespace&gt;__failed_jobs</code>. The <code>__</code> separator is reserved, so root contributions cannot impersonate a mounted one.</p><h2 id="adjust-a-mounted-extension" tabindex="-1">Adjust a mounted extension <a class="header-anchor" href="#adjust-a-mounted-extension" aria-label="Permalink to &quot;Adjust a mounted extension&quot;">​</a></h2><p>Mount as a directory when you need to replace or remove one contribution. Keep the package mount in <code>extension.ts</code>, then overlay the extension&#39;s short name beneath it.</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/extensions/ci/</span></span>
+<span class="line"><span>  extension.ts</span></span>
+<span class="line"><span>  tools/</span></span>
+<span class="line"><span>    job_log.ts</span></span>
+<span class="line"><span>    retry_job.ts</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci/tools/job_log.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  jobLogInput,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  readRedactedLog,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../../../lib/ci.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Read a redacted CI log.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: jobLogInput,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  execute: readRedactedLog,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/ci/tools/retry_job.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { disableTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> disableTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>The first file replaces <code>ci__job_log</code>; the second removes <code>ci__retry_job</code>. Use the matching <code>disable*</code> helper for another slot, or generic <code>disable()</code> when the file location already identifies it. Validation fails when an overlay names a contribution the package does not provide.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p><code>cursorPlugin()</code> adapts a vendored Cursor or Claude plugin into the same namespace model. Skills, commands, agents, and MCP servers become Agent SDK skills, subagents, and connections.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/notion.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorPlugin } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> cursorPlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugins/notion-workspace&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  variables: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    NOTION_TOKEN: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NOTION_TOKEN</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>path</code> is relative to the project root. <code>variables</code> fills placeholders declared by the plugin&#39;s MCP configuration; unresolved placeholders fail validation instead of mounting a partial server.</p><p>Plugin rules and hooks are not mounted. Overlay a generated <code>mcp-connections/&lt;server&gt;.ts</code> file to replace or disable one plugin server. OAuth-backed plugin servers use <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>; transport and tool-filter details live in <a href="./connections.html">MCP connections</a>.</p><h2 id="extension-contents" tabindex="-1">Extension contents <a class="header-anchor" href="#extension-contents" aria-label="Permalink to &quot;Extension contents&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Ships under the namespace</th><th>Ignored</th></tr></thead><tbody><tr><td>Instructions, tools, skills, MCP and host connections</td><td><code>agent.ts</code>, storage, OpenTelemetry</td></tr><tr><td>Hooks, channels, schedules, and subagents</td><td>Playground code, custom sandbox backends</td></tr><tr><td>Artifact kinds and workspace seed files</td><td>Nested extensions</td></tr></tbody></table><p><code>bdk validate</code> reports unsupported paths.</p><h2 id="build-an-extension" tabindex="-1">Build an extension <a class="header-anchor" href="#build-an-extension" aria-label="Permalink to &quot;Build an extension&quot;">​</a></h2><p>Lay out the package like the shareable part of <code>bot/</code>. The root <code>extension.ts</code> supplies a description and validates any settings the consumer must provide.</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>@acme/ci-triage/</span></span>
+<span class="line"><span>  package.json</span></span>
+<span class="line"><span>  extension.ts</span></span>
+<span class="line"><span>  instructions.md</span></span>
+<span class="line"><span>  tools/</span></span>
+<span class="line"><span>    failed_jobs.ts</span></span>
+<span class="line"><span>    job_log.ts</span></span>
+<span class="line"><span>  skills/</span></span>
+<span class="line"><span>    triage.md</span></span>
+<span class="line"><span>  hooks/</span></span>
+<span class="line"><span>    audit.ts</span></span>
+<span class="line"><span>  lib/</span></span>
+<span class="line"><span>    buildkite.ts</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;">// extension.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineExtension } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineExtension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  root: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.dirname,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Investigate failing Buildkite jobs.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  config: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    org: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    token: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    logTailLines: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">positive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Modules inside the package import this definition and read <code>extension.config</code>, which is already validated and has defaults applied. Publish the built entry point with its slot directories and prose assets beside it.</p><p>The <a href="./project-layout.html">Project layout</a> owns each contribution&#39;s authoring contract. Keep extension instructions and tool descriptions namespace-neutral because the consumer chooses the final prefix.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/cloud-agents.html">Cloud agents</a>: delegate repository work through an extension</li><li><a href="./../guides/grokbot-agents.html">Grok Bot agents</a>: consult named bots</li><li><a href="./../guides/jev.html">Jev</a>: typed answers, then gated writes</li><li><a href="./../guides/improve.html">Self-improvement</a>: propose source changes through pull requests</li><li><a href="./project-layout.html">Project layout</a>: contribution slots</li><li><a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>: capability contracts</li></ul>`,36)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_extensions.md.CPPrkWlJ.lean.js

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

package/dist/docs/assets/reference_hooks.md.Dg3dEugd.js

@@ -0,0 +1,45 @@
+import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook subscribes to selected session events and can run a side effect after each matching event is recorded: an audit line, a metric, a transcript copy, or derived state. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply; a handler that throws is logged and skipped.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>Treat the event as read-only. Later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong surface for anything that must run before the model or must fail a turn; see <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>bot/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/bdk/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
+<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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;turn.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.usage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      const</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">inputTokens</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">outputTokens</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.usage;</span></span>
+<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.tokens.input&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, inputTokens);</span></span>
+<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.tokens.output&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, outputTokens);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<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>. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. <code>stubbed</code> means a dry-run session answered a write without running it</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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> pagerUrl</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">PAGER_WEBHOOK_URL</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        pagerUrl </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;eval&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ||</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        event.data.status </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;cancelled&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(pagerUrl, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        method: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;POST&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        headers: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;content-type&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;application/json&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        body: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stringify</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          agent: ctx.agent.name,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          session: ctx.session.id,</span></span>
+<span class="line"><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;">          message: event.data.message,</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;">        signal: AbortSignal.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="hooks-vs-channels-vs-evals" tabindex="-1">Hooks vs channels vs evals <a class="header-anchor" href="#hooks-vs-channels-vs-evals" aria-label="Permalink to &quot;Hooks vs channels vs evals&quot;">​</a></h2><p>All three consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>bot/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to &quot;Hook boundaries&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to &quot;Test a hook&quot;">​</a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events[&quot;turn.completed&quot;]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>bdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>bdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>bdk run --dir . --message &quot;…&quot;</code></td><td>Serve log on stderr, including <code>hook &quot;&lt;name&gt;&quot; handler for &lt;event&gt; threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>bdk logs</code></a>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/hooks.html">Hooks guide</a>: meter usage and page on failure</li><li><a href="./sessions.html">Sessions and streaming</a>: the event vocabulary hooks observe</li><li><a href="./../guides/opentelemetry.html">OpenTelemetry</a>: OTLP traces and metrics from the same event stream</li><li><a href="./../deployment.html#observability">Deployment</a>: runtime logs and export paths</li><li><a href="./channels.html#events">Channels</a>: the delivery-side counterpart</li></ul>`,32)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_hooks.md.Dg3dEugd.lean.js

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

package/dist/docs/assets/reference_http-api.md.BZOvhCqY.js

@@ -0,0 +1,11 @@
+import{_ as t,c as s,o,a3 as a}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),d={name:"reference/http-api.md"};function n(i,e,r,l,c,h){return o(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="http-api" tabindex="-1">HTTP API <a class="header-anchor" href="#http-api" aria-label="Permalink to &quot;HTTP API&quot;">​</a></h1><p>Grok Bot Development Kit (BDK) hosts expose one public HTTP surface. In the default multi-agent layout, each agent uses <code>/&lt;slug&gt;/v1/*</code>; <code>--mode single</code> serves the same routes at <code>/v1/*</code>. Routes use the agent&#39;s HTTP auth chain, and session-owned resources return <code>403</code> to another principal.</p><p>Unless a section says otherwise, the default auth policy is <code>localDevStrict()</code>. <code>--bearer-token</code> replaces it with bearer auth, and <code>--allow-anonymous</code> replaces it with anonymous access. Built-in JSON routes use <code>{ ok: false, error: &quot;&lt;code&gt;&quot;, message? }</code> for errors; MCP uses JSON-RPC, and custom channel handlers define their own responses.</p><h2 id="host-routes" tabindex="-1">Host routes <a class="header-anchor" href="#host-routes" aria-label="Permalink to &quot;Host routes&quot;">​</a></h2><p>These routes live at the host root in multi-agent mode. The index routes exist only when the playground is enabled.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /</code></td><td>HTML index of mounted agents; no auth</td></tr><tr><td><code>GET /v1/agents</code></td><td>JSON index of mounted agents; no auth</td></tr><tr><td><code>GET /docs</code>, <code>GET /docs/*</code></td><td>Documentation site in either layout; no auth</td></tr><tr><td><code>GET /v1/health</code></td><td>Host liveness; no auth</td></tr></tbody></table><p><code>--no-playground</code> removes the two index routes. <code>--no-docs</code> removes the documentation site.</p><h2 id="start-a-session" tabindex="-1">Start a session <a class="header-anchor" href="#start-a-session" aria-label="Permalink to &quot;Start a session&quot;">​</a></h2><p><code>POST /v1/session</code> opens a durable conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>Once accepted, the response returns <code>sessionId</code> for inspection and <code>continuationToken</code> for follow-ups; follow the stream for progress.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Contract</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Display title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone; sets <code>ctx.now()</code> and rejects omitted, relative, or later declared tool time arguments. Invalid values return <code>400</code></td></tr><tr><td><code>workspaceFiles</code></td><td>Relative files added to the session workspace</td></tr><tr><td><code>purpose</code></td><td>Use <code>&quot;eval&quot;</code> to mark regression traffic</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>The route accepts any chat session, including one created by a custom channel. Each accepted follow-up rotates the continuation token and returns the replacement. A message sent to a busy session interrupts the active turn before starting.</p><p>The route returns <code>409</code> for a stale token or task session, and <code>403</code> when the caller doesn&#39;t own the session.</p><h2 id="stream-or-replay-session-events" tabindex="-1">Stream or replay session events <a class="header-anchor" href="#stream-or-replay-session-events" aria-label="Permalink to &quot;Stream or replay session events&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</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>The route replays one event per line from <code>startIndex</code>, then follows new events. The default <code>0</code> replays the full stream. To reconnect without duplicates, pass the last index you received plus one.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>. See <a href="./sessions.html#stream-events">Stream events</a> for the event vocabulary.</p><h2 id="manage-sessions" tabindex="-1">Manage sessions <a class="header-anchor" href="#manage-sessions" aria-label="Permalink to &quot;Manage sessions&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>POST /v1/session/:sessionId/stop</code></td><td>Interrupt the active turn without sending another message</td></tr><tr><td><code>GET /v1/sessions</code></td><td>List sessions owned by the caller</td></tr><tr><td><code>GET /v1/session/:sessionId/cost</code></td><td>Return per-turn token usage and estimated cost</td></tr></tbody></table><p>On loopback under <code>serve --dev</code>, the session list includes every principal so webhook and schedule sessions appear in the playground. The cost route returns <code>404</code> for an unknown session.</p><h2 id="resolve-tool-approvals" tabindex="-1">Resolve tool approvals <a class="header-anchor" href="#resolve-tool-approvals" aria-label="Permalink to &quot;Resolve tool approvals&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>List pending tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one with <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>.</p><h2 id="call-a-tool-without-a-model-turn" tabindex="-1">Call a tool without a model turn <a class="header-anchor" href="#call-a-tool-without-a-model-turn" aria-label="Permalink to &quot;Call a tool without a model turn&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;input&quot;:{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}}&#39;</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;toolName&quot;:&quot;inspect_pr&quot;,&quot;callId&quot;:&quot;tool_inspect_pr_…&quot;,</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Body field</th><th>Contract</th></tr></thead><tbody><tr><td><code>input</code></td><td>Tool input; defaults to <code>{}</code></td></tr><tr><td><code>sessionId</code></td><td>Bind the call to an existing session</td></tr><tr><td><code>continuationToken</code></td><td>Bind the call by its wire continuation token; mutually exclusive with <code>sessionId</code></td></tr></tbody></table><p>Omit both identifiers for an unbound call. Agent-execution tools return <code>400</code>, and an unknown name returns <code>404</code> with the available names. See <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a> for session binding, busy-session rules, and error codes.</p><h2 id="discovery-routes" tabindex="-1">Discovery routes <a class="header-anchor" href="#discovery-routes" aria-label="Permalink to &quot;Discovery routes&quot;">​</a></h2><p>These read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics</td></tr><tr><td><code>GET /v1/tools</code></td><td>Return live server tools and advertised MCP tools as <code>{ name, title?, source? }</code>; bind tenant-scoped listings with <code>session</code> or <code>continuationToken</code></td></tr><tr><td><code>GET /v1/tools/:name</code></td><td>Return one tool&#39;s description, execution mode, approval and effect rules, schemas, and source</td></tr><tr><td><code>GET /v1/health</code></td><td>Return per-agent liveness; no auth</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Return recent server logs and the next polling cursor</td></tr></tbody></table><p>An unknown tool name returns <code>404</code> with available names. If an MCP connection can&#39;t list its tools, the catalog skips that connection and includes it in <code>connectionErrors</code>.</p><h2 id="list-and-download-artifacts" tabindex="-1">List and download artifacts <a class="header-anchor" href="#list-and-download-artifacts" aria-label="Permalink to &quot;List and download artifacts&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/artifacts</code></td><td>Return <code>{ artifacts }</code>, newest-updated first; filter with <code>kind</code>, <code>sessionId</code>, and a positive <code>limit</code></td></tr><tr><td><code>GET /v1/artifacts/:id/content</code></td><td>Download an artifact&#39;s file or blob as an attachment; return <code>404</code> when no content exists</td></tr></tbody></table><p>The list follows the same ownership rules as <code>GET /v1/sessions</code>. See <a href="./artifacts.html">Artifacts</a> for tagging and record fields.</p><h2 id="call-custom-channel-routes" tabindex="-1">Call custom channel routes <a class="header-anchor" href="#call-custom-channel-routes" aria-label="Permalink to &quot;Call custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with their declared methods and paths. The host validates their Zod body and query schemas before calling the handler, returning <code>400</code> on failure. Each channel&#39;s auth chain applies. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p>Both MCP routes use stateless streamable HTTP. Send protocol requests with <code>POST</code>; <code>GET</code> and <code>DELETE</code> return <code>405</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Tools and auth</th></tr></thead><tbody><tr><td><code>/v1/mcp</code></td><td><code>ask</code>, <code>check</code>, and <code>call_tool</code> when server tools exist; uses the session API auth chain</td></tr><tr><td><code>/v1/mcp/tools</code></td><td>Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain</td></tr></tbody></table><p>See <a href="./connections.html#peer-mcp-connection">MCP connections</a> to connect one agent to another.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>The playground Evals tab and remote eval commands use these routes:</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered cases and eval config</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots, newest first</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start <code>{ filterIds?, tags?, timeoutMs?, verbose? }</code>; return <code>202</code>, <code>404</code> for no match, or <code>409</code> while another run is active</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Return progress and the final snapshot</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel an active run; return <code>404</code> when unknown or <code>409</code> when no longer running</td></tr></tbody></table><p>Poll the run route until its status is <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics; when both fields are present, a case must match each group.</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>Contract</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes run them manually.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the playground. <code>--no-playground</code> removes both routes.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Built-in routes use these common status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>400</code></td><td>Invalid body, query, tool input, or request shape</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>The caller is authenticated but doesn&#39;t own the resource</td></tr><tr><td><code>404</code></td><td>A named resource doesn&#39;t exist, or an eval selection matches no cases</td></tr><tr><td><code>405</code></td><td>The route doesn&#39;t accept this method</td></tr><tr><td><code>409</code></td><td>The resource state rejects the request, such as a stale token or busy write</td></tr><tr><td><code>202</code></td><td>The request was accepted for asynchronous work</td></tr><tr><td><code>500</code></td><td>A write-effect tool can&#39;t create its session workspace (<code>workspace_unavailable</code>)</td></tr></tbody></table><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./sessions.html">Sessions</a></li><li><a href="./channels.html">Channels</a></li><li><a href="./tools.html">Tools</a></li><li><a href="./../deployment.html">Deployment</a></li></ul>`,61)])])}const k=t(d,[["render",n]]);export{p as __pageData,k as default};

package/dist/docs/assets/reference_http-api.md.BZOvhCqY.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as s,o,a3 as a}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),d={name:"reference/http-api.md"};function n(i,e,r,l,c,h){return o(),s("div",null,[...e[0]||(e[0]=[a("",61)])])}const k=t(d,[["render",n]]);export{p as __pageData,k as default};

package/dist/docs/assets/reference_instructions.md.Bdwscs4G.js

@@ -0,0 +1,14 @@
+import{_ as t,c as a,o as i,a3 as e}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the local harness, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function l(o,s,r,h,d,p){return i(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="instructions" tabindex="-1">Instructions <a class="header-anchor" href="#instructions" aria-label="Permalink to &quot;Instructions&quot;">​</a></h1><p>Agent instructions form the always-on system prompt and reach the model on every turn. A root agent requires them; a subagent may inline <code>instructions</code> in <code>agent.ts</code> instead.</p><p>The <code>@cursor/bdk</code> imports on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Form</th><th>Use it when</th></tr></thead><tbody><tr><td><code>bot/instructions.md</code></td><td>Plain Markdown for most agents</td></tr><tr><td><code>bot/instructions.ts</code></td><td>Generated prompts. Default-export <code>defineInstructions({ markdown })</code> or a plain string</td></tr><tr><td><code>bot/instructions/</code> directory</td><td>A long prompt split across files, composed in filename order</td></tr></tbody></table><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/instructions.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineInstructions } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineInstructions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`You are the on-call assistant for \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">TEAM_NAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="delivery" tabindex="-1">Delivery <a class="header-anchor" href="#delivery" aria-label="Permalink to &quot;Delivery&quot;">​</a></h2><p>Instructions land in the session workspace as <code>AGENTS.md</code>, and the harness loads them natively. Parent directories can still contribute ambient <code>AGENTS.md</code> and <code>.cursor</code> settings; <a href="./agent-config.html#local-cwd">Agent config: local cwd</a> covers how to control that.</p><h2 id="contents" tabindex="-1">Contents <a class="header-anchor" href="#contents" aria-label="Permalink to &quot;Contents&quot;">​</a></h2><p>Keep them a few lines: identity, when to use which tool, and the output shape. The <a href="./../quickstart.html">quickstart PR approver</a> is the pattern:</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;"># PR approver</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">You review GitHub pull requests. Be specific and brief.</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Call </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`inspect_pr\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> first. Never judge a change you haven&#39;t fetched.</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Match your review to the complexity it reports.</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Never approve a draft.</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><p>Name the tools and the decision rule (&quot;use X before answering about Y&quot;), not general encouragement. State the output contract, including length, format, and fences, so your <a href="./../evals.html">evals</a> can gate it. Put multi-step workflows the model only sometimes needs in <code>bot/skills/</code>; they load on demand and keep the always-on prompt small.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./skills.html">Skills</a>: procedures the model loads only when relevant</li><li><a href="./agent-config.html">Agent config</a>: the file next to this one</li><li><a href="./../hillclimbing.html">Hillclimbing</a>: iterating on instructions with evidence</li></ul>`,14)])])}const u=t(n,[["render",l]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_instructions.md.Bdwscs4G.lean.js

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

package/dist/docs/assets/reference_playground.md.BdQzRJc2.js

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

package/dist/docs/assets/reference_playground.md.BdQzRJc2.lean.js

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