@heystack/otel 0.12.0 → 0.14.0

package/README.md

@@ -13,14 +13,15 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
-> **Requires `@heystack/otel` `>=0.3.0` (prefer `>=0.3.2`).** 0.3.2 fixes the no-op `suppressTracing` (feedback-loop guard) on the Workers/Next-on-OpenNext path and adds the Workers `nodejs_compat` requirement. 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
 
 | Runtime | Import | Notes |
 | --- | --- | --- |
 | 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` | `instrument()` wraps your handler. Fetch-based exporter, flushes via `ctx.waitUntil`. |
+| Standalone Cloudflare Workers (hand-written `export default { fetch }`) | `@heystack/otel/workers` | Native-first `instrument()` wrapper; Cloudflare owns OTLP export and automatic platform spans. |
+| 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). |
 | Anywhere (pure helpers) | `@heystack/otel` | `buildExporterConfig`, types. No Node SDK loaded. |
@@ -108,6 +109,64 @@ export async function register() {
 
 ## Standalone Cloudflare Workers
 
+### Preferred: Cloudflare-native OTel export
+
+Create separate `heystack-traces` and `heystack-logs` OTLP destinations in Cloudflare's Workers Observability dashboard. Use `https://ingest.heystack.dev/v1/traces` and `/v1/logs`, each with `Authorization: Bearer <ingest-key>`, then configure:
+
+```toml
+[observability.traces]
+enabled = true
+destinations = ["heystack-traces"]
+head_sampling_rate = 1
+persist = false
+
+[observability.logs]
+enabled = true
+destinations = ["heystack-logs"]
+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 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";
+
+const worker = {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return withCloudflareSpan(ctx, "order.load", { "order.id": "o1" }, async () => {
+      return Response.json(await env.DB.prepare("SELECT 1").first());
+    });
+  },
+};
+
+export default instrument(worker, {
+  service: "my-worker",
+  nativeTracing: "auto", // default
+  getUser: (request) => ({ id: request.headers.get("x-user-id") ?? undefined }),
+});
+```
+
+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
+
+```ts
+import { Agent } from "agents";
+import { createCloudflareAgentsObservability } from "@heystack/otel/workers/agents";
+
+const observability = createCloudflareAgentsObservability();
+export class SupportAgent extends Agent<Env> {
+  override observability = observability;
+}
+```
+
+Every Agents SDK RPC, state, message/tool, chat/recovery, fiber, scheduling, lifecycle, workflow, MCP, and email event becomes a structured, trace-correlated native log. Common secret and content fields are redacted. For production diagnostics channels, attach a Tail Worker using `createCloudflareAgentsTailHandler()` and enable the same native log destination on it.
+
+### Direct OTLP fallback (non-native runtimes only)
+
+Set `nativeTracing: "direct"` only when `ctx.tracing` and Cloudflare native export are unavailable. The remainder of this section describes that compatibility path. It requires `wrangler secret put HEYSTACK_API_KEY`; do not run it alongside a native trace destination because that creates duplicate trace trees.
+
 For a hand-written Worker (`export default { fetch }`), wrap the handler with `instrument()`:
 
 ```ts
@@ -121,6 +180,7 @@ export default instrument(
   },
   {
     service: "my-worker",      // apiKey defaults to env.HEYSTACK_API_KEY
+    nativeTracing: "direct",    // compatibility fallback only
     getUser: (req) => ({
       id: req.headers.get("x-user-id") ?? undefined,
     }),
@@ -135,9 +195,9 @@ export default instrument(
 export default instrument(withOtherMiddleware(worker), { service: "my-worker" });
 ```
 
-Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
+Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`, and set `nativeTracing: "direct"` in the config.
 
-> **Requires `nodejs_compat` on workerd.** The SDK uses `AsyncLocalStorage` for per-request context isolation. Add to `wrangler.toml`:
+> **Direct mode requires `nodejs_compat` on workerd.** The direct SDK uses `AsyncLocalStorage` for per-request context isolation. Native mode does not require it. Add to `wrangler.toml`:
 > ```toml
 > compatibility_flags = ["nodejs_compat"]
 > ```
@@ -148,11 +208,12 @@ Set the key as a secret: `wrangler secret put HEYSTACK_API_KEY`.
 | Option | Type | Notes |
 | --- | --- | --- |
 | `service` | `string` | **Required.** Service name that appears in the Heystack console. |
+| `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`. |
 | `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). |
@@ -212,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):**
 
@@ -263,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.
 
@@ -288,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.
@@ -307,9 +415,9 @@ inbound W3C `traceparent` (so a client request and the server handler share one
 trace) and returns a `traceparent` response header — plus
 `Access-Control-Expose-Headers: traceparent` so browser clients can read it.
 
-### Durable Objects are NOT covered by `instrument()`
+### Durable Objects in direct fallback mode
 
-`instrument()` wraps the keys of the **default-export handler object** (`fetch`/`queue`/`scheduled`/… ). **Durable Objects are separate named class exports**, so spreading the handler object does not touch them — a DO's `fetch`/`alarm` methods run **untraced** even when your Worker's default export is wrapped.
+Cloudflare native tracing covers Durable Objects and their platform operations. The limitation below applies only to the direct exporter fallback: `instrument()` wraps the keys of the **default-export handler object** (`fetch`/`queue`/`scheduled`/… ), while Durable Objects are separate named class exports.
 
 To trace a Durable Object, instrument it manually with the global tracer (which `instrument()` / `initHeystackWorkers()` already registered) and flush per invocation:
 
@@ -484,6 +592,8 @@ 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).
 - **`0.9.2`** — **`/workers`: `instrument()` no longer breaks WebSocket / Durable Object upgrades.** The fetch wrapper rebuilt every response with `new Response(...)`, which **drops the `webSocket` property** on a `101 Switching Protocols` upgrade — so every WebSocket connection on an instrumented Worker failed *whenever tracing was active* (an API key set), while passing in dev/staging where `instrument()` is a passthrough. `instrument()` now detects an upgrade (`response.webSocket` present, or `status === 101`) and returns the **original response untouched** (span closed immediately; no `traceparent` header injected — headers on a 101 aren't delivered anyway). Fixes failed `wss://` connections behind `routeAgentRequest` / any `new WebSocketPair()` handler. No API change; upgrade and redeploy.

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;