@heystack/otel 0.13.0 → 0.15.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.15.0`.** 0.15 extends direct Workers instrumentation to D1 sessions and batches. Cloudflare native OTel remains the preferred path for Workers; direct SDK export is a compatibility fallback when native tracing is unavailable. See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -21,6 +21,8 @@ HEYSTACK_API_KEY=sk_live_…
 | --- | --- | --- |
 | Next.js — **any** deploy target (Vercel/Node **and** Cloudflare/OpenNext) | `@heystack/otel/next` | `registerHeystack` in `instrumentation.ts`. Auto-detects Node vs Cloudflare workerd and picks the right exporter. No-op on Edge. |
 | Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | Native-first `instrument()` wrapper; Cloudflare owns OTLP export and automatic platform spans. |
+| Cloudflare Python Workers | No `@heystack/otel` import | Enable Cloudflare native traces/logs and an OTLP destination. Python runs inside workerd, so platform tracing covers handler and supported binding operations without a JavaScript SDK. |
+| WebAssembly modules used by a Worker | Instrument the JavaScript/TypeScript host, if present | Enable Cloudflare native traces/logs for the Worker. Wasm execution is part of its host invocation; this package does not inject language-level spans inside Rust/Go/C Wasm code. |
 | Cloudflare Agents SDK / Agents Tail Worker | `@heystack/otel/workers/agents` | Structured Agents lifecycle events, trace correlation, redaction, and Tail Worker adapter. |
 | Node / Express / Fastify / NestJS (long-running server) | `@heystack/otel/node` | `initHeystack`: auto-instrumentations + graceful shutdown. |
 | Browser (SPA / any web frontend) | `@heystack/otel/web` | `instrumentWeb`: session replay + opt-in browser distributed tracing (`tracing: true`) that emits CLIENT spans + propagates W3C `traceparent` (browser→API shows as one trace). No-op on the server (SSR-safe). |
@@ -127,7 +129,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";
@@ -147,6 +149,12 @@ export default instrument(worker, {
 });
 ```
 
+Native export is the portable path across Workers languages. The dashboard destination sends OTLP/HTTP traces and logs, so the same configuration applies to JavaScript/TypeScript, [Python Workers](https://developers.cloudflare.com/workers/languages/python/), and Workers whose handlers call [WebAssembly modules](https://developers.cloudflare.com/workers/runtime-apis/webassembly/). Cloudflare's [OTel export documentation](https://developers.cloudflare.com/workers/observability/exporting-opentelemetry-data/) currently says infrastructure and custom metrics export is unavailable.
+
+For a Python Worker, configure the same `observability.traces` and `observability.logs` blocks and emit structured application logs through the runtime's `console`. There is no Python entry point in this npm package and no claim of Python function-level auto-instrumentation. For WebAssembly, native tracing observes the Worker invocation and Cloudflare operations around the module. Add explicit spans in the JavaScript/TypeScript host with `withCloudflareSpan` when you need timings around a Wasm call; spans inside the compiled module require that language's own workerd-compatible instrumentation.
+
+Cloudflare native tracing automatically covers handler invocations, fetch subrequests, and supported platform operations such as KV, R2, and Durable Objects. The direct JavaScript binding proxies below are a compatibility and enrichment layer; they are not required when native tracing is active.
+
 The wrapper also enters native spans for default-export queue and scheduled handlers. `withCloudflareSpan(ctx, ...)` remains native across arbitrary `await` boundaries and does not require `nodejs_compat`. `withSpan(...)` routes to the native tracer whenever its active context is available.
 
 ### Cloudflare Agents SDK
@@ -184,7 +192,7 @@ export default instrument(
     getUser: (req) => ({
       id: req.headers.get("x-user-id") ?? undefined,
     }),
-    instrumentBindings: true,  // auto-trace D1/KV/R2/Vectorize/AI/Queues/Service bindings
+    instrumentBindings: true,  // direct-mode spans for supported binding operations
   },
 );
 ```
@@ -201,7 +209,7 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`, and set `native
 > ```toml
 > compatibility_flags = ["nodejs_compat"]
 > ```
-> Without it the SDK falls back to a synchronous stack-based context manager — suppression still works, and **binding spans (D1/KV/R2/Vectorize/AI/Queue/Service) are still parented to the request's SERVER span** (they fall back to the request context explicitly, so they never orphan into their own single-span traces). What still degrades to best-effort without `nodejs_compat` is cross-`await` parenting for *outbound-fetch CLIENT spans* and *manual `withSpan` spans* — so `nodejs_compat` remains recommended for a fully-nested trace tree.
+> Without it the SDK falls back to a synchronous stack-based context manager — suppression still works, and **instrumented binding spans are still parented to the request's SERVER span** (they fall back to the request context explicitly, so they never orphan into their own single-span traces). What still degrades to best-effort without `nodejs_compat` is cross-`await` parenting for *outbound-fetch CLIENT spans* and *manual `withSpan` spans* — so `nodejs_compat` remains recommended for a fully-nested trace tree.
 
 ### `WorkersConfig` options
 
@@ -211,9 +219,9 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`, and set `native
 | `nativeTracing` | `"auto" \| "native" \| "direct"` | `auto` (default) uses Cloudflare's native tree when `ctx.tracing` exists. `direct` forces the compatibility exporter. |
 | `apiKey` | `string?` | Defaults to `env.HEYSTACK_API_KEY`. |
 | `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`. |
+| `instrumentBindings` | `boolean \| string[]` | Direct mode only. `true` = child spans for all detected supported bindings; `string[]` = only named bindings. Default `false`. See the operation matrix below. |
 | `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). |
@@ -257,7 +265,22 @@ On startup the worker fetches its configured rate from the Heystack config endpo
 - **Outbound `fetch`** — each outbound subrequest while a request span is active gets a CLIENT child span (`http.request.method`, `url.full`, `server.address`, `http.response.status_code`). A W3C `traceparent` header is injected into the subrequest so a downstream Heystack-instrumented service continues the same trace (distributed tracing across services). The exporter's own ingest POST is never traced.
 - **Queue consumers (`queue`)** — a CONSUMER span per batch, with `messaging.destination.name` (queue name) and `messaging.batch.message_count`.
 - **Scheduled handlers (`scheduled`)** — an INTERNAL span per invocation, with `controller.cron`.
-- **Binding calls** (when `instrumentBindings` is set) — a child span for every D1 query (`db.statement`), KV read/write, R2 operation, Vectorize query, Workers AI inference (`gen_ai.*` attributes including model name and token usage), Queue `.send`/`.sendBatch` (PRODUCER spans with `messaging.*` attributes), and Service binding `.fetch` calls (CLIENT spans with `traceparent` injected so calls to other Workers stitch into the same distributed trace).
+- **Binding calls** (direct mode, when `instrumentBindings` is set) — child spans for the stable operations listed below. Service binding `.fetch` calls receive a W3C `traceparent` header so another instrumented Worker can continue the trace.
+
+| Binding | Direct-mode operations covered |
+| --- | --- |
+| D1 | prepared statement `all`, `first`, `run`, `raw`; database/session `batch`; database `exec`; statements created through `withSession` |
+| KV | `get`, `getWithMetadata`, `put`, `list`, `delete` |
+| R2 | `get`, `put`, `head`, `delete`, `list`; multipart create/resume plus `uploadPart`, `complete`, `abort` |
+| Vectorize | `query`, `upsert`, `insert`, `deleteByIds`, `getByIds` |
+| Workers AI | `run`, including model and token usage when returned without consuming streams |
+| Queues producer | `send`, `sendBatch`, `metrics` |
+| Workflows | `get`, `create`, `createBatch`, `deleteBatch` |
+| Rate Limiting | `limit`; the caller's rate-limit key is deliberately not attached |
+| Analytics Engine | synchronous `writeDataPoint`; datapoint values are deliberately not attached |
+| Fetch-compatible bindings | `fetch` on Service, Browser Rendering, Assets, and other Fetcher-shaped bindings |
+
+Some bindings intentionally remain outside generic direct-mode proxying. Durable Object namespaces return arbitrary RPC stubs whose method surface is application-defined; Hyperdrive exposes a connection string and the actual calls belong to the selected database driver. Email and Pipelines both expose only a generic `send` method; Analytics SQL exposes only `query`; Media begins with a generic `input`; blindly identifying those shapes could wrap an unrelated application object. Images' chained transform handles and hosted-image handles are also not proxied. Secrets, version metadata, and static-data bindings do not perform observable operations. Use [Cloudflare native tracing](https://developers.cloudflare.com/workers/observability/traces/) where it supports the binding, instrument the database/client library, or wrap a known application operation with `withSpan`. RPC methods beyond `.fetch()` need explicit application spans because automatically proxying arbitrary properties can change RPC stub semantics.
 
 ### Client enrichment
 
@@ -273,29 +296,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**:
+
+- **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:**
+**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 +368,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 +394,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 +615,8 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.15.0`** — **direct Workers D1 session and batch coverage.** With `nativeTracing: "direct"` and `instrumentBindings` enabled, prepared D1 statements, database/session `batch`, database `exec`, and statements created through `withSession` now receive child spans. Native Cloudflare OTel remains the recommended Workers path because it preserves Cloudflare's platform trace/log tree; use direct export only where `ctx.tracing` is unavailable. No breaking changes.
+- **`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).
@@ -576,3 +648,13 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 - Short-lived processes: `initHeystack` registers `SIGTERM`/`SIGINT` handlers automatically, so the SDK flushes and shuts down before exit and you don't lose the last batch.
 
 Then run your app and make a request — traces appear in your Heystack dashboard within seconds.
+
+## Investigate with your coding agent
+
+Once telemetry is flowing, connect your coding agent to the hosted **Heystack MCP server** and it can verify the setup (`heystack_verify_setup`), investigate incidents from your traces, sessions and releases, and propose the fix in your code:
+
+```bash
+claude mcp add --transport http heystack https://mcp.heystack.dev/mcp
+```
+
+One-click links for Cursor and VS Code, commands for Codex/Gemini CLI, personal access tokens for CI, and the full tool reference are in the docs: **https://heystack.dev/docs/mcp**.

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;