npm - @cursor/bdk - Versions diffs - 0.2.25 → 0.2.27 - Mend

@cursor/bdk 0.2.25 → 0.2.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (449) hide show

package/dist/docs/assets/guides_opentelemetry.md.D4wO7_8v.js ADDED Viewed

@@ -0,0 +1,37 @@
+import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"OpenTelemetry","description":"","frontmatter":{},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function d(o,s,r,h,l,p){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to &quot;OpenTelemetry&quot;"></a></h1><p>BDK exports traces, metrics, and logs to an OTLP collector. You configure that with standard <code>OTEL_*</code> environment variables. There is no <code>defineOtel</code> or <code>register()</code> hook. <code>ctx.host.otel</code> is deprecated. It still runs for this release and logs one warning per process. Set <code>OTEL_*</code> variables and record with <code>metrics.getMeter</code> and <code>trace.getTracer</code> from <code>@opentelemetry/api</code>.</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Authorization=Bearer </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$OTEL_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident-agent</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><p>The default protocol is OTLP/HTTP protobuf. Set <code>OTEL_EXPORTER_OTLP_PROTOCOL=http/json</code> when the collector only accepts JSON. <code>grpc</code> is not supported. BDK logs a warning and uses <code>http/protobuf</code>.</p><p>Metrics use delta temporality by default. BDK logs that default when export starts. For Grafana Cloud or Prometheus, set <code>OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE</code> to <code>cumulative</code>. Grafana Cloud rejects delta metrics.</p><p>BDK installs trace, metric, and log providers before it imports <code>bot/agent.ts</code>. A meter, tracer, or logger created at module scope binds to those providers. Exporters attach when the process has the <code>OTEL_*</code> variables. On a hosted agent that is the first request, after secrets are in the environment.</p><p>With no OTLP endpoint, BDK adds no exporters. Outbound <code>fetch</code> does not gain a <code>traceparent</code> header. The session collector stays disabled.</p><h2 id="variables" tabindex="-1">Variables <a class="header-anchor" href="#variables" aria-label="Permalink to &quot;Variables&quot;"></a></h2><table tabindex="0"><thead><tr><th>Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td><td>Base URL. BDK appends <code>/v1/traces</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</code></td><td>Traces URL, used as written. It wins over the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</code></td><td>Metrics URL, used as written. It wins over the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</code></td><td>Logs URL, used as written. It wins over the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_HEADERS</code></td><td>Headers on every export. Values are URL-encoded. Read again on each export.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code></td><td><code>http/protobuf</code> (default) or <code>http/json</code>. gRPC is not supported.</td></tr><tr><td><code>OTEL_SERVICE_NAME</code></td><td><code>service.name</code>. Default is the agent name, then <code>unknown_service:node</code>.</td></tr><tr><td><code>OTEL_RESOURCE_ATTRIBUTES</code></td><td>Resource attributes, including <code>service.namespace</code>, <code>service.version</code>, and <code>deployment.environment.name</code>.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE</code></td><td><code>delta</code> (default), <code>cumulative</code>, or <code>lowmemory</code>. Use <code>cumulative</code> for Grafana Cloud.</td></tr><tr><td><code>OTEL_LOGS_EXPORTER</code></td><td><code>otlp</code> turns logs on. Unset, <code>none</code>, and <code>console</code> leave OTLP logs off.</td></tr><tr><td><code>OTEL_SDK_DISABLED</code></td><td><code>true</code> turns export off.</td></tr><tr><td><code>OTEL_TRACES_EXPORTER</code></td><td><code>none</code> turns traces off.</td></tr><tr><td><code>OTEL_METRICS_EXPORTER</code></td><td><code>none</code> turns metrics off.</td></tr><tr><td><code>OTEL_LOG_USER_PROMPTS</code></td><td><code>1</code> puts prompt text on log records.</td></tr><tr><td><code>OTEL_LOG_TOOL_CONTENT</code></td><td><code>1</code> puts tool payloads on log records.</td></tr></tbody></table><h2 id="hosted-agents" tabindex="-1">Hosted agents <a class="header-anchor" href="#hosted-agents" aria-label="Permalink to &quot;Hosted agents&quot;"></a></h2><p>Set the endpoint, headers, and service name as secrets. Add the collector host to <code>hosting.egressDomains</code>. The host is a hostname with no scheme and no path.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  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;otlp-gateway-prod-us-east-0.grafana.net&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>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;OTEL_EXPORTER_OTLP_ENDPOINT&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;OTEL_EXPORTER_OTLP_HEADERS&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">      &quot;OTEL_SERVICE_NAME&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;">});</span></span></code></pre></div><p>Secrets arrive with the first request that has an endpoint. That request&#39;s export uses those headers and <code>service.name</code>. A later <code>bdk secrets set</code> updates headers on the next export, including a rotated key. BDK also replaces the exporter when the URL, protocol, or signal list changes. <code>service.name</code> is fixed on the first export that attaches. Redeploy to change the service name.</p><h2 id="what-you-can-record" tabindex="-1">What you can record <a class="header-anchor" href="#what-you-can-record" aria-label="Permalink to &quot;What you can record&quot;"></a></h2><p>Create the tracer, meter, and logger at module scope.</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;"> { metrics, trace } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@opentelemetry/api&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;"> { logs } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@opentelemetry/api-logs&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tracer</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> trace.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getTracer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</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;"> lookups</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> metrics.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getMeter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createCounter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident.lookups&quot;</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;"> logger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> logs.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getLogger</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Record during a request, after secrets have loaded. A span or a log record that ends before the exporters attach is still exported. BDK holds up to 2048 spans and 2048 log records until the exporters attach, then sends them. BDK drops each record past that limit. A metric recorded before the first collect is included in that collect.</p><p>BDK also records HTTP spans, token counts, and tool calls on the session. Those spans carry <code>cursor.conversation.id</code>. A span you start with <code>trace.getTracer</code> during a turn or a tool call gets the same attribute from the active context. A value you set on the span stays. BDK does not overwrite it. The id stays in this process. It is not propagated.</p><p>A metric does not get <code>cursor.conversation.id</code>. Read the id and set the attribute yourself.</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;"> { metrics } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@opentelemetry/api&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;"> { currentConversationId } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/otel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> lookups</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> metrics.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getMeter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createCounter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident.lookups&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">lookups.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cursor.conversation.id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">currentConversationId</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() });</span></span></code></pre></div><p>Prompt text and tool payloads stay off log records unless logs are on (<code>OTEL_LOGS_EXPORTER=otlp</code>) and you set <code>OTEL_LOG_USER_PROMPTS</code> or <code>OTEL_LOG_TOOL_CONTENT</code>.</p><h2 id="limits" tabindex="-1">Limits <a class="header-anchor" href="#limits" aria-label="Permalink to &quot;Limits&quot;"></a></h2><p>These are not supported yet.</p><ul><li>Custom span processors, samplers, and views.</li><li>Bringing your own OpenTelemetry SDK.</li><li>Library auto-instrumentation.</li><li>A <code>register()</code> hook. There is no ticket for it yet.</li><li><code>OTEL_TRACES_SAMPLER</code> and <code>OTEL_METRIC_EXPORT_INTERVAL</code> that arrive only with hosted secrets. BDK reads them when it builds the provider, which is before that secret load. Set them on the process, then restart. BDK logs a warning when a later value differs.</li></ul><p>Do not import your own SDK providers next to BDK&#39;s. BDK logs a warning when a module replaces a provider BDK registered. The global API then uses that module&#39;s provider. BDK shuts down a provider it created only when that provider is not the one it registered.</p><h2 id="migrating-from-serve-otel" tabindex="-1">Migrating from serve({ otel }) <a class="header-anchor" href="#migrating-from-serve-otel" aria-label="Permalink to &quot;Migrating from serve({ otel })&quot;"></a></h2><p><code>serve({ otel })</code> is removed. Delete the option. Set the same values with <code>OTEL_*</code> variables. Delete <code>bot/otel.ts</code>, <code>agent/otel.ts</code>, and <code>bot/instrumentation.ts</code>. Do not call <code>defineOtel</code>.</p><p>BDK sends each signal to one URL. A second exporter for the same signal has no variable.</p><table tabindex="0"><thead><tr><th>Old option</th><th>Set this instead</th></tr></thead><tbody><tr><td><code>serviceName</code></td><td><code>OTEL_SERVICE_NAME</code></td></tr><tr><td><code>serviceVersion</code></td><td><code>service.version</code> in <code>OTEL_RESOURCE_ATTRIBUTES</code></td></tr><tr><td><code>resourceAttributes</code></td><td><code>OTEL_RESOURCE_ATTRIBUTES</code>. Separate pairs with commas. URL-encode each value.</td></tr><tr><td><code>exporters[].url</code></td><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code>. BDK appends <code>/v1/traces</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>.</td></tr><tr><td><code>exporters[].url</code> with <code>signals</code></td><td><code>OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</code>, <code>OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</code>, or <code>OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</code>. BDK uses that URL as written.</td></tr><tr><td><code>exporters[].headers</code></td><td><code>OTEL_EXPORTER_OTLP_HEADERS</code>. Separate pairs with commas. URL-encode each value.</td></tr><tr><td><code>exporters[].protocol</code></td><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code>. Use <code>http/protobuf</code> or <code>http/json</code>. For one signal, use <code>OTEL_EXPORTER_OTLP_TRACES_PROTOCOL</code>, <code>OTEL_EXPORTER_OTLP_METRICS_PROTOCOL</code>, or <code>OTEL_EXPORTER_OTLP_LOGS_PROTOCOL</code>.</td></tr><tr><td><code>exporters[].signals</code></td><td>Set the signal URL above. Set <code>OTEL_TRACES_EXPORTER</code>, <code>OTEL_METRICS_EXPORTER</code>, or <code>OTEL_LOGS_EXPORTER</code> to <code>none</code> to stop that signal.</td></tr><tr><td><code>traces: false</code></td><td><code>OTEL_TRACES_EXPORTER=none</code></td></tr><tr><td><code>traces: true</code></td><td>Leave <code>OTEL_TRACES_EXPORTER</code> unset. Traces start when an endpoint is set.</td></tr><tr><td><code>traces.sampleRatio</code></td><td><code>OTEL_TRACES_SAMPLER=parentbased_traceidratio</code> and <code>OTEL_TRACES_SAMPLER_ARG</code> set to the ratio. Set both before the process starts.</td></tr><tr><td><code>metrics: false</code></td><td><code>OTEL_METRICS_EXPORTER=none</code></td></tr><tr><td><code>metrics: true</code></td><td>Leave <code>OTEL_METRICS_EXPORTER</code> unset. Metrics start when a metrics URL is set.</td></tr><tr><td><code>metrics.exportIntervalMillis</code></td><td><code>OTEL_METRIC_EXPORT_INTERVAL</code>, in milliseconds. Set it before the process starts.</td></tr><tr><td><code>logs: false</code></td><td>Leave <code>OTEL_LOGS_EXPORTER</code> unset, or set it to <code>none</code>.</td></tr><tr><td><code>logs: true</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code></td></tr><tr><td><code>logs.userPrompts</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code> and <code>OTEL_LOG_USER_PROMPTS=1</code></td></tr><tr><td><code>logs.toolContent</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code> and <code>OTEL_LOG_TOOL_CONTENT=1</code></td></tr><tr><td><code>otel: false</code></td><td>Set no endpoint, or set <code>OTEL_SDK_DISABLED=true</code>.</td></tr></tbody></table><p>Before:</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;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  otel: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    serviceName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    exporters: [</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;">        url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://otel.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;">        headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">OTEL_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&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;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>After:</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident-agent</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Authorization=Bearer%20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$OTEL_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><p>On a hosted agent, put the same names in <code>hosting.secretNames</code>. Add the collector host to <code>hosting.egressDomains</code>. Then run:</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;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_EXPORTER_OTLP_HEADERS</span></span></code></pre></div>`,35)])])}const k=e(n,[["render",d]]);export{E as __pageData,k as default};

package/dist/docs/assets/guides_opentelemetry.md.D4wO7_8v.lean.js ADDED Viewed

@@ -0,0 +1 @@

+ import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"OpenTelemetry","description":"","frontmatter":{},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function d(o,s,r,h,l,p){return i(),t("div",null,[...s[0]||(s[0]=[a("",35)])])}const k=e(n,[["render",d]]);export{E as __pageData,k as default};

package/dist/docs/assets/{guides_slack.md.Bn-WupSE.js → guides_slack.md.ClIyi7FI.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{_ as a,c as i,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),t={name:"guides/slack.md"};function l(h,s,p,k,o,r){return e(),i("div",null,[...s[0]||(s[0]=[n(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;"></a></h1><p>A Slack agent wakes when someone mentions it, sends it a DM, or posts in a channel it watches. From there, it keeps the conversation in one thread and can reply all at once, stream the answer live, or decide for itself when to post updates.</p><p>Run <code>bdk slack create --dir .</code>, then <code>bdk slack doctor</code>.</p><h2 id="answer-a-mention-or-dm" tabindex="-1">Answer a mention or DM <a class="header-anchor" href="#answer-a-mention-or-dm" aria-label="Permalink to &quot;Answer a mention or DM&quot;"></a></h2><p>Mention the bot in a channel or send it a DM, and it will answer in a thread on that message. Any follow-up in the same thread continues the conversation where it left off.</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/channels/slack.ts</span></span>
+import{_ as a,c as i,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,p,o,k,d){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;"></a></h1><p>A Slack agent wakes when someone mentions it, sends it a DM, or posts in a channel it watches. From there, it keeps the conversation in one thread and can reply all at once, stream the answer live, or decide for itself when to post updates.</p><p>Run <code>bdk slack create --dir .</code>, then <code>bdk slack doctor</code>.</p><h2 id="answer-a-mention-or-dm" tabindex="-1">Answer a mention or DM <a class="header-anchor" href="#answer-a-mention-or-dm" aria-label="Permalink to &quot;Answer a mention or DM&quot;"></a></h2><p>Mention the bot in a channel or send it a DM, and it will answer in a thread on that message. Any follow-up in the same thread continues the conversation where it left off.</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/channels/slack.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels/slack&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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -32,7 +32,12 @@ import{_ as a,c as i,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // \`post-update\` writes mid-turn progress and the final reply.</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agentic&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="wake-on-a-channel-post" tabindex="-1">Wake on a channel post <a class="header-anchor" href="#wake-on-a-channel-post" aria-label="Permalink to &quot;Wake on a channel post&quot;"></a></h2><p>This example watches <code>#triage-alerts</code>, so any substantial top-level message starts a thread even when nobody mentions the bot. The length guard filters out short posts before they can start a turn.</p><p>Mentions work in any channel the bot has joined. Listening without a mention requires an explicit allowlist with at least one channel ID starting with <code>C</code> or <code>G</code> and at most 10 distinct IDs. You can add <code>#name</code> entries for readability. A lone <code>&quot;*&quot;</code> watches replies in every joined channel (<code>posts: &quot;replies&quot;</code>), but it does not wake on top-level posts. Do not mix <code>&quot;*&quot;</code> with channel IDs.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="show-steps-as-cards-or-as-a-checklist" tabindex="-1">Show steps as cards or as a checklist <a class="header-anchor" href="#show-steps-as-cards-or-as-a-checklist" aria-label="Permalink to &quot;Show steps as cards or as a checklist&quot;"></a></h3><p>The agent calls <code>post-card</code> to show one step of its work, such as &quot;Scan the repo&quot;. Each card has an <code>id</code>, a <code>title</code>, a <code>status</code>, and optional <code>details</code>. When the agent calls <code>post-card</code> again with the same <code>id</code>, Slack updates that card. The agent uses this to move a step from <code>in_progress</code> to <code>complete</code>.</p><p><code>cards</code> sets how Slack draws these steps:</p><table tabindex="0"><thead><tr><th><code>cards</code></th><th>What Slack shows</th><th>Use it when</th></tr></thead><tbody><tr><td><code>{ display: &quot;timeline&quot; }</code> (default)</td><td>Each step is a separate card in the thread.</td><td>The turn has one or two short steps.</td></tr><tr><td><code>{ display: &quot;plan&quot; }</code></td><td>All steps from one turn are in one checklist.</td><td>The turn has several steps, and readers want to see progress in one place.</td></tr></tbody></table><p>This bot shows its steps as one checklist with the title &quot;Release check&quot;:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agentic&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    cards: { display: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plan&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Release check&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Know these rules for a plan:</p><ul><li>The <code>title</code> is optional. It can have at most 256 characters.</li><li>You set the <code>title</code> in the channel configuration. The agent cannot change the title.</li><li>Each turn starts a new checklist with the same title.</li><li>The <code>pending</code> status shows a step that has not started. Use <code>pending</code> only in a plan.</li><li><code>slackChannel</code> stops at startup if <code>cards</code> is not valid. For example, a <code>title</code> with <code>display: &quot;timeline&quot;</code> stops startup.</li></ul><p><code>display</code> is Slack&#39;s <a href="https://docs.slack.dev/reference/methods/chat.startStream/" target="_blank" rel="noreferrer"><code>task_display_mode</code></a>, and the channel sends <code>title</code> as a <code>plan_update</code> chunk.</p><h2 id="wake-on-a-channel-post" tabindex="-1">Wake on a channel post <a class="header-anchor" href="#wake-on-a-channel-post" aria-label="Permalink to &quot;Wake on a channel post&quot;"></a></h2><p>This example watches <code>#triage-alerts</code>, so any substantial top-level message starts a thread even when nobody mentions the bot. The length guard filters out short posts before they can start a turn.</p><p>Mentions work in any channel the bot has joined. Listening without a mention requires an explicit allowlist with at least one channel ID starting with <code>C</code> or <code>G</code> and at most 10 distinct IDs. You can add <code>#name</code> entries for readability. A lone <code>&quot;*&quot;</code> watches replies in every joined channel (<code>posts: &quot;replies&quot;</code>), but it does not wake on top-level posts. Do not mix <code>&quot;*&quot;</code> with channel IDs.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  engagement: {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channelPosts: {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;C0123ABCDEF&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;#triage-alerts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
@@ -67,4 +72,4 @@ import{_ as a,c as i,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Use the IDs on the hook <code>ctx</code> when handling an event, and <code>ctx.host.slack.getClient()</code> when a tool needs the Slack Web API.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to &quot;Connect&quot;"></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span></code></pre></div><p>After you sign in, <code>slack create</code> opens <strong>Add Slack to this agent</strong> in the browser and writes the resulting tokens to <code>.env.local</code> without printing them. You can open the same wizard from <strong>Integrations</strong> on <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>If Slack requires workspace-admin approval, keep <code>slack create</code> running and open the <strong>Request approval</strong> link printed by the CLI. Installing from the dashboard doesn&#39;t send that request for you. After an admin approves it, return to the dashboard&#39;s <strong>Add Slack</strong> wizard and select <strong>Retry</strong>.</p><p>If you already own the Slack app, initialize it with <code>bdk slack init --manual --dir . --name &quot;Triage&quot;</code> and follow the <a href="./../../skills/setup-slack/SKILL.html">Slack setup skill</a> for installation and tokens.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;"></a></h2><p>Run <code>doctor</code> first to catch missing credentials, then start the agent and send it the same mention or DM a teammate would.</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;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;"></a></h2><ul><li><p>If the tokens are missing, the Slack channel stays idle while the rest of <code>serve</code> starts normally.</p></li><li><p>Keep <code>channelPosts.allow</code> narrow because each qualifying post can start a model turn.</p></li><li><p>Set <code>envPrefix</code> when two Slack bots share a host so the token names do not collide.</p></li></ul><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="./../reference/cli.html#slack">CLI reference</a>: <code>slack create</code>, <code>doctor</code>, <code>init --manual</code></li><li><a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>: the companion skill for coding agents</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: host prep on mention and DM handlers</li><li><a href="./../evals.html">Evals</a>: freeze a mention as a regression check</li></ul>`,52)])])}const E=a(t,[["render",l]]);export{c as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;"></a></h2><ul><li><p>If the tokens are missing, the Slack channel stays idle while the rest of <code>serve</code> starts normally.</p></li><li><p>Keep <code>channelPosts.allow</code> narrow because each qualifying post can start a model turn.</p></li><li><p>Set <code>envPrefix</code> when two Slack bots share a host so the token names do not collide.</p></li></ul><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="./../reference/cli.html#slack">CLI reference</a>: <code>slack create</code>, <code>doctor</code>, <code>init --manual</code></li><li><a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>: the companion skill for coding agents</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: host prep on mention and DM handlers</li><li><a href="./../evals.html">Evals</a>: freeze a mention as a regression check</li></ul>`,61)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{guides_slack.md.Bn-WupSE.lean.js → guides_slack.md.ClIyi7FI.lean.js} RENAMED Viewed

	@@ -1 +1 @@
1	- import{_ as a,c as i,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),t={name:"guides/slack.md"};function l(h,s,p,k,~~o,r~~){return e(),i("div",null,[...s[0]\|\|(s[0]=[n("",52)])])}const E=a(t,[["render",l]]);export{c as __pageData,E as default};
1	+ import{_ as a,c as i,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,p,o,k,d){return e(),i("div",null,[...s[0]\|\|(s[0]=[t("",61)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_agent-config.md.IplwL25I.js → reference_agent-config.md.CZrbHOfT.js} RENAMED Viewed

@@ -1,4 +1,4 @@
-import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,h,r,p){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-config" tabindex="-1">Agent config <a class="header-anchor" href="#agent-config" aria-label="Permalink to &quot;Agent config&quot;"></a></h1><p><code>bot/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent and its local harness defaults. Everything is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,d,h,r,c){return i(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="agent-config" tabindex="-1">Agent config <a class="header-anchor" href="#agent-config" aria-label="Permalink to &quot;Agent config&quot;"></a></h1><p><code>bot/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent and its local harness defaults. Everything is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/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;">  model: {</span></span>
@@ -8,7 +8,7 @@ import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fast&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;true&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ],</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// optional; this is the default</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="agent-fields" tabindex="-1">Agent fields <a class="header-anchor" href="#agent-fields" aria-label="Permalink to &quot;Agent fields&quot;"></a></h2><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>persistent</code></td><td>boolean</td><td>Keep one long-lived runtime for the hosted deployment. Defaults to <code>false</code>. See <a href="#persistent-hosting">Persistent hosting</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames?, image? }</code></td><td>Managed-hosting declarations read by <code>bdk deploy</code>: the deployment&#39;s egress allowlist, the secret names the agent expects, and a container image for a <a href="#persistent-hosting">persistent agent</a>. Mounted <a href="./extensions.html#build-an-extension">extensions</a> add their own. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Agent-wide concurrent turn limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr><tr><td><code>tools</code></td><td><code>ToolName[]</code></td><td>Allowlist of built-in harness tools offered to the model. Unset = the model&#39;s full standard toolset. See <a href="#harness-tools">Harness tools</a>.</td></tr></tbody></table><h2 id="model" tabindex="-1">Model <a class="header-anchor" href="#model" aria-label="Permalink to &quot;Model&quot;"></a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. BDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="agent-fields" tabindex="-1">Agent fields <a class="header-anchor" href="#agent-fields" aria-label="Permalink to &quot;Agent fields&quot;"></a></h2><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>persistent</code></td><td>boolean</td><td>Keep one long-lived runtime for the hosted deployment. Defaults to <code>false</code>. See <a href="#persistent-hosting">Persistent hosting</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames?, image? }</code></td><td>Managed-hosting declarations read by <code>bdk deploy</code>: the deployment&#39;s egress allowlist, the secret names the agent expects, and a container image for a <a href="#persistent-hosting">persistent agent</a>. Mounted <a href="./extensions.html#build-an-extension">extensions</a> add their own. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Agent-wide concurrent turn limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr><tr><td><code>tools</code></td><td><code>ToolName[]</code></td><td>Allowlist of built-in harness tools offered to the model. Unset = the model&#39;s full standard toolset. See <a href="#harness-tools">Harness tools</a>.</td></tr><tr><td><code>fs</code></td><td><code>FileSystem</code> or <code>(ctx) =&gt; FileSystem</code></td><td>Custom file tree for the session. <code>root</code> is the deprecated name. See <a href="#custom-filesystem">Custom filesystem</a>.</td></tr><tr><td><code>skills</code></td><td><code>false</code> or <code>(ctx) =&gt; FileSystem</code></td><td>Replaces the skills tree mounted at <code>/agent/skills</code>, or turns that mount off.</td></tr></tbody></table><h2 id="model" tabindex="-1">Model <a class="header-anchor" href="#model" aria-label="Permalink to &quot;Model&quot;"></a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. BDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grok-4.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  params</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;effort&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;high&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
@@ -17,7 +17,7 @@ import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A plain string works when you don&#39;t need params:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to &quot;Local options&quot;"></a></h2><p><code>local</code> sets local-harness defaults.</p><p><code>local.workspaceDir</code> points every session at one shared harness cwd, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> still wins over both. Sessions share a working tree, so a file one turn writes is visible to the next.</p><p><code>local.sandbox</code> runs the harness inside Cursor&#39;s local sandbox. It&#39;s off by default: shell then auto-approves and inherits the serve process environment, including any credentials the host holds. Turn it on for agents whose turns read untrusted input (webhook payloads, PR diffs, inbound chat); it&#39;s a tool boundary, not a prompt-level one.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;"></a></h3><p><code>local.cwd</code> sets the parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> unless a per-send <code>workspaceDir</code> overrides it.</p><p>Session workspaces are real Cursor project directories. The harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent nested in another git repo (a monorepo package) defaults to a per-project cache directory under <code>~/.cache</code> when you omit <code>cwd</code>, so the enclosing checkout does not leak rules, skills, or MCP servers into the turn. A standalone git root keeps the in-project session workspace. Point <code>cwd</code> at a checkout only when the agent should inherit that tree.</p><h2 id="persistent-hosting" tabindex="-1">Persistent hosting <a class="header-anchor" href="#persistent-hosting" aria-label="Permalink to &quot;Persistent hosting&quot;"></a></h2><p>By default, a hosted deployment starts a runtime when an event arrives and stops it when the work ends. Set <code>persistent: true</code> to keep one long-lived runtime for the deployment instead, with its state directory on the runtime&#39;s own disk. On a redeploy, the new version starts beside the old one on the same state, and the old version stops after the new one takes over. Each team can have one persistent deployment. Local serving ignores the flag.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  persistent: </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;">  hosting: { image: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-bot-base&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>hosting.image</code> names a container image that your team pushed with <code>bdk images push</code>. The agent runs inside that image instead of the default Node 22 image. Only persistent agents can use it, and <code>deploy</code> rejects <code>hosting.image</code> on any other agent. A deploy pins the image it finds, so after you push a new image under the same name, deploy again to pick it up.</p><h2 id="harness-tools" tabindex="-1">Harness tools <a class="header-anchor" href="#harness-tools" aria-label="Permalink to &quot;Harness tools&quot;"></a></h2><p>Use <code>tools</code> to limit which built-in Cursor harness tools the model can call. Omit it to keep the standard toolset. When you set it, the model gets only the tools you list. An empty list disables all native built-in tools. New platform tools stay disabled until you add them.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>hosting.image</code> names a container image that your team pushed with <code>bdk images push</code>. The agent runs inside that image instead of the default Node 22 image. Only persistent agents can use it, and <code>deploy</code> rejects <code>hosting.image</code> on any other agent. A deploy pins the image it finds, so after you push a new image under the same name, deploy again to pick it up.</p><h2 id="custom-filesystem" tabindex="-1">Custom filesystem <a class="header-anchor" href="#custom-filesystem" aria-label="Permalink to &quot;Custom filesystem&quot;"></a></h2><p><code>fs</code> is mounted at <code>/</code>. BDK mounts <code>/tmp</code> and <code>/agent/skills</code> over it.</p><p><code>root</code> is the deprecated name of <code>fs</code>. Set one of them. A tree that already has <code>/agent/skills</code> fails session start unless <code>skills</code> is <code>false</code>.</p><h2 id="harness-tools" tabindex="-1">Harness tools <a class="header-anchor" href="#harness-tools" aria-label="Permalink to &quot;Harness tools&quot;"></a></h2><p>Use <code>tools</code> to limit which built-in Cursor harness tools the model can call. Omit it to keep the standard toolset. When you set it, the model gets only the tools you list. An empty list disables all native built-in tools. New platform tools stay disabled until you add them.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Read-only triage agent: search and read only.</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // No shell, no edits, no subagents.</span></span>
@@ -31,4 +31,8 @@ import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`listening on \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">handle</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.callTool(...), handle.dispatchSchedule(&quot;heartbeat&quot;),</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.project, await handle.close()</span></span></code></pre></div><p>Host settings match the documented <a href="./cli.html">CLI</a> <code>serve</code> flags. <code>serve()</code> also accepts <code>discovery</code> (project-loading options) and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. Pass <code>apiKey</code> or use the same Cursor credential as the CLI: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or <code>bdk login</code>.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;"></a></h2><ul><li><a href="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./cli.html">CLI</a>: the <code>serve</code> flags <code>serve()</code> accepts</li><li><a href="./sessions.html">Sessions</a>: workspaces, identifiers, and turn admission</li><li><a href="./schedules.html">Schedules</a>: reminder tools opted in here</li></ul>`,41)])])}const u=e(n,[["render",o]]);export{k as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.agents, await handle.close()</span></span></code></pre></div><p><code>handle.agents</code> lists each mount as <code>slug</code>, <code>url</code>, and <code>info</code>. <code>handle.project</code> is the first agent&#39;s project. It is deprecated.</p><p>Host settings match the documented <a href="./cli.html">CLI</a> <code>serve</code> flags. <code>serve()</code> also accepts <code>discovery</code> (project-loading options) and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. Pass <code>apiKey</code> or use the same Cursor credential as the CLI: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or <code>bdk login</code>.</p><h2 id="inspect-a-project-in-tests" tabindex="-1">Inspect a project in tests <a class="header-anchor" href="#inspect-a-project-in-tests" aria-label="Permalink to &quot;Inspect a project in tests&quot;"></a></h2><p><code>loadProject(dir)</code> reads one project and does not serve it. The result is a <code>Project</code>. The only field is <code>info</code>. That object matches the <code>GET /v1/info</code> body for the project. <code>bdk info --json</code> on a project directory prints <code>{ agents: [{ slug, ...info }] }</code>. It prints the bare object only when the single mount slug is empty.</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;"> { loadProject } </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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> project</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;"> loadProject</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(project.info.name);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(project.info.tools.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">((</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">tool</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;"> tool.name));</span></span></code></pre></div><p><code>loadProject</code> throws <code>ProjectLoadError</code> when discovery reports an error. Pass <code>{ strict: true }</code> to throw on a warning as well. <code>error.diagnostics</code> lists the findings. Each <code>path</code> is relative to the project directory. A path outside that directory starts with <code>../</code>. <code>loadProject</code> does not take <code>importModule</code>. <code>serve</code> still accepts <code>discovery.importModule</code> for that override.</p><p><code>info.local</code> is <code>{ cwd }</code> when the project sets a cwd. The serve banner reads <code>agents[].info</code>.</p><p><code>serve</code> accepts that <code>Project</code> or a directory path.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;"></a></h2><ul><li><a href="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./cli.html">CLI</a>: the <code>serve</code> flags <code>serve()</code> accepts</li><li><a href="./sessions.html">Sessions</a>: workspaces, identifiers, and turn admission</li><li><a href="./schedules.html">Schedules</a>: reminder tools opted in here</li></ul>`,51)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/docs/assets/{reference_agent-config.md.IplwL25I.lean.js → reference_agent-config.md.CZrbHOfT.lean.js} RENAMED Viewed

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

package/dist/docs/assets/{reference_channels.md.Bxaa020x.js → reference_channels.md.CNNIS6K7.js} RENAMED Viewed

@@ -19,4 +19,4 @@ import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const k
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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-responses" tabindex="-1">Route responses <a class="header-anchor" href="#route-responses" aria-label="Permalink to &quot;Route responses&quot;"></a></h2><p>A custom route acknowledges the caller and nothing more. On Cursor-managed hosting, the deployment answers every custom route with <code>202 Accepted</code> and an empty body as soon as the request arrives, then runs the handler. The caller never receives the handler&#39;s <code>Response</code>, so a route can&#39;t return a session ID, a computed result, or an error status. Requests rejected before the handler runs, such as a missing alias token or a failed <code>sharedSecretAuth</code> or <code>hmacSignatureAuth</code> check, still get <code>401</code>.</p><p>Deliver results through the channel&#39;s <a href="#events"><code>events</code></a> handlers, a callback to the system that sent the request, or a tool the turn calls. Local <code>serve</code> passes the handler&#39;s response through, so return <code>new Response(null, { status: 202 })</code> to keep local calls matching hosted ones.</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, and an empty body is read as <code>{}</code>. A request that fails validation never reaches the handler; local <code>serve</code> answers it with <code>400</code>, while a hosted caller has already received its <code>202</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>Keep work running after the handler 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></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?, separator? })</code></td><td>A hex HMAC-SHA256 signature over the raw body using the named secret. With <code>separator</code>, any of several signatures in the header. A secret holding one value per line verifies under any of them (at most 32, <code>@cursor/bdk</code> 0.2.25 or later)</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, and streaming replies. 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/pagerduty</code></td><td><code>pagerdutyChannel()</code></td><td>PagerDuty v3 incident webhooks. Replies post as incident notes only with <code>deliverReplies: true</code>. See <a href="./../guides/pagerduty.html">PagerDuty</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>`,41)])])}const u=t(i,[["render",o]]);export{k as __pageData,u as default};
+<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-responses" tabindex="-1">Route responses <a class="header-anchor" href="#route-responses" aria-label="Permalink to &quot;Route responses&quot;"></a></h2><p>A custom route acknowledges the caller and nothing more. On Cursor-managed hosting, the deployment answers every custom route with <code>202 Accepted</code> and an empty body as soon as the request arrives, then runs the handler. The caller never receives the handler&#39;s <code>Response</code>, so a route can&#39;t return a session ID, a computed result, or an error status. Requests rejected before the handler runs, such as a missing alias token or a failed <code>sharedSecretAuth</code> or <code>hmacSignatureAuth</code> check, still get <code>401</code>.</p><p>Deliver results through the channel&#39;s <a href="#events"><code>events</code></a> handlers, a callback to the system that sent the request, or a tool the turn calls. Local <code>serve</code> passes the handler&#39;s response through, so return <code>new Response(null, { status: 202 })</code> to keep local calls matching hosted ones.</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, and an empty body is read as <code>{}</code>. A request that fails validation never reaches the handler; local <code>serve</code> answers it with <code>400</code>, while a hosted caller has already received its <code>202</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>Keep work running after the handler 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><tr><td><code>deliveryId</code></td><td>Name this send on the session&#39;s events, at most 256 characters. Defaults to a fresh <code>dlv_…</code> ID</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>. <code>deliveryId</code> names this send on the event where the message reaches the agent; see <a href="./sessions.html#track-which-follow-up-reached-the-agent">Track which follow-up reached the agent</a>. A hosted channel&#39;s <code>send</code> returns the same ID before the session exists.</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></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?, separator? })</code></td><td>A hex HMAC-SHA256 signature over the raw body using the named secret. With <code>separator</code>, any of several signatures in the header. A secret holding one value per line verifies under any of them (at most 32, <code>@cursor/bdk</code> 0.2.25 or later)</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, and streaming replies. 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/pagerduty</code></td><td><code>pagerdutyChannel()</code></td><td>PagerDuty v3 incident webhooks. Replies post as incident notes only with <code>deliverReplies: true</code>. See <a href="./../guides/pagerduty.html">PagerDuty</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>`,41)])])}const u=t(i,[["render",o]]);export{k as __pageData,u as default};