@heystack/otel 0.12.0 → 0.14.0

package/dist/llm-enrich.js

@@ -8,12 +8,112 @@ export function detectLLMProvider(host) {
         return "openai";
     if (h === "api.anthropic.com")
         return "anthropic";
+    if (h === "api.mistral.ai")
+        return "mistral";
     if (h === "generativelanguage.googleapis.com")
         return "google";
     if (h === "gateway.ai.cloudflare.com" || h.endsWith(".gateway.ai.cloudflare.com"))
         return "cloudflare";
     return null;
 }
+/** Map a gateway path token to a provider. `gemini` → google, `workers-ai` → cloudflare. */
+export function providerFromToken(token) {
+    switch (token.toLowerCase()) {
+        case "openai":
+            return "openai";
+        case "anthropic":
+            return "anthropic";
+        case "google":
+        case "gemini":
+            return "google";
+        case "mistral":
+            return "mistral";
+        case "cloudflare":
+        case "workers-ai":
+            return "cloudflare";
+        default:
+            return null;
+    }
+}
+function hostMatchesSuffix(host, suffix) {
+    const s = suffix.toLowerCase().replace(/^\.+/, "");
+    if (!s)
+        return false;
+    return host === s || host.endsWith("." + s);
+}
+/** Split a path into non-empty segments. */
+function segments(path) {
+    return path.split("/").filter((s) => s.length > 0);
+}
+/**
+ * Resolve the LLM provider for an outbound URL: direct host table first, then
+ * each configured gateway pattern. Returns null when neither matches. Pure and
+ * exception-free (a malformed gateway entry is skipped, never thrown).
+ */
+export function resolveLLMProvider(url, gateways) {
+    const host = url.hostname.toLowerCase();
+    const direct = detectLLMProvider(host);
+    if (direct)
+        return { provider: direct };
+    if (!gateways || gateways.length === 0)
+        return null;
+    const pathSegs = segments(url.pathname);
+    for (const gw of gateways) {
+        try {
+            if (!gw || typeof gw.hostSuffix !== "string" || typeof gw.pathPattern !== "string")
+                continue;
+            if (!hostMatchesSuffix(host, gw.hostSuffix))
+                continue;
+            const patternSegs = segments(gw.pathPattern);
+            const providerIdx = patternSegs.findIndex((s) => s.toLowerCase() === ":provider");
+            if (providerIdx === -1 || pathSegs.length < patternSegs.length)
+                continue;
+            let ok = true;
+            for (let i = 0; i < patternSegs.length; i++) {
+                const p = patternSegs[i];
+                if (p.startsWith(":"))
+                    continue; // any single segment
+                if (p !== decodeURIComponentSafe(pathSegs[i])) {
+                    ok = false;
+                    break;
+                }
+            }
+            if (!ok)
+                continue;
+            const provider = providerFromToken(decodeURIComponentSafe(pathSegs[providerIdx]));
+            if (provider)
+                return { provider, gateway: host };
+        }
+        catch {
+            // malformed entry — skip
+        }
+    }
+    return null;
+}
+function decodeURIComponentSafe(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * Best-effort `gen_ai.operation.name` from the request path. Chat-style
+ * endpoints (OpenAI/Mistral `chat/completions`, Anthropic `messages`, Google
+ * `*generateContent`) → `chat`; `embeddings` → `embeddings`; bare/fim
+ * `completions` → `text_completion`; anything else defaults to `chat`.
+ */
+export function llmOperationName(pathname) {
+    const p = pathname.toLowerCase();
+    if (p.includes("/embeddings"))
+        return "embeddings";
+    if (p.includes("/chat/completions") || p.includes("/messages") || p.includes("generatecontent"))
+        return "chat";
+    if (p.endsWith("/completions") || p.includes("/completions"))
+        return "text_completion";
+    return "chat";
+}
 /** Best-effort gen_ai.request.* from a parsed JSON request body. Never throws. */
 export function llmRequestAttrs(provider, body) {
     const out = { "gen_ai.system": provider };
@@ -37,30 +137,29 @@ export function llmResponseAttrs(provider, body) {
     if (!body || typeof body !== "object" || Array.isArray(body))
         return out;
     const b = body;
+    // Response model / id. OpenAI, Mistral (OpenAI-compatible) and Anthropic use
+    // `model` / `id`; Google uses `modelVersion` / `responseId`.
     if (typeof b["model"] === "string")
         out["gen_ai.response.model"] = b["model"];
+    else if (typeof b["modelVersion"] === "string")
+        out["gen_ai.response.model"] = b["modelVersion"];
     if (typeof b["id"] === "string")
         out["gen_ai.response.id"] = b["id"];
-    // Usage tokens — OpenAI: usage.prompt_tokens / completion_tokens
-    //               Anthropic: usage.input_tokens / output_tokens
-    if (b["usage"] && typeof b["usage"] === "object" && !Array.isArray(b["usage"])) {
-        const usage = b["usage"];
-        // OpenAI shape
-        if (typeof usage["prompt_tokens"] === "number") {
-            out["gen_ai.usage.input_tokens"] = usage["prompt_tokens"];
-        }
-        if (typeof usage["completion_tokens"] === "number") {
-            out["gen_ai.usage.output_tokens"] = usage["completion_tokens"];
-        }
-        // Anthropic shape (overrides OpenAI if both somehow present)
-        if (typeof usage["input_tokens"] === "number") {
-            out["gen_ai.usage.input_tokens"] = usage["input_tokens"];
-        }
-        if (typeof usage["output_tokens"] === "number") {
-            out["gen_ai.usage.output_tokens"] = usage["output_tokens"];
-        }
+    else if (typeof b["responseId"] === "string")
+        out["gen_ai.response.id"] = b["responseId"];
+    // Usage tokens — OpenAI/Mistral: usage.prompt_tokens / completion_tokens
+    //               Anthropic:      usage.input_tokens / output_tokens
+    //               Google:         usageMetadata.promptTokenCount / candidatesTokenCount
+    Object.assign(out, usageAttrs(b["usage"]));
+    if (b["usageMetadata"] && typeof b["usageMetadata"] === "object" && !Array.isArray(b["usageMetadata"])) {
+        const um = b["usageMetadata"];
+        if (typeof um["promptTokenCount"] === "number")
+            out["gen_ai.usage.input_tokens"] = um["promptTokenCount"];
+        if (typeof um["candidatesTokenCount"] === "number")
+            out["gen_ai.usage.output_tokens"] = um["candidatesTokenCount"];
     }
-    // Finish reason — OpenAI: choices[0].finish_reason; Anthropic: stop_reason
+    // Finish reason — OpenAI/Mistral: choices[0].finish_reason; Anthropic:
+    // stop_reason; Google: candidates[0].finishReason
     if (typeof b["stop_reason"] === "string") {
         out["gen_ai.response.finish_reason"] = b["stop_reason"];
     }
@@ -70,9 +169,183 @@ export function llmResponseAttrs(provider, body) {
             out["gen_ai.response.finish_reason"] = choice["finish_reason"];
         }
     }
+    else if (Array.isArray(b["candidates"]) && b["candidates"].length > 0) {
+        const cand = b["candidates"][0];
+        if (cand && typeof cand === "object" && typeof cand["finishReason"] === "string") {
+            out["gen_ai.response.finish_reason"] = cand["finishReason"];
+        }
+    }
     void provider; // provider available for future provider-specific logic
     return out;
 }
+/** `gen_ai.usage.*` from an OpenAI-style or Anthropic-style `usage` object. */
+function usageAttrs(usage) {
+    const out = {};
+    if (!usage || typeof usage !== "object" || Array.isArray(usage))
+        return out;
+    const u = usage;
+    // OpenAI / Mistral shape
+    if (typeof u["prompt_tokens"] === "number")
+        out["gen_ai.usage.input_tokens"] = u["prompt_tokens"];
+    if (typeof u["completion_tokens"] === "number")
+        out["gen_ai.usage.output_tokens"] = u["completion_tokens"];
+    // Anthropic shape (overrides OpenAI if both somehow present)
+    if (typeof u["input_tokens"] === "number")
+        out["gen_ai.usage.input_tokens"] = u["input_tokens"];
+    if (typeof u["output_tokens"] === "number")
+        out["gen_ai.usage.output_tokens"] = u["output_tokens"];
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Streaming (SSE) usage scanning — metadata only, never content
+//
+// Every provider streams `text/event-stream`; token usage arrives in one or two
+// chunks: OpenAI (with `stream_options.include_usage`) and Mistral put a `usage`
+// object in the final data chunk; Anthropic sends `message_start` (model, id,
+// input_tokens) and `message_delta` (output_tokens, stop_reason); Google sends
+// `usageMetadata` on the final chunk. The scanner parses each `data:` line's
+// JSON just long enough to lift those fields and discards the chunk. Content
+// deltas are never retained or copied into attributes.
+// ---------------------------------------------------------------------------
+/** Lines longer than this are skipped unparsed (a bound on per-chunk JSON.parse). */
+export const SSE_MAX_LINE_BYTES = 64 * 1024;
+/**
+ * Metadata attrs from ONE parsed stream chunk. Shares the response mapper and
+ * adds the Anthropic envelope (`message.{id,model,usage}` on `message_start`,
+ * `delta.stop_reason` on `message_delta`). Never throws.
+ */
+export function llmStreamChunkAttrs(provider, chunk) {
+    const out = llmResponseAttrs(provider, chunk);
+    if (!chunk || typeof chunk !== "object" || Array.isArray(chunk))
+        return out;
+    const c = chunk;
+    const msg = c["message"];
+    if (msg && typeof msg === "object" && !Array.isArray(msg)) {
+        const m = msg;
+        if (typeof m["id"] === "string")
+            out["gen_ai.response.id"] = m["id"];
+        if (typeof m["model"] === "string")
+            out["gen_ai.response.model"] = m["model"];
+        Object.assign(out, usageAttrs(m["usage"]));
+    }
+    const delta = c["delta"];
+    if (delta && typeof delta === "object" && !Array.isArray(delta)) {
+        const d = delta;
+        if (typeof d["stop_reason"] === "string")
+            out["gen_ai.response.finish_reason"] = d["stop_reason"];
+    }
+    return out;
+}
+/**
+ * Incremental SSE scanner: buffers at most one partial line, parses complete
+ * `data:` lines for usage/model/id/finish_reason and drops everything else
+ * immediately. Lines over `SSE_MAX_LINE_BYTES` are skipped without parsing.
+ */
+export function createSseUsageScanner(provider) {
+    const acc = {};
+    let buf = "";
+    // When a line has already exceeded the cap, keep discarding until its newline.
+    let skipping = false;
+    const handleLine = (raw) => {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (!line.startsWith("data:"))
+            return; // event:/id:/retry:/comments
+        const payload = line.slice(5).trim();
+        if (!payload || payload === "[DONE]")
+            return;
+        if (payload.charCodeAt(0) !== 123 /* { */)
+            return;
+        try {
+            const chunk = JSON.parse(payload);
+            const attrs = llmStreamChunkAttrs(provider, chunk);
+            for (const k of Object.keys(attrs))
+                acc[k] = attrs[k];
+        }
+        catch {
+            // not JSON — ignore this line
+        }
+    };
+    return {
+        feed(text) {
+            try {
+                let start = 0;
+                for (;;) {
+                    const nl = text.indexOf("\n", start);
+                    if (nl === -1) {
+                        const rest = text.slice(start);
+                        if (skipping)
+                            break;
+                        if (buf.length + rest.length > SSE_MAX_LINE_BYTES) {
+                            buf = "";
+                            skipping = true;
+                            break;
+                        }
+                        buf += rest;
+                        break;
+                    }
+                    const piece = text.slice(start, nl);
+                    start = nl + 1;
+                    if (skipping) {
+                        skipping = false;
+                        buf = "";
+                        continue;
+                    }
+                    if (buf.length + piece.length > SSE_MAX_LINE_BYTES) {
+                        buf = "";
+                        continue; // oversize line — skip it whole
+                    }
+                    const line = buf + piece;
+                    buf = "";
+                    handleLine(line);
+                }
+            }
+            catch {
+                // never throw into the caller's stream
+            }
+        },
+        result() {
+            if (buf && !skipping) {
+                const line = buf;
+                buf = "";
+                handleLine(line);
+            }
+            return { ...acc };
+        },
+    };
+}
+/**
+ * Drain a (teed) SSE body through the scanner and resolve with the accumulated
+ * metadata attrs when the stream closes. Resolves — never rejects — on a stream
+ * error, returning whatever was scanned so far. Reads chunk-by-chunk with a
+ * streaming `TextDecoder`, so the body is never buffered.
+ */
+export async function scanSseStreamForUsage(stream, provider) {
+    const scanner = createSseUsageScanner(provider);
+    const decoder = new TextDecoder();
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                scanner.feed(decoder.decode(value, { stream: true }));
+        }
+        scanner.feed(decoder.decode());
+    }
+    catch {
+        // upstream error/cancel — keep what we have
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignore
+        }
+    }
+    return scanner.result();
+}
 /** Content attrs, ONLY when captureContent is on. Size-capped per value, redactor applied. */
 export function llmContentAttrs(provider, reqBody, resBody, opts) {
     const out = {};

package/dist/node.js

@@ -3,7 +3,7 @@ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
 import { ExportResultCode } from "@opentelemetry/core";
-import { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { buildExporterConfig, releaseResourceAttributes, } from "./core.js";
 import { isSelfSpanAttrs, safeHostname } from "./self-span.js";
 /**
@@ -132,7 +132,7 @@ export function initHeystack(o) {
         // Release/commit attribution. NodeSDK merges `serviceName` on top of this
         // resource, so the final resource carries service.name + (when provided)
         // service.version + service.build. Empty when neither option nor env is set.
-        resource: new Resource(resolveNodeReleaseAttributes(o)),
+        resource: resourceFromAttributes(resolveNodeReleaseAttributes(o)),
         traceExporter,
         instrumentations,
     });

package/dist/workers-agents.d.ts

@@ -0,0 +1,49 @@
+import { type Span } from "@opentelemetry/api";
+import { type CloudflareNativeTracing } from "./workers";
+/** Structural equivalent of the Agents SDK event; no `agents` peer required. */
+export interface CloudflareAgentEvent {
+    type: string;
+    agent?: string;
+    name?: string;
+    payload?: Record<string, unknown>;
+    timestamp?: number;
+    [key: string]: unknown;
+}
+export interface CloudflareAgentsObservability {
+    emit(event: CloudflareAgentEvent): void;
+}
+export interface CloudflareAgentsObservabilityOptions {
+    /** Static fields added to every structured event and active-span event. */
+    attributes?: Record<string, string | number | boolean>;
+    /** Allow-list event types. By default every Agents SDK event is retained. */
+    include?: readonly string[];
+    /** Additional payload keys to redact. Common secret keys are always redacted. */
+    redactKeys?: readonly string[];
+    /** Override the structured-log sink (useful for tests/custom routing). */
+    logger?: (level: "info" | "error", value: Record<string, unknown>) => void;
+}
+/**
+ * Agents SDK `Observability` implementation. It emits one structured log for
+ * every lifecycle event and mirrors safe scalar metadata onto the active span.
+ * Native Workers log export then preserves trace correlation without an extra
+ * network request in the Agent/Durable Object request path.
+ */
+export declare function createCloudflareAgentsObservability(options?: CloudflareAgentsObservabilityOptions): CloudflareAgentsObservability;
+export interface CloudflareDiagnosticsMessage {
+    timestamp?: number;
+    channel?: string;
+    message?: CloudflareAgentEvent | unknown;
+}
+export interface CloudflareTailEvent {
+    diagnosticsChannelEvents?: CloudflareDiagnosticsMessage[];
+}
+/**
+ * Tail Worker handler for production Agents diagnostics channels. Attach the
+ * returned handler as a Tail Consumer; its structured logs are exported by the
+ * Tail Worker's own native OTLP logs destination.
+ */
+export declare function createCloudflareAgentsTailHandler(options?: CloudflareAgentsObservabilityOptions): {
+    tail(events: CloudflareTailEvent[]): Promise<void>;
+};
+/** Explicit async-safe native custom span for Agent model/tool/RPC work. */
+export declare function withCloudflareAgentSpan<T>(tracing: ExecutionContext | CloudflareNativeTracing, operation: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;

package/dist/workers-agents.js

@@ -0,0 +1,110 @@
+import { trace } from "@opentelemetry/api";
+import { withCloudflareSpan, } from "./workers";
+const SENSITIVE_KEY = /(?:authorization|cookie|password|secret|token|api[_-]?key|prompt|completion|content|message)/i;
+const ERROR_EVENT = /(?::error|:failed|:stalled|:interrupted|:exhausted)$/;
+function sanitize(value, extraKeys, depth = 0) {
+    if (depth > 5)
+        return "[truncated]";
+    if (value === null || typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return value.length > 2_000 ? `${value.slice(0, 2_000)}…` : value;
+    if (Array.isArray(value))
+        return value.slice(0, 50).map((item) => sanitize(item, extraKeys, depth + 1));
+    if (typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value).slice(0, 100)) {
+            out[key] = SENSITIVE_KEY.test(key) || extraKeys.has(key) ? "[redacted]" : sanitize(item, extraKeys, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}
+function eventAttributes(event) {
+    const attrs = { "cloudflare.agent.event.type": event.type };
+    if (event.agent)
+        attrs["cloudflare.agent.class"] = event.agent;
+    if (event.name)
+        attrs["cloudflare.agent.name"] = event.name;
+    if (event.timestamp)
+        attrs["cloudflare.agent.event.timestamp_ms"] = event.timestamp;
+    for (const [key, value] of Object.entries(event.payload ?? {})) {
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            if (!SENSITIVE_KEY.test(key))
+                attrs[`cloudflare.agent.${key}`] = value;
+        }
+    }
+    return attrs;
+}
+/**
+ * Agents SDK `Observability` implementation. It emits one structured log for
+ * every lifecycle event and mirrors safe scalar metadata onto the active span.
+ * Native Workers log export then preserves trace correlation without an extra
+ * network request in the Agent/Durable Object request path.
+ */
+export function createCloudflareAgentsObservability(options = {}) {
+    const include = options.include ? new Set(options.include) : undefined;
+    const redactKeys = new Set(options.redactKeys ?? []);
+    const logger = options.logger ?? ((level, value) => {
+        if (level === "error")
+            console.error(value);
+        else
+            console.log(value);
+    });
+    return {
+        emit(event) {
+            if (!event?.type || (include && !include.has(event.type)))
+                return;
+            const level = ERROR_EVENT.test(event.type) ? "error" : "info";
+            const safeEvent = sanitize(event, redactKeys);
+            const value = {
+                event: "cloudflare.agent",
+                ...options.attributes,
+                ...safeEvent,
+                severity: level,
+            };
+            logger(level, value);
+            const active = trace.getActiveSpan();
+            if (active?.isRecording())
+                active.addEvent(`cloudflare.agent.${event.type}`, {
+                    ...options.attributes,
+                    ...eventAttributes(event),
+                });
+        },
+    };
+}
+/**
+ * Tail Worker handler for production Agents diagnostics channels. Attach the
+ * returned handler as a Tail Consumer; its structured logs are exported by the
+ * Tail Worker's own native OTLP logs destination.
+ */
+export function createCloudflareAgentsTailHandler(options = {}) {
+    const observability = createCloudflareAgentsObservability(options);
+    return {
+        async tail(events) {
+            for (const event of events) {
+                for (const diagnostic of event.diagnosticsChannelEvents ?? []) {
+                    if (!diagnostic.channel?.startsWith("agents:"))
+                        continue;
+                    const message = diagnostic.message;
+                    if (!message || typeof message !== "object")
+                        continue;
+                    const agentEvent = message;
+                    observability.emit({
+                        ...agentEvent,
+                        type: agentEvent.type || diagnostic.channel.slice("agents:".length),
+                        timestamp: agentEvent.timestamp ?? diagnostic.timestamp,
+                        diagnostics_channel: diagnostic.channel,
+                    });
+                }
+            }
+        },
+    };
+}
+/** Explicit async-safe native custom span for Agent model/tool/RPC work. */
+export function withCloudflareAgentSpan(tracing, operation, attrs, fn) {
+    return withCloudflareSpan(tracing, `agent.${operation}`, {
+        "cloudflare.agent.operation": operation,
+        ...attrs,
+    }, fn);
+}

package/dist/workers.d.ts

@@ -2,6 +2,7 @@ import { type Span } from "@opentelemetry/api";
 import { type Context, type ContextManager } from "@opentelemetry/api";
 import { BasicTracerProvider, type ReadableSpan, type SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { type HeystackOptions } from "./core.js";
+import { type LLMGatewayConfig } from "./llm-enrich.js";
 declare const ExportResultCode: {
     readonly SUCCESS: 0;
     readonly FAILED: 1;
@@ -171,6 +172,17 @@ export interface WorkersConfig {
      * Defaults to `false` (no binding tracing). Consumed by a later task.
      */
     instrumentBindings?: boolean | string[];
+    /**
+     * Select the Workers tracing plane. `auto` (default) uses Cloudflare's native
+     * tracer when `ctx.tracing` is available and otherwise falls back to direct
+     * OTLP export. `native` prefers the platform tracer but still fails open when
+     * unavailable. `direct` always uses Heystack's fetch exporter.
+     *
+     * Native mode deliberately disables Heystack root/fetch/binding
+     * instrumentation: Cloudflare already emits those spans, and running both
+     * creates duplicate, disconnected trace trees.
+     */
+    nativeTracing?: "auto" | "native" | "direct";
     /**
      * Head-sampling configuration. When omitted (or `rate` >= 1), all traces are
      * kept. When `rate` < 1, a deterministic FNV-1a hash of the trace ID decides
@@ -192,20 +204,45 @@ export interface WorkersConfig {
     };
     /**
      * LLM/gen_ai capture for outbound calls to known providers (OpenAI, Anthropic,
-     * CF AI Gateway, Google). Metadata (model, tokens, latency, finish_reason) is
-     * always captured for detected providers.
+     * Mistral, Google, CF AI Gateway). Metadata (model, tokens, latency,
+     * finish_reason) is always captured for detected providers — including
+     * streamed (`text/event-stream`) responses, whose usage is lifted from the
+     * stream without buffering content. Works on both tracing planes: as a CLIENT
+     * span in direct mode and as a native `<operation> <provider>` span (e.g.
+     * `chat mistral`) under Cloudflare native tracing.
+     *
+     * `gateways` teaches the detector about AI gateways / proxies you call
+     * instead of the provider host (Wafer, a corporate proxy, …): each entry
+     * names the gateway host and a path pattern whose `:provider` segment carries
+     * the provider token (`openai | anthropic | google | gemini | mistral |
+     * cloudflare | workers-ai`). Resolved calls get `gen_ai.system=<provider>` +
+     * `heystack.ai.gateway=<host>`. Example for Wafer:
+     *   `gateways: [{ hostSuffix: "wafersecurity.ai", pathPattern: "/p/:tenant/:provider" }]`
      *
      * Set `captureContent: true` to also capture prompt/completion text (off by
      * default) — strongly recommended for AI-app RCA. Provide `redact` to scrub
      * sensitive text before it leaves the Worker. `maxContentChars` caps the length
-     * of each captured value (default 8000 characters).
+     * of each captured value (default 8000 characters). Content is never captured
+     * from streamed responses.
      */
     ai?: {
         captureContent?: boolean;
         redact?: (text: string) => string;
         maxContentChars?: number;
+        gateways?: LLMGatewayConfig[];
     };
 }
+/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
+export interface CloudflareNativeSpan {
+    readonly isTraced: boolean;
+    setAttribute(key: string, value: string | number | boolean | undefined): void;
+    end(): void;
+}
+/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
+export interface CloudflareNativeTracing {
+    enterSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
+    startActiveSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
+}
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
  * flush paths can drain its in-flight fetches directly (the OTel processor's
@@ -388,9 +425,30 @@ export declare function instrument<H extends WorkerHandler<any>>(handler: H, con
  */
 export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
 export declare function withSpan<T>(name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+/**
+ * Create a Cloudflare-native custom span using an explicit ExecutionContext.
+ * Prefer this form in code that calls `withSpan` after an `await` on a Worker
+ * without `nodejs_compat`: the explicit context cannot be lost across async
+ * boundaries. It falls back to the regular OTel tracer outside Cloudflare.
+ */
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
 /**
  * Add a named event (with optional attributes) to the currently-active span.
  * No-op when no span is active.
  */
 export declare function addEvent(name: string, attrs?: Record<string, string | number | boolean>): void;
 export type { Span };
+/**
+ * `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";
+export type { LLMGatewayConfig, LLMProvider } from "./llm-enrich.js";