@cursor/bdk 0.2.25 → 0.2.26

package/dist/docs/assets/chunks/channel.Dt4aweTm.js

@@ -1 +0,0 @@
-import{U as a,D as n}from"../app.BjS1QEI4.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DGUHZs6j.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK.CzYKuv3I.js";import{_ as i}from"../app.BjS1QEI4.js";import"./chunk-FMBD7UC4.DhMTl7ut.js";import"./chunk-YZCP3GAM.CdOOBFYL.js";import"./chunk-55IACEB6.C7_tcJZD.js";import"./chunk-EDXVE4YY.DeTwQPVO.js";import"./framework.BNw1pucY.js";import"./theme.D5jbBys7.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};

package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DGUHZs6j.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK.CzYKuv3I.js";import{_ as i}from"../app.BjS1QEI4.js";import"./chunk-FMBD7UC4.DhMTl7ut.js";import"./chunk-YZCP3GAM.CdOOBFYL.js";import"./chunk-55IACEB6.C7_tcJZD.js";import"./chunk-EDXVE4YY.DeTwQPVO.js";import"./framework.BNw1pucY.js";import"./theme.D5jbBys7.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};

package/dist/docs/assets/chunks/clone.DWf3k0Z0.js

@@ -1 +0,0 @@
-import{b as r}from"./graph.C5IB6_e_.js";var e=4;function a(o){return r(o,e)}export{a as c};

package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.C0571l4D.js

@@ -1 +0,0 @@
-import{s as r,b as e,a,S as s}from"./chunk-OYMX7WX6.Me7f5hEp.js";import{_ as i}from"../app.BjS1QEI4.js";import"./chunk-55IACEB6.C7_tcJZD.js";import"./chunk-EDXVE4YY.DeTwQPVO.js";import"./framework.BNw1pucY.js";import"./theme.D5jbBys7.js";var u={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/docs/assets/guides_opentelemetry.md.DBQtp7_V.js

@@ -1,45 +0,0 @@
-import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function o(l,s,h,p,r,d){return t(),a("div",null,[...s[0]||(s[0]=[i(`<h1 id="observe-an-agent-with-opentelemetry" tabindex="-1">Observe an agent with OpenTelemetry <a class="header-anchor" href="#observe-an-agent-with-opentelemetry" aria-label="Permalink to &quot;Observe an agent with OpenTelemetry&quot;">​</a></h1><p>OpenTelemetry connects an agent turn to the observability system your team already uses. Once you configure an OTLP collector, each request, model turn, tool call, and subagent appears alongside token, tool, and cost metrics from the serve process.</p><p>Export is opt-in. Nothing leaves the process until you configure a destination.</p><h2 id="connect-an-otlp-collector" tabindex="-1">Connect an OTLP collector <a class="header-anchor" href="#connect-an-otlp-collector" aria-label="Permalink to &quot;Connect an OTLP collector&quot;">​</a></h2><p>Set the collector endpoint, start the agent, and send it a message. You should see an <code>agent_sdk.http</code> request span and an <code>agent_sdk.turn</code> trace, with any tool or subagent work nested under the turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#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>Metrics use delta temporality by default. For Grafana Cloud, set <code>OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE</code> to <code>cumulative</code>. Grafana Cloud rejects delta metrics.</p><p>The default protocol is OTLP/HTTP protobuf. If you already call <code>serve()</code> from TypeScript, you can configure the same destination in code:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { serve } </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;">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: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Use environment variables when you start the agent with <code>bdk serve</code>. Use <code>serve({ otel })</code> when your TypeScript application starts the server itself. When that application already uses OpenTelemetry, BDK sends its traces, metrics, and logs to the collector configured here.</p><h2 id="export-from-a-hosted-agent" tabindex="-1">Export from a hosted agent <a class="header-anchor" href="#export-from-a-hosted-agent" aria-label="Permalink to &quot;Export from a hosted agent&quot;">​</a></h2><p>Set the collector endpoint and headers as secrets, and add the collector host to <code>hosting.egressDomains</code>. The host is a hostname with no scheme and no path. The first request loads the secrets, and export starts with those headers.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/agent.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  hosting: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;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 style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;OTEL_EXPORTER_OTLP_ENDPOINT&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><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:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-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_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_EXPORTER_OTLP_HEADERS</span></span></code></pre></div><p><code>OTEL_EXPORTER_OTLP_HEADERS</code> is a comma-separated list of <code>name=value</code> pairs. Each value is URL-encoded, so a space is <code>%20</code> (<code>Authorization=Basic%20...</code>).</p><p>A later <code>bdk secrets set</code> changes the headers on the next export. You do not redeploy to rotate a token. The URL, service name, resource attributes, signals, sample ratio, metric export interval, and metrics temporality stay as they were on the first export. Redeploy to change one of those. BDK logs a warning when one of them changes on a running agent.</p><p>When an exporter host is missing from <code>hosting.egressDomains</code>, BDK logs an error that names the host. Add the host and redeploy.</p><p>Spans and metrics from before the first request are not exported, including spans from channel <code>onStart</code>. If the OpenTelemetry config fails, BDK logs the error and the request still completes.</p><p>Logs stay off until <code>serve({ otel })</code> sets <code>logs</code>, or until <code>OTEL_LOGS_EXPORTER</code> is <code>otlp</code>. Prompt text and tool payloads stay off until you set <code>OTEL_LOG_USER_PROMPTS</code> or <code>OTEL_LOG_TOOL_CONTENT</code>.</p><h2 id="follow-one-conversation" tabindex="-1">Follow one conversation <a class="header-anchor" href="#follow-one-conversation" aria-label="Permalink to &quot;Follow one conversation&quot;">​</a></h2><p>Copy the complete session ID from the playground or session API, then filter your observability system on either <code>agent_sdk.session_id</code> or <code>cursor.conversation.id</code>. Every turn in that conversation carries the same value, including follow-ups and tool work.</p><p>The trace shape stays small:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>request: agent_sdk.http</span></span>
-<span class="line"><span></span></span>
-<span class="line"><span>turn: agent_sdk.turn</span></span>
-<span class="line"><span>      |- agent_sdk.tool</span></span>
-<span class="line"><span>      \`- agent_sdk.subagent</span></span>
-<span class="line"><span>         \`- agent_sdk.tool</span></span></code></pre></div><p>A conversation can produce several turn traces, so use the session ID as the join key instead of expecting one long-lived session span.</p><h3 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h3><p>A subagent&#39;s tool calls are <code>agent_sdk.tool</code> spans under its <code>agent_sdk.subagent</code> span. Its <code>reasoning.completed</code> and <code>message.completed</code> events sit on that span too, so the subagent span shows where its time went. Time between two tool spans is the model choosing the next step. A subagent that fails or is cancelled ends its span with ERROR status when it stops.</p><h3 id="computer-use" tabindex="-1">Computer use <a class="header-anchor" href="#computer-use" aria-label="Permalink to &quot;Computer use&quot;">​</a></h3><p>Each computer use action is an <code>agent_sdk.tool</code> span with <code>cursor.tool.name</code> set to <code>computerUse</code>, under the computer use subagent&#39;s span. A failed action has ERROR status. These attributes describe the action without typed text, coordinates, or screenshots:</p><table tabindex="0"><thead><tr><th>Attribute</th><th>Value</th></tr></thead><tbody><tr><td><code>agent_sdk.computer.actions</code></td><td>The action type, such as <code>click</code>, <code>type</code>, or <code>screenshot</code></td></tr><tr><td><code>agent_sdk.computer.executor_duration_ms</code></td><td>Time the desktop took to run the action and capture the screen</td></tr><tr><td><code>agent_sdk.computer.settle_ms</code></td><td>Part of that time spent waiting for the screen to settle</td></tr></tbody></table><p>The two durations appear only on actions that succeed.</p><p>To export the full actions, turn on tool content as shown in <a href="#control-what-leaves-the-process">Control what leaves the process</a>. Tool content includes the text the agent typed, which can contain passwords.</p><h2 id="add-domain-telemetry" tabindex="-1">Add domain telemetry <a class="header-anchor" href="#add-domain-telemetry" aria-label="Permalink to &quot;Add domain telemetry&quot;">​</a></h2><p>Use <code>ctx.host.otel</code> when your dashboard should answer questions the built-in telemetry cannot, such as which incident a turn handled or how long approval took. Attributes appear on the active turn and tool spans, while counters and histograms give you metrics to graph and alert on.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;support.ticket_id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INC-123&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;support.queue&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;p1&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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;support.ticket.resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  outcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fixed&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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">record</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;support.approval.duration_ms&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1420</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  outcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approved&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>This API is available in tools, hooks, and channel handlers. A session-bound context adds <code>cursor.conversation.id</code> and <code>agent_sdk.agent</code> automatically, so custom measurements join the first-party telemetry without extra plumbing.</p><p>Prefix custom names with your team or agent. First-party metric names and join keys are reserved, and this surface does not create custom spans.</p><h2 id="choose-signals" tabindex="-1">Choose signals <a class="header-anchor" href="#choose-signals" aria-label="Permalink to &quot;Choose signals&quot;">​</a></h2><p>Once export has a destination, traces and metrics are on by default; logs remain off until you opt in.</p><table tabindex="0"><thead><tr><th>Signal</th><th>What appears</th></tr></thead><tbody><tr><td>Traces</td><td>HTTP requests, turns, tools, and subagents</td></tr><tr><td>Metrics</td><td>Token usage, tool calls, cost, and BDK session or turn counts</td></tr><tr><td>Logs</td><td>Session events, after you enable log export</td></tr></tbody></table><p>The first metrics to look for are <code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, and <code>cursor.cost.usage</code>. Configure <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: true</code> under <code>serve({ otel })</code> when you need a different signal mix.</p><h2 id="control-what-leaves-the-process" tabindex="-1">Control what leaves the process <a class="header-anchor" href="#control-what-leaves-the-process" aria-label="Permalink to &quot;Control what leaves the process&quot;">​</a></h2><p>Traces include structure, tool names, usage metrics, and span status. A failed tool&#39;s span status and its <code>action.result</code> log include a short failure reason. A tool or subagent that is still open when the turn ends gets ERROR status with the reason <code>no result</code>. User prompts, tool arguments, and full tool results stay off the wire until you opt in.</p><p>Turn on logs first, then opt into prompt or tool content separately:</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_LOGS_EXPORTER</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">otlp</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOG_USER_PROMPTS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_LOG_TOOL_CONTENT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span></code></pre></div><p><code>OTEL_LOG_USER_PROMPTS</code> exports user text. <code>OTEL_LOG_TOOL_CONTENT</code> exports tool inputs, outputs, and failure details. Enable either only when the collector&#39;s access and retention policies are appropriate for that data.</p><p>The same controls are available as <code>logs: { userPrompts, toolContent }</code> under <code>serve({ otel })</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="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>: compact configuration and custom-metric reference for coding agents</li><li><a href="./../reference/hooks.html">Hooks</a>: emit domain telemetry from session events</li><li><a href="./../deployment.html">Deployment</a>: declare <code>hosting.egressDomains</code> and set collector secrets on a hosted agent</li><li><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>: send organization-wide Cursor telemetry to the same collector</li></ul>`,48)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};

package/dist/docs/assets/guides_opentelemetry.md.DBQtp7_V.lean.js

@@ -1 +0,0 @@
-import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.","frontmatter":{"title":"OpenTelemetry","description":"Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function o(l,s,h,p,r,d){return t(),a("div",null,[...s[0]||(s[0]=[i("",48)])])}const E=e(n,[["render",o]]);export{k as __pageData,E as default};

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

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

package/dist/docs/assets/reference_sessions.md.C8FXuGwk.lean.js

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