@heystack/otel 0.12.0 → 0.14.0

package/dist/workers.js

@@ -7,15 +7,15 @@
 // `@opentelemetry/resources` and the platform `fetch` — all WinterCG-safe — and
 // ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
 // where the Node SDK cannot.
-import { context, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { context, createContextKey, INVALID_SPAN_CONTEXT, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
 import { suppressTracing, isTracingSuppressed } from "@opentelemetry/core";
 import { ROOT_CONTEXT } from "@opentelemetry/api";
-import { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BasicTracerProvider, SimpleSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { buildExporterConfig, DEFAULT_ENDPOINT, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
-import { detectLLMProvider, llmRequestAttrs, llmResponseAttrs, llmContentAttrs } from "./llm-enrich.js";
+import { llmRequestAttrs, llmResponseAttrs, llmContentAttrs, llmOperationName, resolveLLMProvider, scanSseStreamForUsage, } from "./llm-enrich.js";
 import { instrumentEnv } from "./workers-bindings.js";
 import { makeSampler, loadRemoteSamplingRate } from "./workers-sampler.js";
 // `ExportResult` / `ExportResultCode` mirror `@opentelemetry/core`. We define
@@ -113,7 +113,9 @@ function readableSpanToOtlp(span) {
     return {
         traceId: ctx.traceId,
         spanId: ctx.spanId,
-        parentSpanId: span.parentSpanId ?? "",
+        // OTel SDK 2.x: `parentSpanId` became `parentSpanContext` (a full
+        // SpanContext); OTLP still wants the bare hex parent span id.
+        parentSpanId: span.parentSpanContext?.spanId ?? "",
         name: span.name,
         kind: toOtlpKind(span.kind),
         startTimeUnixNano: hrTimeToUnixNano(span.startTime),
@@ -268,12 +270,203 @@ function injectTraceparent(input, init, traceparent) {
 /** Max response body size to clone for gen_ai enrichment (512 KB). */
 const LLM_RESPONSE_SIZE_CAP = 512 * 1024;
 /**
- * Patch `globalThis.fetch` exactly once to emit a CLIENT child span + inject
- * `traceparent` for outbound subrequests. `ingestHost` is the bare ingest
- * hostname (lower-case, no port) so the exporter's own uploads are never traced.
- * `aiCfg` enables gen_ai semantic-convention enrichment for known LLM providers.
+ * Context key under which `runNativeSpan` / `withSpan` publish the request's
+ * Cloudflare native tracer, so nested helpers (and the fetch wrapper) can join
+ * the platform trace tree instead of creating OTel-provider spans.
+ */
+const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-tracing");
+/**
+ * Latest ingest host / ai config seen by `ensureFetchInstrumentation`. The
+ * wrapper is installed ONCE per isolate but `instrument()` may reach it first
+ * from native mode (no exporter → no ingest host) and later from direct mode
+ * (or vice-versa), so the wrapper reads these refs at call time instead of
+ * closing over the first caller's values.
+ */
+let _fetchIngestHost = "";
+let _fetchAiCfg = {};
+/** A promise whose settle handles are exposed. */
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/** Parse the outbound target; null when it isn't an absolute URL. */
+function parseTarget(input) {
+    try {
+        return new URL(outboundUrl(input));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Request-side gen_ai attributes for a resolved LLM target: `gen_ai.system`,
+ * `gen_ai.operation.name`, `heystack.ai.gateway` (when routed through a
+ * configured gateway) and, when the request body is already a JSON string (the
+ * common LLM-SDK case), `gen_ai.request.*`. The outgoing Request body is never
+ * cloned/consumed. Returns the parsed body too so content capture (opt-in) can
+ * reuse it without a second parse.
+ */
+function llmRequestSide(resolved, url, init) {
+    let parsedReqBody = undefined;
+    if (typeof init?.body === "string") {
+        try {
+            parsedReqBody = JSON.parse(init.body);
+        }
+        catch {
+            // body not JSON — request enrichment limited to system/operation
+        }
+    }
+    const attrs = {
+        ...llmRequestAttrs(resolved.provider, parsedReqBody),
+        "gen_ai.operation.name": llmOperationName(url.pathname),
+    };
+    if (resolved.gateway)
+        attrs["heystack.ai.gateway"] = resolved.gateway;
+    return { attrs, parsedReqBody };
+}
+/**
+ * Response-side gen_ai enrichment shared by the direct (OTel CLIENT span) and
+ * native (Cloudflare span) paths. Never throws and NEVER consumes the caller's
+ * body:
+ *   - JSON (size-capped): parse a clone, set `gen_ai.response.*` + usage, and
+ *     opt-in content attrs. `settled` resolves immediately.
+ *   - `text/event-stream`: tee the body; the caller gets a Response wrapping
+ *     one branch, the other is scanned incrementally for usage/model/id only
+ *     (content deltas are discarded as they arrive). `settled` resolves when
+ *     the stream closes or errors — the span must stay open until then.
+ *   - anything else: passthrough, `settled` resolves immediately.
+ */
+async function enrichLLMResponse(span, provider, response, parsedReqBody, aiCfg) {
+    const done = { response, settled: Promise.resolve() };
+    try {
+        const ct = response.headers.get("content-type") ?? "";
+        const isStream = ct.includes("event-stream");
+        if (isStream) {
+            if (!response.body)
+                return done;
+            const [toCaller, toScanner] = response.body.tee();
+            const out = new Response(toCaller, response);
+            const settled = scanSseStreamForUsage(toScanner, provider)
+                .then((attrs) => {
+                for (const [k, v] of Object.entries(attrs))
+                    span.setAttribute(k, v);
+            })
+                .catch(() => {
+                // scanner never rejects; belt-and-braces
+            });
+            return { response: out, settled };
+        }
+        const cl = parseInt(response.headers.get("content-length") ?? "0", 10);
+        const isJson = ct.includes("application/json");
+        const withinCap = isNaN(cl) || cl === 0 || cl <= LLM_RESPONSE_SIZE_CAP;
+        if (isJson && withinCap) {
+            const rb = await response.clone().json();
+            for (const [k, v] of Object.entries(llmResponseAttrs(provider, rb)))
+                span.setAttribute(k, v);
+            if (aiCfg.captureContent) {
+                for (const [k, v] of Object.entries(llmContentAttrs(provider, parsedReqBody, rb, {
+                    redact: aiCfg.redact,
+                    maxChars: aiCfg.maxContentChars,
+                }))) {
+                    span.setAttribute(k, v);
+                }
+            }
+        }
+    }
+    catch {
+        // parse failure — degrade to the plain span (no throw, no side effects)
+    }
+    return done;
+}
+/**
+ * Native-tracing path for an outbound LLM call: open a Cloudflare custom span
+ * named `<operation> <provider>` (e.g. `chat mistral`) via the request's
+ * `ctx.tracing`, set request-side `gen_ai.*`, run the ORIGINAL fetch inside it
+ * (so Cloudflare's own subrequest span nests underneath), then enrich from the
+ * response. Cloudflare's `enterSpan` ends the span when the callback settles,
+ * so for a streaming response the callback stays pending until the SSE body
+ * closes while the Response is handed back to the caller immediately through a
+ * deferred — that is what lets usage tokens land on the span without buffering
+ * or delaying the stream. No OTel provider/exporter is involved.
+ */
+function nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch, aiCfg) {
+    const ready = deferred();
+    const name = `${llmOperationName(url.pathname)} ${resolved.provider}`;
+    let run;
+    let invoked = false;
+    try {
+        run = nativeTracing.enterSpan(name, async (nativeSpan) => {
+            invoked = true;
+            // Unsampled invocation: skip all enrichment work (no tee, no clone).
+            if (!nativeSpan.isTraced) {
+                try {
+                    ready.resolve(await originalFetch(input, init));
+                }
+                catch (error) {
+                    ready.reject(error);
+                }
+                return;
+            }
+            const adapter = new NativeSpanAdapter(nativeSpan, true);
+            const { attrs, parsedReqBody } = llmRequestSide(resolved, url, init);
+            adapter.setAttributes({ ...attrs, "server.address": url.hostname });
+            try {
+                const response = await originalFetch(input, init);
+                adapter.setAttribute("http.response.status_code", response.status);
+                if (response.status >= 400)
+                    adapter.setAttribute("error.type", String(response.status));
+                const { response: out, settled } = await enrichLLMResponse(adapter, resolved.provider, response, parsedReqBody, aiCfg);
+                ready.resolve(out);
+                // Keep the native span open until the (streamed) body has closed.
+                await settled;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                adapter.recordException(err);
+                adapter.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                ready.reject(error);
+            }
+        });
+    }
+    catch {
+        // enterSpan itself threw (should not happen) — fail open to the plain fetch.
+        return originalFetch(input, init);
+    }
+    // A platform tracer that returns without running the callback must never
+    // hang the app's fetch — fail open to the plain fetch.
+    if (!invoked)
+        return originalFetch(input, init);
+    // All errors are routed to `ready`; make sure the callback promise never
+    // surfaces as an unhandled rejection.
+    Promise.resolve(run).catch(() => { });
+    return ready.promise;
+}
+/**
+ * Patch `globalThis.fetch` exactly once. The wrapper decides per call which
+ * tracing plane the current request is on:
+ *
+ *   - **Native** (`ctx.tracing` present, published in OTel context by
+ *     `runNativeSpan`): a lean LLM-only path. Targets that resolve to an LLM
+ *     provider (direct host or a configured `ai.gateways` pattern) get a native
+ *     `<operation> <provider>` span with `gen_ai.*` enrichment; every other
+ *     fetch passes straight through UNTOUCHED (Cloudflare already records it).
+ *   - **Direct** (an OTel span is active): a CLIENT child span + `traceparent`
+ *     injection for every subrequest (distributed tracing), plus the same
+ *     `gen_ai.*` enrichment for LLM targets.
+ *
+ * `ingestHost` is the bare ingest hostname (lower-case, no port) so the
+ * exporter's own uploads are never traced; native callers pass "" (no exporter).
+ * `aiCfg` configures gen_ai enrichment (content capture is opt-in).
  */
 function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
+    if (ingestHost)
+        _fetchIngestHost = ingestHost;
+    _fetchAiCfg = aiCfg;
     if (_fetchInstrumented)
         return;
     _fetchInstrumented = true;
@@ -284,16 +477,28 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
     _originalFetch = originalFetch;
     const wrapper = async (input, init) => {
         const active = context.active();
-        // Passthrough UNCHANGED when there is nothing to parent to (no active span,
-        // e.g. a fetch outside a traced request) or tracing is suppressed (the
-        // exporter's own POST, or anything under suppressTracing).
-        if (isTracingSuppressed(active) || !trace.getSpan(active)) {
+        // Passthrough UNCHANGED when tracing is suppressed (the exporter's own POST,
+        // or anything under suppressTracing).
+        if (isTracingSuppressed(active)) {
+            return originalFetch(input, init);
+        }
+        // Native plane: LLM-only. Non-LLM subrequests are Cloudflare's to record.
+        const nativeTracing = active.getValue(NATIVE_TRACING_CONTEXT_KEY);
+        if (nativeTracing) {
+            const url = parseTarget(input);
+            const resolved = url ? resolveLLMProvider(url, _fetchAiCfg.gateways) : null;
+            if (!url || !resolved)
+                return originalFetch(input, init);
+            return nativeLLMFetch(nativeTracing, resolved, url, input, init, originalFetch, _fetchAiCfg);
+        }
+        // Direct plane: nothing to parent to (a fetch outside a traced request).
+        if (!trace.getSpan(active)) {
             return originalFetch(input, init);
         }
         const target = outboundUrl(input);
         const host = safeHostname(target);
         // No parseable host, or the ingest host itself (self-span) → don't trace.
-        if (!host || host === ingestHost) {
+        if (!host || host === _fetchIngestHost) {
             return originalFetch(input, init);
         }
         const method = outboundMethod(input, init);
@@ -308,60 +513,29 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
         const sc = span.spanContext();
         const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
         const [reqInput, reqInit] = injectTraceparent(input, init, traceparent);
-        // gen_ai enrichment — request side.
-        // Only when host is a known LLM provider and the body is already a string
-        // (the common LLM SDK case). Never clone/read the outgoing Request body.
-        const provider = detectLLMProvider(host);
+        // gen_ai enrichment — request side (direct host or configured gateway).
+        const url = parseTarget(input);
+        const resolved = url ? resolveLLMProvider(url, _fetchAiCfg.gateways) : null;
         let parsedReqBody = undefined;
-        if (provider !== null) {
-            // Only read the request body when it's already a string (the common LLM
-            // SDK case). Never clone/consume the outgoing Request.
-            const bodyStr = typeof init?.body === "string" ? init.body : undefined;
-            if (typeof bodyStr === "string") {
-                try {
-                    parsedReqBody = JSON.parse(bodyStr);
-                    for (const [k, v] of Object.entries(llmRequestAttrs(provider, parsedReqBody))) {
-                        span.setAttribute(k, v);
-                    }
-                }
-                catch {
-                    // body not valid JSON — skip request enrichment
-                }
-            }
+        if (url && resolved) {
+            const side = llmRequestSide(resolved, url, init);
+            parsedReqBody = side.parsedReqBody;
+            span.setAttributes(side.attrs);
         }
+        // For a streamed LLM response the span must outlive this call (it ends
+        // when the SSE body closes), so `finally` must not end it in that case.
+        let deferEnd = false;
         try {
             const response = await originalFetch(reqInput, reqInit);
             span.setAttribute("http.response.status_code", response.status);
-            // gen_ai enrichment — response side.
-            // Guard: known provider, JSON content-type (not event-stream), size cap.
-            // Always clone — NEVER consume the original response body.
-            if (provider !== null) {
-                try {
-                    const ct = response.headers.get("content-type") ?? "";
-                    const cl = parseInt(response.headers.get("content-length") ?? "0", 10);
-                    const isJson = ct.includes("application/json");
-                    const isStream = ct.includes("event-stream");
-                    const withinCap = isNaN(cl) || cl === 0 || cl <= LLM_RESPONSE_SIZE_CAP;
-                    if (isJson && !isStream && withinCap) {
-                        const rb = await response.clone().json();
-                        for (const [k, v] of Object.entries(llmResponseAttrs(provider, rb))) {
-                            span.setAttribute(k, v);
-                        }
-                        if (aiCfg.captureContent) {
-                            for (const [k, v] of Object.entries(llmContentAttrs(provider, parsedReqBody, rb, {
-                                redact: aiCfg.redact,
-                                maxChars: aiCfg.maxContentChars,
-                            }))) {
-                                span.setAttribute(k, v);
-                            }
-                        }
-                    }
-                }
-                catch {
-                    // parse failure — degrade to plain CLIENT span (no throw, no side effects)
-                }
+            if (!resolved)
+                return response;
+            const { response: out, settled } = await enrichLLMResponse(span, resolved.provider, response, parsedReqBody, _fetchAiCfg);
+            if (out !== response) {
+                deferEnd = true;
+                void settled.then(() => span.end());
             }
-            return response;
+            return out;
         }
         catch (error) {
             span.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -372,7 +546,8 @@ function ensureFetchInstrumentation(ingestHost, aiCfg = {}) {
             throw error;
         }
         finally {
-            span.end();
+            if (!deferEnd)
+                span.end();
         }
     };
     _fetchWrapper = wrapper;
@@ -390,6 +565,8 @@ export function __resetFetchInstrumentation() {
     _fetchInstrumented = false;
     _originalFetch = undefined;
     _fetchWrapper = undefined;
+    _fetchIngestHost = "";
+    _fetchAiCfg = {};
 }
 // ---------------------------------------------------------------------------
 // Exporter
@@ -563,6 +740,125 @@ export class HeystackSpanExporter {
         await Promise.allSettled([...this.pending]);
     }
 }
+function nativeTracingFromContext() {
+    return context.active().getValue(NATIVE_TRACING_CONTEXT_KEY);
+}
+/**
+ * Adapts Cloudflare's deliberately-small Span API to the OTel API shape used by
+ * `withSpan`. Unsupported OTel operations degrade to attributes instead of
+ * creating a second exporter/provider.
+ */
+class NativeSpanAdapter {
+    nativeSpan;
+    autoEnd;
+    constructor(nativeSpan, autoEnd) {
+        this.nativeSpan = nativeSpan;
+        this.autoEnd = autoEnd;
+    }
+    spanContext() { return INVALID_SPAN_CONTEXT; }
+    setAttribute(key, value) {
+        try {
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+                this.nativeSpan.setAttribute(key, value);
+            }
+            else if (Array.isArray(value)) {
+                this.nativeSpan.setAttribute(key, JSON.stringify(value));
+            }
+        }
+        catch {
+            // Telemetry must never surface as an application error (e.g. a platform
+            // span rejecting a value); drop the attribute instead.
+        }
+        return this;
+    }
+    setAttributes(attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined)
+                this.setAttribute(key, value);
+        }
+        return this;
+    }
+    addEvent(name, attributesOrStartTime) {
+        const prefix = `event.${name}`;
+        this.nativeSpan.setAttribute(prefix, true);
+        if (attributesOrStartTime && !Array.isArray(attributesOrStartTime) && typeof attributesOrStartTime === "object") {
+            for (const [key, value] of Object.entries(attributesOrStartTime)) {
+                if (value !== undefined)
+                    this.setAttribute(`${prefix}.${key}`, value);
+            }
+        }
+        return this;
+    }
+    addLink(_link) { return this; }
+    addLinks(_links) { return this; }
+    /** True once `recordException` stamped a specific `error.type` (the exception class). */
+    errorTyped = false;
+    setStatus(status) {
+        if (status.code === SpanStatusCode.ERROR) {
+            // Don't clobber the more specific class name a preceding recordException set.
+            if (!this.errorTyped)
+                this.nativeSpan.setAttribute("error.type", "error");
+            if (status.message)
+                this.nativeSpan.setAttribute("error.message", status.message);
+        }
+        return this;
+    }
+    updateName(_name) { return this; }
+    end(_endTime) {
+        if (!this.autoEnd)
+            this.nativeSpan.end();
+    }
+    isRecording() { return this.nativeSpan.isTraced; }
+    recordException(exception, _time) {
+        const error = exception instanceof Error ? exception : new Error(String(exception));
+        this.nativeSpan.setAttribute("error.type", error.name || "Error");
+        this.errorTyped = true;
+        this.nativeSpan.setAttribute("error.message", error.message);
+        if (error.stack)
+            this.nativeSpan.setAttribute("exception.stacktrace", error.stack);
+    }
+}
+function getNativeTracing(ctx) {
+    const candidate = ctx.tracing;
+    return candidate && typeof candidate.enterSpan === "function" ? candidate : undefined;
+}
+function setNativeRequestAttributes(span, config, req) {
+    const url = new URL(req.url);
+    span.setAttribute("service.name", config.service);
+    span.setAttribute("http.route", url.pathname);
+    if (config.version)
+        span.setAttribute("service.version", config.version);
+    if (config.build)
+        span.setAttribute("service.build", config.build);
+    const userInfo = config.getUser?.(req);
+    if (userInfo?.id)
+        span.setAttribute("enduser.id", userInfo.id);
+    if (userInfo?.session)
+        span.setAttribute("session.id", userInfo.session);
+    const requestId = userInfo?.requestId ?? req.headers.get("cf-ray") ?? undefined;
+    if (requestId)
+        span.setAttribute("http.request.id", requestId);
+}
+async function runNativeSpan(nativeTracing, name, attrs, fn) {
+    ensureContextManager();
+    return nativeTracing.enterSpan(name, async (nativeSpan) => {
+        const adapter = new NativeSpanAdapter(nativeSpan, true);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined)
+                adapter.setAttribute(key, value);
+        }
+        const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
+        try {
+            return await context.with(nativeContext, () => fn(adapter));
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            adapter.recordException(err);
+            adapter.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+            throw error;
+        }
+    });
+}
 /**
  * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
  * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
@@ -578,7 +874,7 @@ export function createTracerProvider(config) {
     const provider = new BasicTracerProvider({
         // service.name is always present; service.version/service.build are added
         // only when the caller supplied `version`/`build` (release attribution).
-        resource: new Resource({
+        resource: resourceFromAttributes({
             [ATTR_SERVICE_NAME]: config.service,
             ...releaseResourceAttributes(config),
         }),
@@ -824,6 +1120,25 @@ export function instrument(handler, config) {
     const originalFetch = handler.fetch?.bind(handler);
     if (originalFetch) {
         wrapped.fetch = async (req, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                // `withSpan()` discovers the request's native tracer through OTel
+                // context. Register our WinterCG-safe manager even though native mode
+                // intentionally does not create an OTel provider/exporter.
+                //
+                // Install the (LLM-only under native) fetch wrapper so outbound calls
+                // to LLM providers/gateways still get gen_ai.* enrichment — native mode
+                // never runs `setup()`, which is where the direct plane installs it.
+                ensureFetchInstrumentation("", config.ai ?? {});
+                return runNativeSpan(nativeTracing, "heystack.request", {}, async (adapter) => {
+                    setNativeRequestAttributes(adapter, config, req);
+                    const response = await originalFetch(req, env, ctx);
+                    adapter.setAttribute("http.response.status_code", response.status);
+                    if (response.status >= 500)
+                        adapter.setAttribute("error.type", "http_error");
+                    return response;
+                });
+            }
             const s = setup(env);
             if (!s)
                 return originalFetch(req, env, ctx);
@@ -998,6 +1313,18 @@ export function instrument(handler, config) {
     const originalQueue = handler.queue?.bind(handler);
     if (originalQueue) {
         wrapped.queue = async (batch, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                ensureFetchInstrumentation("", config.ai ?? {});
+                return runNativeSpan(nativeTracing, `heystack.queue ${batch.queue}`, {
+                    "service.name": config.service,
+                    "messaging.batch.message_count": batch.messages.length,
+                    "messaging.destination.name": batch.queue,
+                    "messaging.operation.type": "process",
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalQueue(batch, env, ctx));
+            }
             const s = setup(env);
             if (!s)
                 return originalQueue(batch, env, ctx);
@@ -1030,6 +1357,17 @@ export function instrument(handler, config) {
     const originalScheduled = handler.scheduled?.bind(handler);
     if (originalScheduled) {
         wrapped.scheduled = async (controller, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                ensureFetchInstrumentation("", config.ai ?? {});
+                return runNativeSpan(nativeTracing, `heystack.scheduled ${controller.cron}`, {
+                    "service.name": config.service,
+                    "faas.trigger": "timer",
+                    "cloudflare.scheduled.cron": controller.cron,
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalScheduled(controller, env, ctx));
+            }
             const s = setup(env);
             if (!s)
                 return originalScheduled(controller, env, ctx);
@@ -1063,6 +1401,23 @@ export function instrument(handler, config) {
 export async function withSpan(name, attrsOrFn, maybeFn) {
     const attrs = typeof attrsOrFn === "function" ? undefined : attrsOrFn;
     const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
+    const nativeTracing = nativeTracingFromContext();
+    if (nativeTracing) {
+        return nativeTracing.enterSpan(name, async (nativeSpan) => {
+            const adapter = new NativeSpanAdapter(nativeSpan, true);
+            if (attrs)
+                adapter.setAttributes(attrs);
+            const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
+            try {
+                return await context.with(nativeContext, () => fn(adapter));
+            }
+            catch (err) {
+                adapter.recordException(err instanceof Error ? err : new Error(String(err)));
+                adapter.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
+        });
+    }
     const tracer = trace.getTracer("heystack");
     const span = tracer.startSpan(name, attrs ? { attributes: attrs } : undefined);
     const ctx = trace.setSpan(context.active(), span);
@@ -1078,6 +1433,14 @@ export async function withSpan(name, attrsOrFn, maybeFn) {
         span.end();
     }
 }
+export async function withCloudflareSpan(ctx, name, attrsOrFn, maybeFn) {
+    const attrs = typeof attrsOrFn === "function" ? {} : attrsOrFn;
+    const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
+    const tracing = "enterSpan" in ctx ? ctx : getNativeTracing(ctx);
+    if (tracing)
+        return runNativeSpan(tracing, name, attrs, fn);
+    return withSpan(name, attrs, fn);
+}
 /**
  * Add a named event (with optional attributes) to the currently-active span.
  * No-op when no span is active.
@@ -1086,3 +1449,19 @@ export function addEvent(name, attrs) {
     const span = trace.getSpan(context.active());
     span?.addEvent(name, attrs);
 }
+// ---------------------------------------------------------------------------
+// gen_ai helpers for manual spans (e.g. `env.AI.run`, or any LLM call the fetch
+// wrapper cannot see). Pure, WinterCG-safe; pair them with `withSpan`.
+// ---------------------------------------------------------------------------
+/**
+ * `gen_ai.system` + `gen_ai.request.*` from an LLM request body (model,
+ * max_tokens, temperature). Alias of the internal request mapper.
+ */
+export { llmRequestAttrs as genAiRequestAttrs } from "./llm-enrich.js";
+/**
+ * `gen_ai.response.*` + `gen_ai.usage.*` from an LLM response object. Understands
+ * OpenAI/Mistral (`usage.prompt_tokens`/`completion_tokens`), Anthropic
+ * (`usage.input_tokens`/`output_tokens`) and Google (`usageMetadata`) shapes —
+ * Workers AI results (`usage.prompt_tokens`/`completion_tokens`) included.
+ */
+export { llmResponseAttrs as genAiResponseAttrs } from "./llm-enrich.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,10 @@
       "types": "./dist/workers.d.ts",
       "import": "./dist/workers.js"
     },
+    "./workers/agents": {
+      "types": "./dist/workers-agents.d.ts",
+      "import": "./dist/workers-agents.js"
+    },
     "./web": {
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js"
@@ -46,13 +50,13 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/core": "^1.30.0",
-    "@opentelemetry/sdk-node": "^0.57.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.57.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.55.0",
-    "@opentelemetry/sdk-trace-base": "^1.30.0",
-    "@opentelemetry/resources": "^1.30.0",
-    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "@opentelemetry/core": "^2.11.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
     "rrweb": "^2.0.0-alpha.18"
   },
   "devDependencies": {