@cursor/bdk 0.2.14 → 0.2.16

package/dist/docs/assets/deployment.md.BYuEcDBv.js

@@ -1,29 +0,0 @@
-import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Deployment","description":"Deploy a BDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure.","frontmatter":{"title":"Deployment","description":"Deploy a BDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure."},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),o={name:"deployment.md"};function i(r,e,l,d,p,h){return a(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="deploy-a-bdk-project" tabindex="-1">Deploy a BDK project <a class="header-anchor" href="#deploy-a-bdk-project" aria-label="Permalink to &quot;Deploy a BDK project&quot;">​</a></h1><p>Deployment turns a pushed Grok Bot Development Kit (BDK) project into a stable service. Cursor-managed hosting builds the selected Git ref and operates the runtime; self-hosting gives you control of the network, process, and filesystem.</p><h2 id="choose-managed-hosting-or-self-hosting" tabindex="-1">Choose managed hosting or self-hosting <a class="header-anchor" href="#choose-managed-hosting-or-self-hosting" aria-label="Permalink to &quot;Choose managed hosting or self-hosting&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Option</th><th>Use it when</th><th>You manage</th></tr></thead><tbody><tr><td>Cursor-managed hosting</td><td>You want the shortest path from Git to a running agent</td><td>Source, declared egress, secrets, and agent behavior</td></tr><tr><td>Self-hosting</td><td>You need your own network, proxy, filesystem, or process controls</td><td>The Node process, TLS, auth, secrets, state, monitoring, and upgrades</td></tr></tbody></table><p>The rest of this guide starts with managed hosting. The <a href="#self-host-securely">self-host recipe</a> uses the same project and HTTP API.</p><h2 id="deploy-from-git" tabindex="-1">Deploy from Git <a class="header-anchor" href="#deploy-from-git" aria-label="Permalink to &quot;Deploy from Git&quot;">​</a></h2><p>Commit and push the exact ref you want to run, then sign in, validate, and deploy. The preferred CLI is <code>bdk</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>cd my-agent</span></span>
-<span class="line"><span>bdk login</span></span>
-<span class="line"><span>bdk whoami</span></span>
-<span class="line"><span>bdk validate</span></span>
-<span class="line"><span>bdk deploy</span></span></code></pre></div><p>The deploy command waits until the runtime is running and prints the stable deployment URL.</p><p><code>deploy</code> reads from Git; it does not upload your working tree. Inside a checkout, it infers the HTTPS origin, current ref, agent path, and slug. Pass them explicitly when the checkout is not the source you want:</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 deploy \\</span></span>
-<span class="line"><span>  --repo https://github.com/acme/agents \\</span></span>
-<span class="line"><span>  --ref main \\</span></span>
-<span class="line"><span>  --path agents/weather \\</span></span>
-<span class="line"><span>  --slug weather-agent</span></span></code></pre></div><p>The source repository must be available through the team&#39;s repository integration, and a nested <code>--path</code> must contain an installable BDK project.</p><h2 id="add-egress-and-secrets" tabindex="-1">Add egress and secrets <a class="header-anchor" href="#add-egress-and-secrets" aria-label="Permalink to &quot;Add egress and secrets&quot;">​</a></h2><p>Declare the external hosts and secret names the agent needs. Mounted extensions add the ones they declare, so list only what your own code calls; <code>bdk info --dir .</code> shows the combined list and what each mount adds. After the deployment exists, set each value at the hidden prompt and follow the CLI or dashboard instruction to redeploy.</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/agent.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  hosting: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;api.weather.example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    secretNames: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;WEATHER_API_KEY&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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 secrets set weather-agent WEATHER_API_KEY</span></span>
-<span class="line"><span>bdk secrets list weather-agent</span></span>
-<span class="line"><span>bdk deploy --dir . --slug weather-agent</span></span></code></pre></div><p>Commit secret names, never values. <code>secrets set</code> accepts names and reads values without echoing them; <code>secrets list</code> returns names and creation times only. Do not pass <code>NAME=VALUE</code>, print a secret to verify it, or put names beginning with reserved <code>CURSOR_</code> in <code>secretNames</code>.</p><p>A hosted deployment receives its secrets per request, after its modules are loaded, so code that reads <code>process.env</code> while a module is still loading sees nothing. Read a secret inside the handler, tool, or callback that needs it, and give an MCP connection its credential as a <code>\${NAME}</code> template, which resolves when the connection opens. See <a href="./reference/connections.html#credentials-in-headers-and-env">credentials in headers and env</a>. SCM webhook channels go one step further and name their secrets in the channel definition, as <code>{ secretName: &quot;GITHUB_WEBHOOK_SECRET&quot; }</code>, so the platform can verify each delivery&#39;s signature before any compute starts. <code>validate</code> rejects a literal or getter there. The <a href="./guides/github.html#other-hosts">GitHub guide</a> shows the named form.</p><p>Enter egress hosts without schemes or paths. An HTTPS host needs no port; add one, as <code>clickhouse.example.com:9440</code>, only for a protocol the proxy reads no hostname from. The <a href="./guides/mcp-oauth.html">Host MCP OAuth guide</a> owns the extra secret and egress steps for OAuth-backed MCP servers.</p><h2 id="use-the-hosted-agent" tabindex="-1">Use the hosted agent <a class="header-anchor" href="#use-the-hosted-agent" aria-label="Permalink to &quot;Use the hosted agent&quot;">​</a></h2><h3 id="verify-a-hosted-turn" tabindex="-1">Verify a hosted turn <a class="header-anchor" href="#verify-a-hosted-turn" aria-label="Permalink to &quot;Verify a hosted turn&quot;">​</a></h3><p>Start a turn on the 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 run --prod --slug weather-agent \\</span></span>
-<span class="line"><span>  --message &quot;Forecast for Paris&quot;</span></span></code></pre></div><p>The command returns as soon as the deployment accepts the turn, so the output has a <code>deliveryId</code> but no <code>sessionId</code> yet. That&#39;s expected, with or without <code>--dry-run</code>. Open the deployment from <strong>Deployed Agents</strong> in the <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">dashboard</a> and select <strong>Sessions</strong> to find the new session&#39;s <code>ses_...</code> ID.</p><p>Check the session from the CLI:</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 session ses_... --prod --slug weather-agent</span></span></code></pre></div><p>While the turn runs, the command reports how many events have arrived and prints <code>Turn running; runs may lag behind events.</code> Rerun it until the latest run shows a final status such as <code>finished</code>. High-effort turns can take about eight minutes, and runs can stay empty until the turn ends, so a growing event count is the progress signal. Escalate only when no new events arrive for about two to three minutes.</p><p>Hosted deployments don&#39;t support <code>bdk call</code> or <code>bdk sessions</code>, so use <code>bdk run --prod</code> and <code>bdk session</code> instead. Dashboard links to a single session may not open yet, so confirm the result with <code>bdk session</code>.</p><h3 id="call-the-hosted-http-api" tabindex="-1">Call the hosted HTTP API <a class="header-anchor" href="#call-the-hosted-http-api" aria-label="Permalink to &quot;Call the hosted HTTP API&quot;">​</a></h3><p>External HTTP clients use the stable alias URL and send the alias token on every request:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_ALIAS_URL</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/health&quot;</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;"> &quot;X-Agent-Alias-Token: </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_ALIAS_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>The first deploy prints this token once. Store it outside terminal transcripts; it cannot be retrieved later. If it is lost or exposed, <code>bdk rotate-token weather-agent</code> replaces it and invalidates the old value.</p><p><code>deployment --json</code> can include short-lived access headers, so treat that output as a credential too.</p><p>For a custom webhook whose provider cannot send the alias token, use <code>publicEndpoint()</code> only when the channel verifies the provider signature. That opens the custom channel path, not the built-in session or tool APIs. See <a href="./guides/webhooks.html">Webhooks</a>.</p><h2 id="update-the-deployment" tabindex="-1">Update the deployment <a class="header-anchor" href="#update-the-deployment" aria-label="Permalink to &quot;Update the deployment&quot;">​</a></h2><p>Push the new ref and deploy the same slug. The stable URL remains while the new generation replaces the previous one.</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 deploy --dir . --slug weather-agent</span></span></code></pre></div><p>A redeploy replaces its source, its watched repositories, and any egress domains supplied through CLI flags. Pass every <code>--cursor-events-repo</code> value again; without the flag, the deployment watches its GitHub source repository. Keep source-controlled egress in the <code>hosting</code> block when possible.</p><p>Use <code>bdk deployment weather-agent</code> to inspect a rollout. The <a href="./reference/cli.html#deploy">CLI reference</a> owns <code>--no-wait</code>, multi-agent deployment, stop, and delete behavior.</p><h2 id="keep-state-across-replacements" tabindex="-1">Keep state across replacements <a class="header-anchor" href="#keep-state-across-replacements" aria-label="Permalink to &quot;Keep state across replacements&quot;">​</a></h2><p>Managed hosting persists framework-owned session, KV, and file state across normal runtime replacements. Files written elsewhere on the runtime&#39;s local filesystem are disposable; use <code>ctx.host.kv</code> or <code>ctx.host.files</code> for durable application state.</p><p>Parked approvals and in-memory reminder handlers do not survive a restart. Run the turn again or recreate the reminder after a replacement.</p><h2 id="self-host-securely" tabindex="-1">Self-host securely <a class="header-anchor" href="#self-host-securely" aria-label="Permalink to &quot;Self-host securely&quot;">​</a></h2><p>Run BDK under Node 22.13 or newer, never Bun. One supervised process can serve every agent under a directory while a persistent state root keeps sessions across restarts.</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>export CURSOR_API_KEY=&quot;&lt;cursor-api-key&gt;&quot;</span></span>
-<span class="line"><span>export BDK_BEARER_TOKEN=&quot;$(openssl rand -hex 32)&quot;</span></span>
-<span class="line"><span></span></span>
-<span class="line"><span>bdk serve \\</span></span>
-<span class="line"><span>  --dir /srv/agents \\</span></span>
-<span class="line"><span>  --host 127.0.0.1 \\</span></span>
-<span class="line"><span>  --port 3000 \\</span></span>
-<span class="line"><span>  --state-root /var/lib/bdk \\</span></span>
-<span class="line"><span>  --bearer-token &quot;$BDK_BEARER_TOKEN&quot;</span></span></code></pre></div><p>Before exposing the host:</p><ul><li><p>Put TLS or an authenticating proxy in front of the loopback server.</p></li><li><p>Keep <code>--bearer-token</code> on shared hosts. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</p></li><li><p>Mount <code>--state-root</code> on a persistent volume outside the agent repository and back it up.</p></li><li><p>Inject credentials at startup instead of baking them into an image.</p></li><li><p>Run the process under a supervisor and enable schedules on exactly one serving process per project.</p></li></ul><p>Containers use the same command with <code>--host 0.0.0.0</code>, a mounted state volume, and an authenticating network boundary. The <a href="./reference/channels.html#auth-policies">Channels reference</a> covers per-caller and channel-specific auth.</p><h2 id="observability" tabindex="-1">Observability <a class="header-anchor" href="#observability" aria-label="Permalink to &quot;Observability&quot;">​</a></h2><p>Use <code>bdk session &lt;sessionId&gt; --prod</code> for a hosted session&#39;s runs and logs, <a href="./guides/opentelemetry.html">OpenTelemetry</a> for traces and metrics, and <a href="./reference/sessions.html#inspect-a-saved-event-stream">session traces</a> for a local conversation.</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/migrate.html">Early-alpha migration</a>: move a hosted architecture v1 project to v2 through a reviewed pull request</li><li><a href="./reference/cli.html#deploy">CLI reference</a>: inspect, update, stop, delete, and rotate deployments</li><li><a href="./guides/github.html">GitHub</a>: Cursor-event repositories and direct webhook delivery</li><li><a href="./guides/slack.html">Slack</a>: provision a dedicated hosted Slack app</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: persist OAuth credentials across hosted replacements</li><li><a href="./troubleshooting.html">Troubleshooting</a>: diagnose failed or stale deployments</li></ul>`,52)])])}const g=s(o,[["render",i]]);export{u as __pageData,g as default};

package/dist/docs/assets/guides_cloud-agents.md.CWJjS9No.js

@@ -1,10 +0,0 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let a BDK agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.","frontmatter":{"title":"Cursor cloud agents","description":"Let a BDK agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),o={name:"guides/cloud-agents.md"};function i(r,e,h,l,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="cloud-agents" tabindex="-1">Cloud agents <a class="header-anchor" href="#cloud-agents" aria-label="Permalink to &quot;Cloud agents&quot;">​</a></h1><p>The <code>cursor-cloud-agents</code> extension adds repository delegation to an existing BDK conversation. Cloud agents work on repository checkouts and push branches and pull requests; your agent can hand off a task, keep talking while it runs, inspect the result, and steer or stop the same branch.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/cloud.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorCloudAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions/cursor-cloud-agents&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;"> cursorCloudAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/api&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    autoCreatePR: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</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;">  needsApproval: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</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>Launches run under the host&#39;s signed-in account (<code>bdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>) and spend its cloud-agent budget. Name the repositories the agent may target, and keep approval on when you can&#39;t.</p><p>Launch approval resolves through the serving host.</p><h2 id="what-the-agent-can-do" tabindex="-1">What the agent can do <a class="header-anchor" href="#what-the-agent-can-do" aria-label="Permalink to &quot;What the agent can do&quot;">​</a></h2><p>With the extension mounted, the agent can hand off coding work and stay in the conversation while it happens:</p><ul><li><strong>Hand off a task.</strong> Launch a cloud agent on one of your repositories, or on a pull request, with a self-contained brief. It gets back an agent id and a URL to share.</li><li><strong>Check on it.</strong> See whether the agent is still running, what it produced, and which branches or pull requests it pushed.</li><li><strong>Read what was done.</strong> Pull the agent&#39;s full conversation into the workspace, quote its final report, or trace the exact edits before summarizing for a person.</li><li><strong>Steer or stop.</strong> Send a follow-up to an agent it launched; it queues behind the current run, or interrupts it on request. Cancel a run that went sideways.</li><li><strong>Keep track.</strong> List the agents launched in this conversation, or everything it has launched before.</li></ul><p>A skill teaches the model when to delegate, how to write a brief a cloud agent can act on alone, and how to follow up. Everything the extension launches stays bound to whoever launched it: an agent started by another user, or outside the extension, is out of reach. That separation is only as fine as your host&#39;s auth; a shared bearer token or <code>--allow-anonymous</code> makes every caller one principal, so use <a href="./../reference/channels.html#auth-policies">authored auth</a> when callers need their own.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>cloud</code></td><td>Launch defaults for repositories, environment, and pull request behavior.</td></tr><tr><td><code>cloud.repos</code></td><td>The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can&#39;t name one, so secrets in <code>cloud.envVars</code> never reach a repository you didn&#39;t list.</td></tr><tr><td><code>model</code></td><td>The model launched agents run. Omit it to use the account default.</td></tr><tr><td><code>needsApproval</code></td><td>Park launches and follow-ups for a <a href="./../reference/tools.html#gate-a-tool-on-human-approval">human decision</a>. Defaults to <code>true</code> when no <code>cloud.repos</code> are configured, <code>false</code> otherwise.</td></tr><tr><td><code>apiKey</code></td><td>A Cursor API key to launch with instead of the host&#39;s own.</td></tr></tbody></table><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to &quot;Adjust it&quot;">​</a></h2><p>To take a capability away, such as sending follow-ups, mount as a directory and disable that tool; see <a href="./../reference/extensions.html#adjust-a-mounted-extension">overlays</a>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: where parked launches get approved</li></ul>`,17)])])}const g=t(o,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_cloud-agents.md.CWJjS9No.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let a BDK agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval.","frontmatter":{"title":"Cursor cloud agents","description":"Let a BDK agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),o={name:"guides/cloud-agents.md"};function i(r,e,h,l,d,c){return s(),a("div",null,[...e[0]||(e[0]=[n("",17)])])}const g=t(o,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_grokbot-agents.md.tD1smFhU.js

@@ -1,16 +0,0 @@
-import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.","frontmatter":{"title":"Cursor Grok Bot agents","description":"Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work."},"headers":[],"relativePath":"guides/grokbot-agents.md","filePath":"guides/grokbot-agents.md"}'),o={name:"guides/grokbot-agents.md"};function i(r,e,l,h,p,d){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="grok-bot-agents" tabindex="-1">Grok Bot agents <a class="header-anchor" href="#grok-bot-agents" aria-label="Permalink to &quot;Grok Bot agents&quot;">​</a></h1><p>The <code>cursor-grokbot-agents</code> extension lets a BDK agent consult the Grok Bot agents on its serve host&#39;s Cursor account. The bot keeps its existing conversation, memory, and tools, while your agent carries the delivered reply back into the current conversation.</p><p>Use this extension on the local runtime. It consults another Grok Bot; it does not move this agent onto a Grok Bot runtime.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to &quot;Mount it&quot;">​</a></h2><p>List the bots your agent may contact and decide whether each new message needs approval. Descriptions teach the model when to choose one bot over another.</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/grokbot.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorGrokBotAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/extensions/cursor-grokbot-agents&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;"> cursorGrokBotAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agents: [</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;">      name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Plan Keeper&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Decides whether outdoor plans should move.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Chief of Staff&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Routes work and tracks priorities.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  needsApproval: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</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>Mounted as <code>grokbot</code>, the extension contributes <code>grokbot__ask</code>, <code>grokbot__check</code>, <code>grokbot__interrupt</code>, and <code>grokbot__list</code>, plus guidance for consulting them.</p><p>You can also scaffold the packaged example:</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 init ./grokbot --template grokbot-agents</span></span></code></pre></div><h2 id="ask-a-named-bot" tabindex="-1">Ask a named bot <a class="header-anchor" href="#ask-a-named-bot" aria-label="Permalink to &quot;Ask a named bot&quot;">​</a></h2><p>When someone says, &quot;Ask Plan Keeper whether we should move the picnic,&quot; your agent prepares one self-contained message, requests approval, and waits for the bot&#39;s delivered reply. That reply appears in the current conversation as the consultation result.</p><p>The message must include who is asking, the relevant facts, and the shape of the answer. The Grok Bot does not see the current BDK conversation.</p><blockquote><p>Avery is deciding whether to move Saturday&#39;s picnic. The forecast is 70% rain from 1-4pm. Recommend keep or move, give one reason, and name the best alternate time.</p></blockquote><p>When exactly one bot is configured, the model may omit its name.</p><h2 id="keep-waiting-for-a-long-reply" tabindex="-1">Keep waiting for a long reply <a class="header-anchor" href="#keep-waiting-for-a-long-reply" aria-label="Permalink to &quot;Keep waiting for a long reply&quot;">​</a></h2><p>If the bot is still working when <code>ask</code> reaches its wait limit, the tool returns <code>status: &quot;running&quot;</code> and any reply received so far. Your agent calls <code>check</code> for the same bot and reports the final answer when it arrives.</p><p><code>check</code> advances this caller&#39;s read position, so it returns only replies not already consumed. Check when the answer is needed instead of polling in a tight loop.</p><p>Earlier unread replies can arrive alongside the current result. Keep their order and pass them on when they still matter.</p><h2 id="interrupt-a-bot-turn" tabindex="-1">Interrupt a bot turn <a class="header-anchor" href="#interrupt-a-bot-turn" aria-label="Permalink to &quot;Interrupt a bot turn&quot;">​</a></h2><p>Use <code>interrupt</code> when the bot is pursuing the wrong task or the person changes direction. The active turn stops, but the host account&#39;s conversation with that bot remains, so a later <code>ask</code> continues with its existing memory.</p><blockquote><p>Stop Plan Keeper&#39;s current turn. Then ask it to compare indoor venues instead of changing the time.</p></blockquote><p>Only <code>ask</code> uses <code>needsApproval</code>. <code>check</code> and <code>interrupt</code> execute without an approval card, so expose this extension only to callers who may read or stop those bot conversations.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p><code>agents</code> is a name allowlist, not an existence check. A name outside the list is refused, but a misspelled configured name may create a new empty bot on first use. If a result says <code>created: true</code>, tell the person and check the name before sending more work.</p><p>With no <code>agents</code> list, any name is allowed and approval defaults on. Prefer an explicit list for a shared agent. <code>list</code> returns configured bots and bots this caller already contacted; it does not enumerate the whole account.</p><p>Calls use the serve host credential: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or <code>bdk login</code>. Use <code>apiKey</code> only when the extension should run under a different account.</p><p><code>pollIntervalMs</code> changes how often a waiting tool reads for new bot output. Keep the default unless the service needs a different balance between response latency and request volume.</p><h2 id="account-and-caller-boundaries" tabindex="-1">Account and caller boundaries <a class="header-anchor" href="#account-and-caller-boundaries" aria-label="Permalink to &quot;Account and caller boundaries&quot;">​</a></h2><p>Every tool reaches the serve host account&#39;s existing Grok Bot conversation. Authenticated BDK callers have separate contact lists and read positions, but they do not get separate Grok Bot accounts or isolated bot memory.</p><p>A shared bearer token or anonymous host also collapses callers into one BDK principal. Use per-caller auth when contact history and read positions must remain separate.</p><p>If <code>ask</code> finds the bot busy with an earlier message, it sends nothing. For a bot this caller already contacted, use <code>check</code> or <code>interrupt</code>. On first contact, wait for the existing turn in the Grok Bot app to finish, then ask again.</p><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to &quot;Adjust it&quot;">​</a></h2><p>To remove a capability such as <code>interrupt</code>, mount the extension as a directory and disable that tool. See <a href="./../reference/extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./../reference/extensions.html">Extensions</a>: namespaces, trust, and overlays</li><li><a href="./../reference/tools.html#gate-a-tool-on-human-approval">Tool approvals</a>: approve asks</li></ul>`,35)])])}const k=t(o,[["render",i]]);export{u as __pageData,k as default};

package/dist/docs/assets/guides_mcp-oauth.md.DR3zhC9r.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.","frontmatter":{"title":"Host MCP OAuth","description":"Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent."},"headers":[],"relativePath":"guides/mcp-oauth.md","filePath":"guides/mcp-oauth.md"}'),n={name:"guides/mcp-oauth.md"};function h(l,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",28)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_channels.md.LbNIJBwd.js

@@ -1,23 +0,0 @@
-import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication.","frontmatter":{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),i={name:"reference/channels.md"};function o(d,e,r,h,l,c){return a(),s("div",null,[...e[0]||(e[0]=[n(`<h1 id="channels" tabindex="-1">Channels <a class="header-anchor" href="#channels" aria-label="Permalink to &quot;Channels&quot;">​</a></h1><p>A channel connects an external surface to agent sessions. A file at <code>bot/channels/&lt;id&gt;.ts</code> defines channel <code>&lt;id&gt;</code> and mounts its routes under <code>/v1/channels/&lt;id&gt;</code>. The built-in HTTP session channel is always available alongside any custom or prebuilt channels.</p><h2 id="built-in-http-channel" tabindex="-1">Built-in HTTP channel <a class="header-anchor" href="#built-in-http-channel" aria-label="Permalink to &quot;Built-in HTTP channel&quot;">​</a></h2><p>The built-in channel serves the session, approval, tool, discovery, and health routes. In a multi-agent host, each agent&#39;s routes sit under its slug. See the <a href="./http-api.html">HTTP API</a> for request and response contracts.</p><h2 id="define-a-custom-channel" tabindex="-1">Define a custom channel <a class="header-anchor" href="#define-a-custom-channel" aria-label="Permalink to &quot;Define a custom channel&quot;">​</a></h2><p>Use <code>defineChannel</code> with one or more typed routes:</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;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels&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;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes: [</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</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;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review a pull request on this channel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      bodySchema: 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;">        message: 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;">        prUrl: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }),</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      handler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_request</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> session</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">          \`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Pull request: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`pr:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        );</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ sessionId: session.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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The route above is <code>POST /v1/channels/&lt;id&gt;/review</code>. Calls for the same pull request reuse one conversation because they pass the same continuation token.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p>Route paths must begin with <code>/</code>. The method helper determines which Zod schemas the route accepts:</p><table tabindex="0"><thead><tr><th>Helper</th><th>Schema contract</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>querySchema</code> is required</td></tr><tr><td><code>POST</code>, <code>PUT</code>, <code>PATCH</code></td><td><code>bodySchema</code> is required; <code>querySchema</code> is optional</td></tr><tr><td><code>DELETE</code></td><td>Both schemas are optional</td></tr></tbody></table><p>Plain JSON Schema objects don&#39;t type-check. Use <code>z.object({})</code> or <code>z.unknown()</code> for an open surface. The host validates the body and query before calling the handler, returning <code>400</code> on failure; an empty body is read as <code>{}</code>. Declared schemas also appear in <code>GET /v1/info</code> for playground requests and slash commands.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>Each handler receives the Fetch <code>Request</code> and a typed arguments object.</p><table tabindex="0"><thead><tr><th>Member</th><th>Contract</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Start or resume a session on this channel</td></tr><tr><td><code>getSession(sessionId)</code></td><td>Return this channel&#39;s session, or <code>null</code></td></tr><tr><td><code>receive(channel, input)</code></td><td>Hand work to another channel</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td><a href="./tools.html#call-a-tool-without-a-model-turn">Call a server tool</a> without a model turn</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated inputs and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> returned by the route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address, or <code>null</code></td></tr><tr><td><code>host</code></td><td>Shared MCP, provider, storage, telemetry, and reminder services</td></tr><tr><td><code>waitUntil(promise)</code></td><td>Track work after the response returns</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Build absolute playground and trace URLs for this mount</td></tr><tr><td><code>artifacts</code></td><td>List or tag <a href="./artifacts.html">artifacts</a>; pass <code>sessionId</code> when attributing one</td></tr></tbody></table><h3 id="send-options" tabindex="-1"><code>send</code> options <a class="header-anchor" href="#send-options" aria-label="Permalink to &quot;\`send\` options&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Resume the session with this channel-local key, or create one when the key is new</td></tr><tr><td><code>admission</code></td><td><code>&quot;preempt&quot;</code> interrupts a busy turn; <code>&quot;coalesce&quot;</code> queues behind it. The default is <code>&quot;preempt&quot;</code></td></tr><tr><td><code>workspaceFiles</code></td><td>Add relative files for the next turn</td></tr><tr><td><code>workspaceDir</code></td><td>Use an absolute local working directory</td></tr><tr><td><code>auth</code></td><td>Set the session principal; defaults to the request principal</td></tr><tr><td><code>state</code></td><td>Set starting channel state for a new session</td></tr><tr><td><code>title</code></td><td>Set the display title for a new session</td></tr><tr><td><code>purpose</code></td><td>Use <code>&quot;eval&quot;</code> to mark a new session as regression traffic</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools for a new session</td></tr><tr><td><code>asOf</code></td><td>Freeze a new session at an ISO-8601 instant with a timezone</td></tr></tbody></table><p><code>send</code> returns a <code>ChannelSession</code>. Its <code>id</code> identifies the session, <code>continuationToken</code> contains its current channel key, and <code>isNew</code> says whether this call created it. A coalesced call also returns <code>coalesced: true</code>.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code>. Each handler receives <code>(event, channel, ctx)</code>, including the session&#39;s <code>channel.state</code>, session info, and shared host services. Use these handlers to deliver progress and replies to the surface that owns the channel.</p><h2 id="session-state" tabindex="-1">Session state <a class="header-anchor" href="#session-state" aria-label="Permalink to &quot;Session state&quot;">​</a></h2><p><code>state</code> on the channel definition supplies starting JSON for each new session. A route can instead pass <code>state</code> to <code>send</code>; event handlers read and update the active value through <code>channel.state</code>.</p><h2 id="start-and-stop-a-channel" tabindex="-1">Start and stop a channel <a class="header-anchor" href="#start-and-stop-a-channel" aria-label="Permalink to &quot;Start and stop a channel&quot;">​</a></h2><p><code>onStart(args)</code> runs when the channel mounts, and <code>onStop()</code> runs when the host stops. <code>onStart</code> receives the route helpers plus these transport controls:</p><table tabindex="0"><thead><tr><th>Helper</th><th>Contract</th></tr></thead><tbody><tr><td><code>emitAssistantMessage(sessionId, text)</code></td><td>Append final assistant text without starting a model turn</td></tr><tr><td><code>hasContinuationSession(token)</code></td><td>Check whether a token maps to a session</td></tr><tr><td><code>isContinuationBusy(token)</code></td><td>Check whether a turn is active for a token</td></tr><tr><td><code>interruptContinuation(token)</code></td><td>Stop the active turn and clear queued coalesced follow-ups</td></tr><tr><td><code>resolveApproval(...)</code></td><td>Approve or deny a parked tool call</td></tr></tbody></table><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs the channel&#39;s <code>auth</code> array. The default is <code>[localDevStrict()]</code>. Policies may be asynchronous; the first one to return an <code>AuthContext</code> admits the request, and an all-null result returns <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback requests with a loopback hostname and no proxy-forwarding headers</td></tr><tr><td><code>localDev()</code></td><td>Direct loopback requests with no proxy-forwarding headers, without checking the hostname</td></tr><tr><td><code>loopbackOnly()</code></td><td>Any loopback TCP peer, including local relays that carry forwarding headers</td></tr><tr><td><code>bearerAuth(tokenOrVerify)</code></td><td>A matching bearer token, or a token accepted by the verifier</td></tr><tr><td><code>sharedSecretAuth({ header, secret })</code></td><td>A header matching the named environment or deployment secret</td></tr><tr><td><code>hmacSignatureAuth({ header, secret, prefix? })</code></td><td>A hex HMAC-SHA256 signature over the raw body using the named secret</td></tr><tr><td><code>allowAll()</code></td><td>Every caller as an anonymous principal</td></tr><tr><td><code>publicEndpoint()</code></td><td>Every caller on this custom channel; managed hosting also exposes the route without an alias token</td></tr></tbody></table><p>Use <code>allowAll()</code> only for an intentionally public surface or one protected upstream. With <code>publicEndpoint()</code>, the handler must verify the provider&#39;s signature. The policy applies only to custom channel routes; it doesn&#39;t open the built-in session or tool API.</p><p>The resolved <code>AuthContext</code> (<code>{ authenticator, principalId, principalType, attributes? }</code>) becomes the request principal. Sessions belong to the principal that created them, and other principals receive <code>403</code> on owned routes.</p><p>Server flags interact with authored auth: <code>--bearer-token</code> swaps the default <code>localDevStrict()</code> for <code>bearerAuth(...)</code> on channels that don&#39;t author their own chain, and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>. An authored <code>auth</code> array always takes precedence.</p><h2 id="prebuilt-channels" tabindex="-1">Prebuilt channels <a class="header-anchor" href="#prebuilt-channels" aria-label="Permalink to &quot;Prebuilt channels&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Import</th><th>Function</th><th>Surface</th></tr></thead><tbody><tr><td><code>@cursor/bdk/channels/slack</code></td><td><code>slackChannel()</code></td><td>Slack messages, threads, streaming replies, and approvals. See <a href="./../guides/slack.html">Slack</a></td></tr><tr><td><code>@cursor/bdk/channels/github</code></td><td><code>githubChannel()</code></td><td>GitHub and GitHub Enterprise webhooks. See <a href="./../guides/github.html">GitHub</a></td></tr><tr><td><code>@cursor/bdk/channels/gitlab</code></td><td><code>gitlabChannel()</code></td><td>GitLab.com and self-managed GitLab hooks. See <a href="./../guides/gitlab.html">GitLab</a></td></tr><tr><td><code>@cursor/bdk/channels/bitbucket</code></td><td><code>bitbucketChannel()</code></td><td>Bitbucket Cloud and Data Center hooks. See <a href="./../guides/bitbucket.html">Bitbucket</a></td></tr><tr><td><code>@cursor/bdk/channels/deployments</code></td><td><code>deploymentsChannel()</code></td><td>Deployment events filtered by source, environment, or event name</td></tr></tbody></table><p>For other platforms like Discord or Teams, use the authored <code>defineChannel</code> route form.</p><h2 id="continuation-tokens" tabindex="-1">Continuation tokens <a class="header-anchor" href="#continuation-tokens" aria-label="Permalink to &quot;Continuation tokens&quot;">​</a></h2><p>Each channel defines its continuation-token format. The same token resumes the same conversation; the built-in HTTP channel rotates its opaque token after every accepted follow-up and returns <code>409</code> for a stale token. See <a href="./sessions.html#session-identifiers">Session identifiers</a> for the full contract.</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/webhooks.html">Webhooks</a></li><li><a href="./http-api.html">HTTP API</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./hooks.html">Hooks</a></li></ul>`,38)])])}const u=t(i,[["render",o]]);export{k as __pageData,u as default};

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

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

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

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

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

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

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

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

package/dist/docs/assets/reference_tools.md.DzIY9JzY.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",60)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/troubleshooting.md.x-GBa7wN.js

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

package/dist/internal/convert-automation/slug.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"slug.d.ts","sourceRoot":"","sources":["../../../src/internal/convert-automation/slug.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAElD,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,+EAA+E;AAC/E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAE1C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAY1B;CACF"}