@heystack/otel 0.12.0 → 0.13.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.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.
 
 ## 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 patch `fetch`, does not proxy bindings, and does not require `HEYSTACK_API_KEY` in the Worker.
+
+```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,6 +208,7 @@ 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`. |
@@ -307,9 +368,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 +545,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`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/workers-agents.d.ts

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

package/dist/workers-agents.js

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

package/dist/workers.d.ts

@@ -171,6 +171,17 @@ export interface WorkersConfig {
      * Defaults to `false` (no binding tracing). Consumed by a later task.
      */
     instrumentBindings?: boolean | string[];
+    /**
+     * Select the Workers tracing plane. `auto` (default) uses Cloudflare's native
+     * tracer when `ctx.tracing` is available and otherwise falls back to direct
+     * OTLP export. `native` prefers the platform tracer but still fails open when
+     * unavailable. `direct` always uses Heystack's fetch exporter.
+     *
+     * Native mode deliberately disables Heystack root/fetch/binding
+     * instrumentation: Cloudflare already emits those spans, and running both
+     * creates duplicate, disconnected trace trees.
+     */
+    nativeTracing?: "auto" | "native" | "direct";
     /**
      * Head-sampling configuration. When omitted (or `rate` >= 1), all traces are
      * kept. When `rate` < 1, a deterministic FNV-1a hash of the trace ID decides
@@ -206,6 +217,17 @@ export interface WorkersConfig {
         maxContentChars?: number;
     };
 }
+/** Minimal public surface exposed by Cloudflare's Workers custom-spans API. */
+export interface CloudflareNativeSpan {
+    readonly isTraced: boolean;
+    setAttribute(key: string, value: string | number | boolean | undefined): void;
+    end(): void;
+}
+/** `ExecutionContext.tracing` without importing the `cloudflare:workers` module. */
+export interface CloudflareNativeTracing {
+    enterSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
+    startActiveSpan<T>(name: string, callback: (span: CloudflareNativeSpan) => T): T;
+}
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
  * flush paths can drain its in-flight fetches directly (the OTel processor's
@@ -388,6 +410,14 @@ export declare function instrument<H extends WorkerHandler<any>>(handler: H, con
  */
 export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
 export declare function withSpan<T>(name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
+/**
+ * Create a Cloudflare-native custom span using an explicit ExecutionContext.
+ * Prefer this form in code that calls `withSpan` after an `await` on a Worker
+ * without `nodejs_compat`: the explicit context cannot be lost across async
+ * boundaries. It falls back to the regular OTel tracer outside Cloudflare.
+ */
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+export declare function withCloudflareSpan<T>(ctx: ExecutionContext | CloudflareNativeTracing, name: string, attrs: Record<string, string | number | boolean>, fn: (span: Span) => T | Promise<T>): Promise<T>;
 /**
  * Add a named event (with optional attributes) to the currently-active span.
  * No-op when no span is active.

package/dist/workers.js

@@ -7,7 +7,7 @@
 // `@opentelemetry/resources` and the platform `fetch` — all WinterCG-safe — and
 // ships its own OTLP/JSON-over-fetch span exporter so it runs on Workers/Edge
 // where the Node SDK cannot.
-import { context, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
+import { context, createContextKey, INVALID_SPAN_CONTEXT, trace, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
 import { suppressTracing, isTracingSuppressed } from "@opentelemetry/core";
 import { ROOT_CONTEXT } from "@opentelemetry/api";
 import { Resource } from "@opentelemetry/resources";
@@ -563,6 +563,115 @@ 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);
+}
+/**
+ * Adapts Cloudflare's deliberately-small Span API to the OTel API shape used by
+ * `withSpan`. Unsupported OTel operations degrade to attributes instead of
+ * creating a second exporter/provider.
+ */
+class NativeSpanAdapter {
+    nativeSpan;
+    autoEnd;
+    constructor(nativeSpan, autoEnd) {
+        this.nativeSpan = nativeSpan;
+        this.autoEnd = autoEnd;
+    }
+    spanContext() { return INVALID_SPAN_CONTEXT; }
+    setAttribute(key, value) {
+        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));
+        }
+        return this;
+    }
+    setAttributes(attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined)
+                this.setAttribute(key, value);
+        }
+        return this;
+    }
+    addEvent(name, attributesOrStartTime) {
+        const prefix = `event.${name}`;
+        this.nativeSpan.setAttribute(prefix, true);
+        if (attributesOrStartTime && !Array.isArray(attributesOrStartTime) && typeof attributesOrStartTime === "object") {
+            for (const [key, value] of Object.entries(attributesOrStartTime)) {
+                if (value !== undefined)
+                    this.setAttribute(`${prefix}.${key}`, value);
+            }
+        }
+        return this;
+    }
+    addLink(_link) { return this; }
+    addLinks(_links) { return this; }
+    setStatus(status) {
+        if (status.code === SpanStatusCode.ERROR) {
+            this.nativeSpan.setAttribute("error.type", "error");
+            if (status.message)
+                this.nativeSpan.setAttribute("error.message", status.message);
+        }
+        return this;
+    }
+    updateName(_name) { return this; }
+    end(_endTime) {
+        if (!this.autoEnd)
+            this.nativeSpan.end();
+    }
+    isRecording() { return this.nativeSpan.isTraced; }
+    recordException(exception, _time) {
+        const error = exception instanceof Error ? exception : new Error(String(exception));
+        this.nativeSpan.setAttribute("error.type", error.name || "Error");
+        this.nativeSpan.setAttribute("error.message", error.message);
+        if (error.stack)
+            this.nativeSpan.setAttribute("exception.stacktrace", error.stack);
+    }
+}
+function getNativeTracing(ctx) {
+    const candidate = ctx.tracing;
+    return candidate && typeof candidate.enterSpan === "function" ? candidate : undefined;
+}
+function setNativeRequestAttributes(span, config, req) {
+    const url = new URL(req.url);
+    span.setAttribute("service.name", config.service);
+    span.setAttribute("http.route", url.pathname);
+    if (config.version)
+        span.setAttribute("service.version", config.version);
+    if (config.build)
+        span.setAttribute("service.build", config.build);
+    const userInfo = config.getUser?.(req);
+    if (userInfo?.id)
+        span.setAttribute("enduser.id", userInfo.id);
+    if (userInfo?.session)
+        span.setAttribute("session.id", userInfo.session);
+    const requestId = userInfo?.requestId ?? req.headers.get("cf-ray") ?? undefined;
+    if (requestId)
+        span.setAttribute("http.request.id", requestId);
+}
+async function runNativeSpan(nativeTracing, name, attrs, fn) {
+    ensureContextManager();
+    return nativeTracing.enterSpan(name, async (nativeSpan) => {
+        const adapter = new NativeSpanAdapter(nativeSpan, true);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value !== undefined)
+                adapter.setAttribute(key, value);
+        }
+        const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
+        try {
+            return await context.with(nativeContext, () => fn(adapter));
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            adapter.recordException(err);
+            adapter.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+            throw error;
+        }
+    });
+}
 /**
  * Build a `BasicTracerProvider` wired to a `HeystackSpanExporter` via a
  * `SimpleSpanProcessor`. Exposed for advanced users who want to add manual
@@ -824,6 +933,20 @@ export function instrument(handler, config) {
     const originalFetch = handler.fetch?.bind(handler);
     if (originalFetch) {
         wrapped.fetch = async (req, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                // `withSpan()` discovers the request's native tracer through OTel
+                // context. Register our WinterCG-safe manager even though native mode
+                // intentionally does not create an OTel provider/exporter.
+                return runNativeSpan(nativeTracing, "heystack.request", {}, async (adapter) => {
+                    setNativeRequestAttributes(adapter, config, req);
+                    const response = await originalFetch(req, env, ctx);
+                    adapter.setAttribute("http.response.status_code", response.status);
+                    if (response.status >= 500)
+                        adapter.setAttribute("error.type", "http_error");
+                    return response;
+                });
+            }
             const s = setup(env);
             if (!s)
                 return originalFetch(req, env, ctx);
@@ -998,6 +1121,17 @@ export function instrument(handler, config) {
     const originalQueue = handler.queue?.bind(handler);
     if (originalQueue) {
         wrapped.queue = async (batch, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                return runNativeSpan(nativeTracing, `heystack.queue ${batch.queue}`, {
+                    "service.name": config.service,
+                    "messaging.batch.message_count": batch.messages.length,
+                    "messaging.destination.name": batch.queue,
+                    "messaging.operation.type": "process",
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalQueue(batch, env, ctx));
+            }
             const s = setup(env);
             if (!s)
                 return originalQueue(batch, env, ctx);
@@ -1030,6 +1164,16 @@ export function instrument(handler, config) {
     const originalScheduled = handler.scheduled?.bind(handler);
     if (originalScheduled) {
         wrapped.scheduled = async (controller, env, ctx) => {
+            const nativeTracing = config.nativeTracing === "direct" ? undefined : getNativeTracing(ctx);
+            if (nativeTracing) {
+                return runNativeSpan(nativeTracing, `heystack.scheduled ${controller.cron}`, {
+                    "service.name": config.service,
+                    "faas.trigger": "timer",
+                    "cloudflare.scheduled.cron": controller.cron,
+                    "service.version": config.version,
+                    "service.build": config.build,
+                }, () => originalScheduled(controller, env, ctx));
+            }
             const s = setup(env);
             if (!s)
                 return originalScheduled(controller, env, ctx);
@@ -1063,6 +1207,23 @@ export function instrument(handler, config) {
 export async function withSpan(name, attrsOrFn, maybeFn) {
     const attrs = typeof attrsOrFn === "function" ? undefined : attrsOrFn;
     const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
+    const nativeTracing = nativeTracingFromContext();
+    if (nativeTracing) {
+        return nativeTracing.enterSpan(name, async (nativeSpan) => {
+            const adapter = new NativeSpanAdapter(nativeSpan, true);
+            if (attrs)
+                adapter.setAttributes(attrs);
+            const nativeContext = trace.setSpan(context.active().setValue(NATIVE_TRACING_CONTEXT_KEY, nativeTracing), adapter);
+            try {
+                return await context.with(nativeContext, () => fn(adapter));
+            }
+            catch (err) {
+                adapter.recordException(err instanceof Error ? err : new Error(String(err)));
+                adapter.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
+        });
+    }
     const tracer = trace.getTracer("heystack");
     const span = tracer.startSpan(name, attrs ? { attributes: attrs } : undefined);
     const ctx = trace.setSpan(context.active(), span);
@@ -1078,6 +1239,14 @@ export async function withSpan(name, attrsOrFn, maybeFn) {
         span.end();
     }
 }
+export async function withCloudflareSpan(ctx, name, attrsOrFn, maybeFn) {
+    const attrs = typeof attrsOrFn === "function" ? {} : attrsOrFn;
+    const fn = (typeof attrsOrFn === "function" ? attrsOrFn : maybeFn);
+    const tracing = "enterSpan" in ctx ? ctx : getNativeTracing(ctx);
+    if (tracing)
+        return runNativeSpan(tracing, name, attrs, fn);
+    return withSpan(name, attrs, fn);
+}
 /**
  * Add a named event (with optional attributes) to the currently-active span.
  * No-op when no span is active.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heystack/otel",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Runtime-aware OpenTelemetry tracing that exports to Heystack (Node, Next.js, Workers).",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,10 @@
       "types": "./dist/workers.d.ts",
       "import": "./dist/workers.js"
     },
+    "./workers/agents": {
+      "types": "./dist/workers-agents.d.ts",
+      "import": "./dist/workers-agents.js"
+    },
     "./web": {
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js"