@cursor/bdk 0.2.24 → 0.2.26

package/dist/internal/otel/config.js

@@ -1,75 +1,53 @@
 /**
- * Merge authored `defineOtel`, `serve({ otel })`, and standard OTel env.
+ * Standard `OTEL_*` variables for export. There is no instrumentation file.
  */
-import { resolveOtelDefinition, } from "../../otel.js";
 /**
- * Process-global authored config. OTel SDK is one per serve process — if
- * several mounts ship `agent/otel.ts`, they must be identical.
+ * `service.name` when no agent name, `OTEL_SERVICE_NAME`, or
+ * `service.name` resource attribute is set. Matches the SDK fallback.
  */
-export function pickAuthoredOtel(mounts) {
-    const found = mounts.filter((m) => m.otel !== undefined);
-    if (found.length === 0) {
-        return undefined;
-    }
-    const first = found[0];
-    const key = stableConfigKey(first.otel);
-    for (const other of found.slice(1)) {
-        if (stableConfigKey(other.otel) !== key) {
-            const a = first.slug === "" ? first.name : first.slug;
-            const b = other.slug === "" ? other.name : other.slug;
-            throw new Error(`Conflicting agent/otel.ts on mounts "${a}" and "${b}": OTel is process-global. Use identical defineOtel configs, or configure once via serve({ otel }) / OTEL_EXPORTER_OTLP_*.`);
-        }
-    }
-    return first.otel;
-}
-/**
- * Resolve effective config.
- *
- * Precedence: `serve({ otel: false })` disables; otherwise merge
- * `serve({ otel })` over `defineOtel` over env defaults.
- */
-export function resolveOtelConfig(input) {
+export const UNKNOWN_SERVICE_NAME = "unknown_service:node";
+/** Resolve export from `OTEL_EXPORTER_OTLP_*`. No endpoint means disabled. */
+export function resolveOtelConfig(input = {}) {
     const env = input.env ?? process.env;
-    if (input.serve === false) {
-        return disabledOtelConfig();
-    }
-    const authored = input.authored === undefined ? {} : resolveOtelDefinition(input.authored);
-    const serve = input.serve === undefined ? {} : input.serve;
-    const merged = {
-        serviceName: serve.serviceName ?? authored.serviceName,
-        serviceVersion: serve.serviceVersion ?? authored.serviceVersion,
-        resourceAttributes: {
-            ...authored.resourceAttributes,
-            ...serve.resourceAttributes,
-        },
-        exporters: serve.exporters ?? authored.exporters,
-        traces: serve.traces ?? authored.traces,
-        metrics: serve.metrics ?? authored.metrics,
-        logs: serve.logs ?? authored.logs,
-    };
-    const envExporters = exportersFromEnv(env);
-    const exporters = merged.exporters !== undefined && merged.exporters.length > 0
-        ? merged.exporters.map((e) => withEnvHeaders(e, env))
-        : envExporters;
-    const optedIn = input.authored !== undefined || input.serve !== undefined || envExporters.length > 0;
-    if (!optedIn) {
-        return disabledOtelConfig();
-    }
-    const traces = resolveSignal(merged.traces);
-    const metrics = exporters.length === 0 ? false : resolveSignal(merged.metrics);
-    const logs = exporters.length === 0 ? false : resolveLogs(merged.logs, env);
-    if (exporters.length === 0 && traces === false) {
-        return disabledOtelConfig();
+    if (sdkDisabled(env)) {
+        return disabledOtelConfig(input.defaultServiceName);
+    }
+    const built = exportersFromEnv(env);
+    if (built.exporters.length === 0) {
+        return { ...disabledOtelConfig(input.defaultServiceName), warnings: built.warnings };
+    }
+    const serviceName = env.OTEL_SERVICE_NAME?.trim();
+    const parsed = metricsTemporalityFromEnv(env.OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE);
+    const tracesOff = signalExporterOff(env, "TRACES") || exportersForSignal(built.exporters, "traces").length === 0;
+    const metricsOff = signalExporterOff(env, "METRICS") ||
+        exportersForSignal(built.exporters, "metrics").length === 0;
+    const logsOn = resolveLogs(env, built.warnings);
+    const logs = logsOn !== false && exportersForSignal(built.exporters, "logs").length > 0 ? logsOn : false;
+    const traces = tracesOff ? false : {};
+    const metrics = metricsOff
+        ? false
+        : {
+            temporality: parsed.temporality,
+            unrecognizedTemporality: parsed.unrecognized,
+            exportIntervalMillis: metricExportInterval(env),
+        };
+    if (traces === false && metrics === false && logs === false) {
+        return { ...disabledOtelConfig(input.defaultServiceName), warnings: built.warnings };
     }
     return {
-        enabled: traces !== false || metrics !== false || logs !== false,
-        serviceName: merged.serviceName ?? env.OTEL_SERVICE_NAME ?? "cursor",
-        serviceVersion: merged.serviceVersion,
-        resourceAttributes: merged.resourceAttributes ?? {},
-        exporters,
+        enabled: true,
+        serviceName: nonEmpty(serviceName)
+            ? serviceName
+            : nonEmpty(input.defaultServiceName)
+                ? input.defaultServiceName
+                : UNKNOWN_SERVICE_NAME,
+        serviceVersion: undefined,
+        resourceAttributes: {},
+        exporters: built.exporters,
         traces,
         metrics,
         logs,
+        warnings: built.warnings,
     };
 }
 /** Values are URL-encoded per the OTel spec (`Authorization=Basic%20...`). */
@@ -108,16 +86,17 @@ export function stripSignalPath(url) {
 export function exportersForSignal(exporters, signal) {
     return exporters.filter((exporter) => exporter.signals === undefined || exporter.signals.includes(signal));
 }
-export function disabledOtelConfig() {
+export function disabledOtelConfig(defaultServiceName) {
     return {
         enabled: false,
-        serviceName: "cursor",
+        serviceName: nonEmpty(defaultServiceName) ? defaultServiceName : UNKNOWN_SERVICE_NAME,
         serviceVersion: undefined,
         resourceAttributes: {},
         exporters: [],
         traces: false,
         metrics: false,
         logs: false,
+        warnings: [],
     };
 }
 /**
@@ -127,89 +106,117 @@ export function disabledOtelConfig() {
  * signal (OTel env spec).
  */
 function exportersFromEnv(env) {
+    const warnings = [];
     const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
-    const traces = env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim();
-    const metrics = env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT?.trim();
-    const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT?.trim();
-    const protocol = protocolFromEnv(env.OTEL_EXPORTER_OTLP_PROTOCOL);
     const headers = parseOtelHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
-    if (nonEmpty(base)) {
-        return [{ url: stripSignalPath(base), headers, protocol }];
+    const shared = protocolFromEnv(env.OTEL_EXPORTER_OTLP_PROTOCOL, "OTEL_EXPORTER_OTLP_PROTOCOL");
+    if (shared.warning !== undefined) {
+        warnings.push(shared.warning);
+    }
+    const traces = signalExporter(env, "traces", "TRACES", base, headers, shared.protocol, warnings);
+    const metrics = signalExporter(env, "metrics", "METRICS", base, headers, shared.protocol, warnings);
+    const logs = signalExporter(env, "logs", "LOGS", base, headers, shared.protocol, warnings);
+    const list = [traces, metrics, logs].filter((exporter) => exporter !== undefined);
+    if (list.length === 3 &&
+        list.every((exporter) => exporter.literalUrl !== true &&
+            exporter.url === list[0]?.url &&
+            exporter.protocol === list[0]?.protocol)) {
+        return {
+            exporters: [{ url: list[0].url, headers, protocol: list[0].protocol }],
+            warnings,
+        };
+    }
+    return { exporters: list, warnings };
+}
+function signalExporter(env, signal, envName, base, headers, sharedProtocol, warnings) {
+    if (signalExporterOff(env, envName)) {
+        return undefined;
     }
-    const out = [];
-    pushSignalExporter(out, traces, "traces", headers, protocol);
-    pushSignalExporter(out, metrics, "metrics", headers, protocol);
-    pushSignalExporter(out, logs, "logs", headers, protocol);
-    return out;
-}
-function pushSignalExporter(out, raw, signal, headers, protocol) {
-    if (!nonEmpty(raw)) {
-        return;
+    const specific = env[`OTEL_EXPORTER_OTLP_${envName}_ENDPOINT`]?.trim();
+    const protocolEnv = env[`OTEL_EXPORTER_OTLP_${envName}_PROTOCOL`];
+    const chosen = protocolEnv !== undefined && protocolEnv.trim().length > 0
+        ? protocolFromEnv(protocolEnv, `OTEL_EXPORTER_OTLP_${envName}_PROTOCOL`)
+        : { protocol: sharedProtocol, warning: undefined };
+    if (chosen.warning !== undefined && !warnings.includes(chosen.warning)) {
+        warnings.push(chosen.warning);
+    }
+    if (nonEmpty(specific)) {
+        return {
+            url: specific,
+            headers,
+            protocol: chosen.protocol,
+            signals: [signal],
+            literalUrl: true,
+        };
+    }
+    if (!nonEmpty(base)) {
+        return undefined;
     }
-    out.push({
-        url: stripSignalPath(raw),
+    return {
+        url: stripSignalPath(base),
         headers,
-        protocol,
+        protocol: chosen.protocol,
         signals: [signal],
-    });
-}
-function withEnvHeaders(exporter, env) {
-    const envHeaders = parseOtelHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
-    return {
-        url: stripSignalPath(exporter.url),
-        headers: { ...envHeaders, ...exporter.headers },
-        protocol: exporter.protocol ?? protocolFromEnv(env.OTEL_EXPORTER_OTLP_PROTOCOL),
-        signals: exporter.signals,
     };
 }
-function protocolFromEnv(raw) {
+function protocolFromEnv(raw, name) {
     const v = raw?.trim().toLowerCase();
     if (v === "http/json" || v === "json") {
-        return "http/json";
+        return { protocol: "http/json", warning: undefined };
     }
-    // Default protobuf — matches Cursor enterprise OTLP/HTTP. grpc unsupported.
-    return "http/protobuf";
+    if (v === "grpc") {
+        return {
+            protocol: "http/protobuf",
+            warning: `${name}=grpc is unsupported; using http/protobuf`,
+        };
+    }
+    return { protocol: "http/protobuf", warning: undefined };
 }
-function resolveSignal(value) {
-    if (value === false) {
-        return false;
+function sdkDisabled(env) {
+    const raw = env.OTEL_SDK_DISABLED?.trim().toLowerCase();
+    return raw === "true" || raw === "1";
+}
+function signalExporterOff(env, signal) {
+    return env[`OTEL_${signal}_EXPORTER`]?.trim().toLowerCase() === "none";
+}
+function metricExportInterval(env) {
+    const raw = env.OTEL_METRIC_EXPORT_INTERVAL?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
     }
-    if (value === true || value === undefined) {
-        return {};
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) {
+        return undefined;
     }
     return value;
 }
-function resolveLogs(value, env) {
-    if (value === false) {
-        return false;
+function metricsTemporalityFromEnv(raw) {
+    const value = raw?.trim().toLowerCase();
+    if (value === undefined || value.length === 0) {
+        return { temporality: "delta", unrecognized: undefined };
     }
-    const envPrompts = env.OTEL_LOG_USER_PROMPTS === "1";
-    const envTools = env.OTEL_LOG_TOOL_CONTENT === "1";
-    if (value === true) {
-        return { userPrompts: envPrompts, toolContent: envTools };
+    switch (value) {
+        case "cumulative":
+        case "delta":
+        case "lowmemory":
+            return { temporality: value, unrecognized: undefined };
+        default:
+            return { temporality: "delta", unrecognized: raw };
     }
-    if (value === undefined) {
-        // Match OTel: unset / empty / `none` means logs off. Any other
-        // `OTEL_LOGS_EXPORTER` value (e.g. `otlp`) opts logs on.
-        if (!envPrompts && !envTools && !logsExporterOptIn(env)) {
-            return false;
-        }
-        return { userPrompts: envPrompts, toolContent: envTools };
+}
+function resolveLogs(env, warnings) {
+    const raw = env.OTEL_LOGS_EXPORTER?.trim().toLowerCase();
+    if (raw === "console") {
+        warnings.push("OTEL_LOGS_EXPORTER=console does not enable OTLP logs. Set otlp to export logs.");
+    }
+    if (raw !== "otlp") {
+        return false;
     }
     return {
-        userPrompts: value.userPrompts ?? envPrompts,
-        toolContent: value.toolContent ?? envTools,
+        userPrompts: env.OTEL_LOG_USER_PROMPTS === "1",
+        toolContent: env.OTEL_LOG_TOOL_CONTENT === "1",
     };
 }
-/** `OTEL_LOGS_EXPORTER=none` (or unset) must not enable log export. */
-function logsExporterOptIn(env) {
-    const raw = env.OTEL_LOGS_EXPORTER?.trim().toLowerCase();
-    return raw !== undefined && raw.length > 0 && raw !== "none";
-}
-function stableConfigKey(def) {
-    const { __agentServe: _brand, ...rest } = def;
-    return stableJson(rest);
-}
 /** Canonical JSON with sorted keys, so object key order does not change the result. */
 export function stableJson(value) {
     if (value === null || typeof value !== "object") {

package/dist/internal/otel/conversation-span-processor.d.ts

@@ -0,0 +1,9 @@
+import { type Context } from "@opentelemetry/api";
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+/** Bind the BDK session id onto a context. The value does not propagate. */
+export declare function withConversationId(parent: Context, sessionId: string): Context;
+/** Session id for the active turn, when this process set one. */
+export declare function currentConversationId(): string | undefined;
+/** Copy the session id onto a span that does not already set it. */
+export declare function conversationIdSpanProcessor(): SpanProcessor;
+//# sourceMappingURL=conversation-span-processor.d.ts.map

package/dist/internal/otel/conversation-span-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-span-processor.d.ts","sourceRoot":"","sources":["../../../src/internal/otel/conversation-span-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAQ,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKzE,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,SAAS,CAG1D;AAED,oEAAoE;AACpE,wBAAgB,2BAA2B,IAAI,aAAa,CAoB3D"}

package/dist/internal/otel/conversation-span-processor.js

@@ -0,0 +1,34 @@
+import { context, createContextKey } from "@opentelemetry/api";
+const CONVERSATION_ID_ATTRIBUTE = "cursor.conversation.id";
+const conversationIdKey = createContextKey(CONVERSATION_ID_ATTRIBUTE);
+/** Bind the BDK session id onto a context. The value does not propagate. */
+export function withConversationId(parent, sessionId) {
+    return parent.setValue(conversationIdKey, sessionId);
+}
+/** Session id for the active turn, when this process set one. */
+export function currentConversationId() {
+    const value = context.active().getValue(conversationIdKey);
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** Copy the session id onto a span that does not already set it. */
+export function conversationIdSpanProcessor() {
+    return {
+        onStart(span, parentContext) {
+            if (span.attributes[CONVERSATION_ID_ATTRIBUTE] !== undefined) {
+                return;
+            }
+            const value = parentContext.getValue(conversationIdKey);
+            if (typeof value !== "string" || value === "") {
+                return;
+            }
+            span.setAttribute(CONVERSATION_ID_ATTRIBUTE, value);
+        },
+        onEnd() { },
+        shutdown() {
+            return Promise.resolve();
+        },
+        forceFlush() {
+            return Promise.resolve();
+        },
+    };
+}

package/dist/internal/otel/customer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bake-time OpenTelemetry providers. Discovery installs them before other
+ * agent modules load. Real OTLP exporters attach from `OTEL_*` variables
+ * at the first secret load.
+ */
+import { type OtelRuntimeHandle } from "./runtime.js";
+/**
+ * Register a mapper that runs when secrets load, before exporters are built.
+ * Factory agents use this to copy their own secret names into `OTEL_*`.
+ * Not exported from `@cursor/bdk/otel`.
+ */
+export declare function contributeOtelEnv(contribute: (env: NodeJS.ProcessEnv) => void): void;
+export declare function writeDatadogTraceEnv(env: NodeJS.ProcessEnv, input: {
+    apiKey: string;
+    serviceName: string;
+    tracesUrl: string;
+    environment: string;
+}): void;
+/** Resolves at the first secret load. Local serve resolves it at start. */
+export declare function otelSecretsReady(): Promise<void>;
+/**
+ * Install global trace, metric, and log providers before `agent.ts` loads.
+ * A second call does nothing. BDK shuts down a provider only when its
+ * registration installed that provider. If another SDK already owns a
+ * global, that provider stays and the new one is shut down.
+ */
+export declare function installCustomerOtel(): void;
+export interface NotifyOtelSecretsInput {
+    log: (line: string) => void;
+    egressDomains?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    defaultServiceName?: string;
+}
+/**
+ * Settle resource promises and attach OTLP exporters from the current env.
+ * Later calls keep the same URLs. Exporter headers are read on each export.
+ */
+export declare function notifyOtelSecretsReady(input: NotifyOtelSecretsInput): void;
+/**
+ * The runtime `serve` uses after discovery installs the providers.
+ * HTTP spans, the collector, and flush stay on one path.
+ */
+export declare function createCustomerOtelRuntime(log: (line: string) => void, options?: {
+    egressDomains?: readonly string[];
+    defaultServiceName?: string;
+}): OtelRuntimeHandle;
+export declare function forceFlushGlobalOtel(): Promise<void>;
+/** True when agent code replaced a provider this process installed. */
+export declare function otelProvidersReplaced(): boolean;
+/** Test isolation. Settles pending resource promises so a flush cannot wait forever. */
+export declare function resetCustomerOtelForTests(): Promise<void>;
+//# sourceMappingURL=customer.d.ts.map

package/dist/internal/otel/customer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer.d.ts","sourceRoot":"","sources":["../../../src/internal/otel/customer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmDH,OAAO,EAIL,KAAK,iBAAiB,EAIvB,MAAM,cAAc,CAAC;AAoEtB;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,IAAI,GAAG,IAAI,CAEpF;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,KAAK,EAAE;IACL,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,GACA,IAAI,CA0BN;AA2DD,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CA6E1C;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI,CA6C1E;AAyED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC3B,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/E,iBAAiB,CAyCnB;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAM1D;AA2CD,uEAAuE;AACvE,wBAAgB,qBAAqB,IAAI,OAAO,CAU/C;AAWD,wFAAwF;AACxF,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB/D"}