@heystack/otel 0.13.0 → 0.14.0

package/README.md

@@ -13,7 +13,7 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
-> **Use `@heystack/otel` `>=0.13.0`.** 0.13 makes Cloudflare's native trace tree authoritative, adds async-safe native custom spans, queue/cron coverage, and the Agents SDK adapter. See [Migration](#migration--versioning) below.
+> **Use `@heystack/otel` `>=0.14.0`.** 0.14 makes LLM `gen_ai.*` telemetry work under Cloudflare native tracing (it was silently absent before), adds Mistral + AI-gateway (`ai.gateways`) detection and streaming token usage, and moves to the OpenTelemetry 2.x SDK (clears downstream Dependabot alerts). 0.13 made Cloudflare's native trace tree authoritative. See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -127,7 +127,7 @@ head_sampling_rate = 1
 persist = false
 ```
 
-Cloudflare creates the invocation and supported platform/binding spans and exports trace-correlated logs. `instrument()` detects `ctx.tracing` and adds Heystack business/identity attributes to that same tree. In this mode it creates no OTel provider, makes no Heystack export request, does not patch `fetch`, does not proxy bindings, and does not require `HEYSTACK_API_KEY` in the Worker.
+Cloudflare creates the invocation and supported platform/binding spans and exports trace-correlated logs. `instrument()` detects `ctx.tracing` and adds Heystack business/identity attributes to that same tree. In this mode it creates no OTel provider, makes no Heystack export request, does not proxy bindings, and does not require `HEYSTACK_API_KEY` in the Worker. The only `fetch` patch it installs is a **lean, LLM-only** one (0.14+): outbound calls to a detected LLM provider or a configured AI gateway get a native `<operation> <provider>` span (e.g. `chat mistral`) with `gen_ai.*` attributes — every other subrequest passes through untouched, since Cloudflare already records it. See [AI / LLM observability](#ai--llm-observability).
 
 ```ts
 import { instrument, withCloudflareSpan } from "@heystack/otel/workers";
@@ -213,7 +213,7 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`, and set `native
 | `getUser` | `(req: Request) => { id?, session?, requestId? } \| undefined` | Called per request. `id` → `enduser.id`, `session` → `session.id`, `requestId` → `http.request.id` (falls back to the `cf-ray` header). |
 | `instrumentBindings` | `boolean \| string[]` | `true` = auto child spans for all detected D1 / KV / R2 / Vectorize / Workers AI / Queue producer / Service binding bindings; `string[]` = only the named bindings. Default `false`. |
 | `sampling` | `{ rate?: number } \| { remote: true }` | Head-sampling configuration. `{ rate }`: keep a deterministic fraction of fresh root traces (0–1; default `1` = keep all). `{ remote: true }`: fetch the rate from the Heystack config endpoint instead — lets you change it centrally without redeploying. Cold isolates keep all traffic until the first config fetch resolves; fails open if the config can't be reached. Parent-respecting in both modes: a request arriving with a sampled `traceparent` is always recorded. See [Head sampling](#head-sampling) below. |
-| `ai` | `{ captureContent?: boolean; redact?: (text: string) => string; maxContentChars?: number }` | LLM/gen_ai capture for outbound calls to known providers. See [AI / LLM observability](#ai--llm-observability) below. |
+| `ai` | `{ captureContent?: boolean; redact?: (text: string) => string; maxContentChars?: number; gateways?: Array<{ hostSuffix: string; pathPattern: string }> }` | LLM/gen_ai capture for outbound calls to known providers (works under native tracing and the direct exporter). `gateways` declares AI gateways/proxies you call instead of the provider host (e.g. Wafer). See [AI / LLM observability](#ai--llm-observability) below. |
 | `waitUntil` | `(p: Promise<unknown>) => void` | Override the isolate keep-alive hook; defaults to the auto-detected `ctx.waitUntil`. |
 | `version` | `string?` | Release identifier → `service.version` resource attribute. Powers release health + suspect release. See [Release & commit attribution](#release--commit-attribution-version--build). |
 | `build` | `string?` | Commit SHA → `service.build` resource attribute. Powers suspect commit (deep-links to the commit when a repo URL is set in the console). |
@@ -273,29 +273,50 @@ These attributes are set automatically on every SERVER span from request metadat
 
 ### AI / LLM observability
 
-When your Worker calls an LLM API, `instrument()` automatically attaches [OpenTelemetry gen_ai semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) to the outbound CLIENT span. No extra code is needed — detection is based on the target hostname.
+When your Worker calls an LLM API, `instrument()` automatically attaches [OpenTelemetry gen_ai semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) to the outbound call. No extra code is needed — detection is based on the target URL. It works on **both tracing planes**:
 
-**Detected providers:**
+- **Cloudflare native tracing** (`nativeTracing: "auto" | "native"`, the default) — the call becomes a native span named `<operation> <provider>` (e.g. `chat mistral`, `chat google`) in Cloudflare's trace tree, carrying the `gen_ai.*` attributes below plus `server.address` and `http.response.status_code`. Non-LLM subrequests are not touched (Cloudflare records them itself). *(0.14+; before that, native mode emitted no `gen_ai.*` at all.)*
+- **Direct exporter** (`nativeTracing: "direct"`) — the attributes land on the outbound CLIENT span.
+
+**Detected providers (direct hosts):**
 - **OpenAI** — `api.openai.com`
 - **Anthropic** — `api.anthropic.com`
-- **Cloudflare AI Gateway** — any host ending in `gateway.ai.cloudflare.com`
+- **Mistral** — `api.mistral.ai`
 - **Google** — `generativelanguage.googleapis.com`
+- **Cloudflare AI Gateway** — any host ending in `gateway.ai.cloudflare.com`
+
+**AI gateways / proxies (`ai.gateways`):** if you call providers through a gateway such as [Wafer](https://wafersecurity.ai) instead of the provider host, tell the SDK how to read the provider off the URL. Each entry names the gateway host (exact or any subdomain) and a path pattern whose `:provider` segment carries the provider token — one of `openai`, `anthropic`, `google`, `gemini` (→ `google`), `mistral`, `cloudflare`, `workers-ai` (→ `cloudflare`). Literal segments must match; other `:params` match any segment; the provider's own API path may follow. Direct hosts are checked first; a gateway URL whose token is unknown is left untraced.
+
+```ts
+export default instrument(worker, {
+  service: "tp-api",
+  ai: {
+    gateways: [{ hostSuffix: "wafersecurity.ai", pathPattern: "/p/:tenant/:provider" }],
+  },
+});
+// https://wafersecurity.ai/p/talkpod/mistral/v1/chat/completions
+//   → gen_ai.system = "mistral", heystack.ai.gateway = "wafersecurity.ai"
+// https://wafersecurity.ai/p/talkpod/gemini/v1beta/models/gemini-2.5-flash:streamGenerateContent
+//   → gen_ai.system = "google",  heystack.ai.gateway = "wafersecurity.ai"
+```
 
 **Attributes captured automatically (metadata, always on):**
 
 | Attribute | Description |
 | --- | --- |
-| `gen_ai.system` | Provider name (`openai`, `anthropic`, `cloudflare`, `google`) |
+| `gen_ai.system` | Provider name (`openai`, `anthropic`, `mistral`, `google`, `cloudflare`) |
+| `gen_ai.operation.name` | `chat`, `embeddings` or `text_completion`, inferred from the request path |
+| `heystack.ai.gateway` | Gateway hostname — only when the provider was resolved via `ai.gateways` |
 | `gen_ai.request.model` | Model from the request body (`body.model`) |
 | `gen_ai.request.max_tokens` | Max tokens from the request (`max_tokens` or `max_completion_tokens`) |
 | `gen_ai.request.temperature` | Temperature from the request |
-| `gen_ai.response.model` | Model from the response body |
-| `gen_ai.response.id` | Response ID |
-| `gen_ai.usage.input_tokens` | Input/prompt tokens used |
-| `gen_ai.usage.output_tokens` | Output/completion tokens used |
-| `gen_ai.response.finish_reason` | Stop reason (`stop`, `end_turn`, etc.) |
+| `gen_ai.response.model` | Model from the response (`model`, or Google's `modelVersion`) |
+| `gen_ai.response.id` | Response ID (`id`, or Google's `responseId`) |
+| `gen_ai.usage.input_tokens` | Input/prompt tokens (`usage.prompt_tokens`, `usage.input_tokens`, or `usageMetadata.promptTokenCount`) |
+| `gen_ai.usage.output_tokens` | Output/completion tokens (`usage.completion_tokens`, `usage.output_tokens`, or `usageMetadata.candidatesTokenCount`) |
+| `gen_ai.response.finish_reason` | Stop reason (`stop`, `end_turn`, `STOP`, etc.) |
 
-Streaming responses (`text/event-stream`) skip response enrichment (the body is not consumed) but request-side attributes are still set.
+**Streaming responses (`text/event-stream`)** are enriched too (0.14+). The body is `tee()`d: your handler gets one branch untouched (byte-for-byte, no added latency); the SDK reads the other **without buffering content** — each `data:` line's JSON is inspected only for `usage` / `usageMetadata`, model, id and finish reason, then discarded. That covers Mistral and OpenAI (usage in the final chunk — for OpenAI send `stream_options: { include_usage: true }`), Anthropic (`message_start` input tokens + `message_delta` output tokens) and Google (`usageMetadata` on the last chunk). The span stays open until the stream closes (or errors), so its duration is the true time-to-last-token. Lines over 64 KB are skipped unparsed; a scanner failure never throws into your stream. Content is never captured from streams, even with `captureContent: true`.
 
 **Content capture (opt-in, strongly recommended for AI-app RCA):**
 
@@ -324,8 +345,9 @@ When `captureContent` is enabled, two additional attributes appear on the CLIENT
 
 **Body safety guarantees:**
 - Request body: only read when it is already a plain `string` (the common LLM SDK case). Non-string bodies (streams, FormData, etc.) are never touched.
-- Response body: read only from `response.clone()`, so the original response is returned untouched and your handler can call `.json()` / `.text()` normally.
-- Parse failures or unexpected shapes degrade silently to the plain CLIENT span — no errors are thrown.
+- Response body: JSON is read only from `response.clone()`; a stream is `tee()`d and your branch is handed back immediately. Either way the response you receive is intact and your handler can call `.json()` / `.text()` / `.body.getReader()` normally.
+- Parse failures or unexpected shapes degrade silently to the plain span — no errors are thrown.
+- Under native tracing the wrapper needs the request's native tracer in the active context, which propagates across `await`s only with `nodejs_compat` (AsyncLocalStorage). Without it an LLM call made after an `await` passes through untraced — the same caveat as `withSpan`. Use `withCloudflareSpan(ctx, …)` + `genAiResponseAttrs` for a manual span if you cannot enable `nodejs_compat`.
 - For a detected provider with a JSON response, the cloned body is parsed before the `fetch()` promise resolves to your handler (the span must close with usage attributes). This adds negligible latency to an already-slow LLM call.
 - The response size guard (512 KB) only applies when the response carries a `content-length` header; a chunked JSON response without one is still read. The known providers bound this via `max_tokens`, so it is safe in practice.
 
@@ -349,10 +371,35 @@ const data = await withSpan("call-llm", async () => {
 });
 ```
 
-`withSpan(name, attrs?, fn)` — runs `fn` inside a new child span parented to the currently-active span. The span is started before `fn` and ended in `finally`; exceptions are recorded on the span and re-thrown. The `fn` receives the live `Span` as its argument.
+`withSpan(name, attrs?, fn)` — runs `fn` inside a new child span parented to the currently-active span. The span is started before `fn` and ended in `finally`; exceptions are recorded on the span and re-thrown. The `fn` receives the live `Span` as its argument, so you can `span.setAttribute(s)` after the work has produced a result. Under Cloudflare native tracing it joins the native tree; otherwise it is an OTel child span.
 
 `addEvent(name, attrs?)` — adds a named event to the currently-active span. No-op when no span is active.
 
+#### LLM calls the auto-wrapper can't see (`env.AI.run`, SDKs with their own transport)
+
+The automatic `gen_ai.*` enrichment hooks `fetch`. Anything that doesn't go through `fetch` — Workers AI (`env.AI.run`), a binding, an SDK with a custom transport — is invisible to it. `withSpan` plus the two pure helpers `genAiRequestAttrs(provider, requestBody)` and `genAiResponseAttrs(provider, result)` (both exported from `/workers`) is the supported path; it works identically under native tracing and the direct exporter. Name the span `<operation> <provider>` so it lines up with the automatic ones:
+
+```ts
+import { instrument, withSpan, genAiRequestAttrs, genAiResponseAttrs } from "@heystack/otel/workers";
+
+async function chat(env: Env, prompt: string) {
+  const model = "@cf/meta/llama-3.1-8b-instruct";
+  return withSpan(
+    "chat cloudflare",
+    { ...genAiRequestAttrs("cloudflare", { model, max_tokens: 256 }), "gen_ai.operation.name": "chat" },
+    async (span) => {
+      const result = await env.AI.run(model, { prompt, max_tokens: 256 });
+      // Workers AI returns `usage: { prompt_tokens, completion_tokens }` for most text models;
+      // genAiResponseAttrs maps it to gen_ai.usage.input_tokens / output_tokens (no-op if absent).
+      span.setAttributes(genAiResponseAttrs("cloudflare", result));
+      return result;
+    },
+  );
+}
+```
+
+`genAiRequestAttrs` sets `gen_ai.system` + `gen_ai.request.{model,max_tokens,temperature}`; `genAiResponseAttrs` understands OpenAI/Mistral, Anthropic, Google and Workers AI response shapes and returns `gen_ai.response.{model,id,finish_reason}` + `gen_ai.usage.*`. Neither ever throws or captures prompt/completion text. (If `instrumentBindings` is on under the direct exporter, `env.AI.run` is already traced automatically — use the manual form under native tracing or for other call paths.)
+
 ### Why a ContextManager
 
 `context.with(...)` in OpenTelemetry is a **no-op unless a ContextManager is registered** with the global API. Without one, `suppressTracing()` — the primary defence against the self-trace feedback loop — silently does nothing in production. As of **0.3.2** the SDK registers a ContextManager exactly once at init. With `AsyncLocalStorage` (workerd under `nodejs_compat`, Node) you also get **cross-`await` parent→child span linking** and **per-request context isolation** — concurrent requests no longer share or clobber the active span.
@@ -545,6 +592,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.14.0`** — **gen_ai enrichment under Cloudflare native tracing, Mistral + AI-gateway detection, streaming usage; OpenTelemetry JS SDK 2.x.** (1) `/workers`: under `nativeTracing: "auto" | "native"` `instrument()` never installed the fetch wrapper, so native-mode Workers emitted **no** `gen_ai.*` telemetry. It now installs a lean LLM-only wrapper that opens a native `<operation> <provider>` span (e.g. `chat mistral`) with request/response `gen_ai.*` for detected providers and passes every other subrequest through untouched. (2) New provider **Mistral** (`api.mistral.ai`) and a new `ai.gateways` option (`[{ hostSuffix, pathPattern }]`, e.g. `{ hostSuffix: "wafersecurity.ai", pathPattern: "/p/:tenant/:provider" }`) that resolves the provider from an AI-gateway URL and stamps `heystack.ai.gateway`; `gemini` → `google`, `workers-ai` → `cloudflare`. New `gen_ai.operation.name`. (3) **Streaming (`text/event-stream`) responses now yield usage**: the body is `tee()`d and scanned line-by-line for `usage`/`usageMetadata`, model, id and finish reason only (never content); the span stays open until the stream closes. Google (`usageMetadata`) and Mistral response shapes added to the JSON path too. (4) New `/workers` exports `genAiRequestAttrs` / `genAiResponseAttrs` for manual `withSpan` spans around `env.AI.run` or any non-`fetch` LLM call. Native `error.type` now keeps the exception class instead of being overwritten with `error`. (5) All `@opentelemetry/*` dependencies move to the 2.x SDK line (`core`/`sdk-trace-base`/`resources` ^2.11, `sdk-node`/`exporter-trace-otlp-http` ^0.222, `auto-instrumentations-node` ^0.80, `semantic-conventions` ^1.43), clearing the downstream Dependabot alerts the 1.x line surfaced through this package (GHSA-8988-4f7v-96qf in `@opentelemetry/core`, GHSA-q7rr-3cgh-j5r3 in `sdk-node` / `auto-instrumentations-node` / `exporter-prometheus`, GHSA-45rx-2jwx-cxfr in `propagator-jaeger`). **Node ≥ 18.19 (or ≥ 20.6) is now required on `/node` and `/next`** — the 2.x SDK dropped Node 14/16. If you pass your own `instrumentations` array to `initHeystack`, upgrade those `@opentelemetry/instrumentation-*` packages to a release that peers on `@opentelemetry/core@^2` (the auto-instrumentations 0.80 set already does). `/workers` is still WinterCG-safe (no `node:*` imports). No other API changes; all new options are optional.
 - **`0.13.0`** — **Cloudflare-native tracing and complete Workers platform coverage.** On runtimes exposing `ctx.tracing`, `/workers` now joins Cloudflare's authoritative invocation trace instead of creating and exporting a duplicate tree. `nativeTracing: "auto"` is the default; `withCloudflareSpan(ctx, ...)` adds async-safe business spans, while fetch, queue, and scheduled handlers are enriched in the native tree. The new `/workers/agents` entry maps Cloudflare Agents observability callbacks and Tail Worker diagnostics to structured, redacted telemetry. Direct OTLP remains available with `nativeTracing: "direct"` for runtimes without the native API. Heystack ingest now preserves full OTLP trace/log fidelity, accepts OTLP metrics, and can import Workers Analytics metrics through the app-scoped Cloudflare connector. Native mode needs no Worker API-key secret and must not be combined with direct export.
 - **`0.11.0`** — **`/web`: browser error + console collection, in-app bug reports, and seekable replay keyframes.** `instrumentWeb` now captures uncaught errors (`window.onerror` + `unhandledrejection`) and `console.error` as OTLP logs by default (`event.name=browser.error` / `browser.console`, with `exception.*` semconv, `url.full`, `session_id`, and the active trace/span ids when `tracing` is on). New options: `errors?: boolean` (default `true`), `captureConsole?: 'error' | 'warn' | false` (default `'error'`). New **`reportBug({ message, email?, context? })`** API — a headless in-app bug reporter that POSTs to `/v1/bug-reports` and auto-attaches the URL, user agent, `session_id`, active `trace_id`, `release`/`build`, and the last ≤20 captured browser errors (also emitted as a `user.bug_report` log); reports triage in the console **Bugs** tab. The `version` / `build` options are now stamped as `service.version` / `service.build` on exported browser logs (release attribution). Console capture is recursion-guarded + rate-capped (no self-export loop, no flood). The recorder also checkpoints a keyframe (~60s) so the console player seeks from the nearest snapshot instead of loading the whole session. No breaking changes; all new options are optional.
 - **`0.10.0`** — **release / commit attribution (`version` + `build`) on every runtime entry.** New optional options: `version` → the `service.version` resource attribute (a release identifier such as `1.4.2` or a git tag), `build` → the `service.build` resource attribute (the commit SHA). They power **release health**, **suspect release**, and **suspect commit** in the console — attributing a regression to the version/commit that introduced it (suspect-commit deep-links to the commit when a repo URL is configured for the app). Wired on `/node`, `/next` (threaded to whichever runtime runs), and `/workers`; accepted on `/web` for API symmetry. `/node` also reads `HEYSTACK_SERVICE_VERSION` / `OTEL_SERVICE_VERSION` and `HEYSTACK_SERVICE_BUILD` as env fallbacks. Both options are optional and only emitted when non-empty. No breaking changes. See [Release & commit attribution](#release--commit-attribution-version--build).

package/dist/llm-enrich.d.ts

@@ -1,6 +1,41 @@
-export type LLMProvider = "openai" | "anthropic" | "cloudflare" | "google";
+export type LLMProvider = "openai" | "anthropic" | "cloudflare" | "google" | "mistral";
 /** Return the provider for a known LLM host, else null. Host is lower-case, no port. */
 export declare function detectLLMProvider(host: string): LLMProvider | null;
+export interface LLMGatewayConfig {
+    /**
+     * Gateway hostname. Matches the exact host or any subdomain of it
+     * (`wafersecurity.ai` matches `wafersecurity.ai` and `gw.wafersecurity.ai`,
+     * never `notwafersecurity.ai`). A leading dot is tolerated.
+     */
+    hostSuffix: string;
+    /**
+     * Path pattern whose `:provider` segment names the upstream provider, e.g.
+     * `/p/:tenant/:provider`. Literal segments must match exactly; other `:param`
+     * segments match any single segment; the request path may carry further
+     * segments after the pattern (the provider's own API path).
+     */
+    pathPattern: string;
+}
+export interface ResolvedLLMProvider {
+    provider: LLMProvider;
+    /** Set (to the gateway hostname) when the provider was resolved via a gateway. */
+    gateway?: string;
+}
+/** Map a gateway path token to a provider. `gemini` → google, `workers-ai` → cloudflare. */
+export declare function providerFromToken(token: string): LLMProvider | null;
+/**
+ * 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 declare function resolveLLMProvider(url: URL, gateways?: readonly LLMGatewayConfig[]): ResolvedLLMProvider | null;
+/**
+ * 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 declare function llmOperationName(pathname: string): "chat" | "embeddings" | "text_completion";
 export interface LLMRequestAttrs {
     [k: string]: string | number;
 }
@@ -8,6 +43,33 @@ export interface LLMRequestAttrs {
 export declare function llmRequestAttrs(provider: LLMProvider, body: unknown): LLMRequestAttrs;
 /** Best-effort gen_ai.response.* + usage from a parsed JSON response body. Never throws. */
 export declare function llmResponseAttrs(provider: LLMProvider, body: unknown): Record<string, string | number>;
+/** Lines longer than this are skipped unparsed (a bound on per-chunk JSON.parse). */
+export declare const SSE_MAX_LINE_BYTES: number;
+/**
+ * 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 declare function llmStreamChunkAttrs(provider: LLMProvider, chunk: unknown): Record<string, string | number>;
+export interface SseUsageScanner {
+    /** Feed decoded text (any chunk boundary). Never throws. */
+    feed(text: string): void;
+    /** Flush a trailing partial line and return the accumulated attrs. */
+    result(): Record<string, string | number>;
+}
+/**
+ * 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 declare function createSseUsageScanner(provider: LLMProvider): SseUsageScanner;
+/**
+ * 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 declare function scanSseStreamForUsage(stream: ReadableStream<Uint8Array>, provider: LLMProvider): Promise<Record<string, string | number>>;
 /** Content attrs, ONLY when captureContent is on. Size-capped per value, redactor applied. */
 export declare function llmContentAttrs(provider: LLMProvider, reqBody: unknown, resBody: unknown, opts: {
     redact?: (text: string) => string;

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.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;
@@ -203,18 +204,32 @@ 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. */
@@ -424,3 +439,16 @@ export declare function withCloudflareSpan<T>(ctx: ExecutionContext | Cloudflare
  */
 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";

package/dist/workers.js

@@ -10,12 +10,12 @@
 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,7 +740,6 @@ export class HeystackSpanExporter {
         await Promise.allSettled([...this.pending]);
     }
 }
-const NATIVE_TRACING_CONTEXT_KEY = createContextKey("heystack.cloudflare.native-tracing");
 function nativeTracingFromContext() {
     return context.active().getValue(NATIVE_TRACING_CONTEXT_KEY);
 }
@@ -581,11 +757,17 @@ class NativeSpanAdapter {
     }
     spanContext() { return INVALID_SPAN_CONTEXT; }
     setAttribute(key, value) {
-        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-            this.nativeSpan.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));
+            }
         }
-        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;
     }
@@ -609,9 +791,13 @@ class NativeSpanAdapter {
     }
     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) {
-            this.nativeSpan.setAttribute("error.type", "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);
         }
@@ -626,6 +812,7 @@ class NativeSpanAdapter {
     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);
@@ -687,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),
         }),
@@ -938,6 +1125,11 @@ export function instrument(handler, config) {
                 // `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);
@@ -1123,6 +1315,7 @@ export function instrument(handler, config) {
         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,
@@ -1166,6 +1359,7 @@ export function instrument(handler, config) {
         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",
@@ -1255,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.13.0",
+  "version": "0.14.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -50,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": {