@heystack/otel 0.11.1 → 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:
 
@@ -400,6 +461,8 @@ await instrumentWeb({
 
 Otherwise it's **cost-aware and safe by design**: off unless you opt in; head-sampled (an unsampled request still propagates `traceparent` with the sampled flag cleared, so the backend makes the same keep/drop decision — no orphaned server spans); and the exporter posts through the *original* `fetch`, never tracing its own upload (no self-export loop). Spans post to `/v1/traces` cross-origin with no CORS setup on your side.
 
+**Remote kill-switch (safety valve).** Browser tracing can also be disabled **from the server**, without an app redeploy — a way to stop it fleet-wide if it ever misbehaves in the wild. It is **fail-open**: if the server config is unreachable or omits the flag, tracing stays on (absent flag = enabled), so the switch can only ever *disable*, never accidentally turn a working app off.
+
 ### Browser error & console collection
 
 `instrumentWeb` captures **uncaught browser errors** out of the box — no extra setup. Any `window.onerror` / unhandled promise rejection becomes an OTLP **log** (`event.name=browser.error`, `ERROR` severity) carrying the OTel `exception.type` / `exception.message` / `exception.stacktrace` semconv attributes, the page `url.full`, the `session_id` (so it correlates to the session replay), and — when `tracing` is on — the active `trace_id` / `span_id`. `console.error` is captured too by default.
@@ -417,6 +480,8 @@ await instrumentWeb({
 
 It's the **same cost-safe design** as tracing/replay: logs POST to `/v1/logs` through the *original* `fetch` (captured before any patching) so the exporter never traces its own upload — no self-export loop. Console capture is **recursion-guarded** (anything logged on the export path is never re-captured) and **rate-capped** (max ~60 records/minute; the overflow is dropped and counted, with one summary log emitted when the cap lifts) so a runaway `console.error` in a render loop can't flood ingest. Errors show up in the console **Logs** tab and correlate to their session replay and trace.
 
+Like tracing, error / console capture has a **remote kill-switch**: it can be disabled **from the server** without an app redeploy, and is **fail-open** (if the server config is unreachable or omits the flag, capture stays on — absent flag = enabled).
+
 ### In-app bug reports (`reportBug`)
 
 Let users report a bug from inside your app. `reportBug` is a headless API — **no widget, you own the UX** — that files a structured report and auto-attaches the context a triager needs: the current URL, user agent, replay `session_id`, active `trace_id`, `release` / `build`, and the **last few captured browser errors** (so you see what was going wrong on the page right before the report). The report also appears on the Logs timeline (`event.name=user.bug_report`).
@@ -480,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/web.d.ts

@@ -17,6 +17,19 @@ export interface RecorderConfig {
     enabled: boolean;
     sample_rate: number;
     masking_mode: "strict" | "relaxed";
+    /**
+     * Server-side kill-switch for browser distributed tracing. Absent/`true` = enabled
+     * (**fail-open**); set `false` server-side to remotely disable browser tracing
+     * WITHOUT an app redeploy — the safety valve for the 2026-07-03 cross-origin
+     * `traceparent` outage. See `tracingActive`.
+     */
+    tracing_enabled?: boolean;
+    /**
+     * Server-side kill-switch for browser error / console capture. Absent/`true` =
+     * enabled (**fail-open**); set `false` server-side to remotely disable it without
+     * an app redeploy. See `errorCaptureActive`.
+     */
+    errors_enabled?: boolean;
 }
 /** Pure: decide once per session whether to record. rng defaults to Math.random. */
 export declare function shouldRecord(cfg: RecorderConfig, rng?: () => number): boolean;
@@ -116,6 +129,21 @@ export interface InstrumentWebOptions {
      */
     captureConsole?: "error" | "warn" | false;
 }
+/**
+ * Pure: is browser distributed tracing active for this run? Requires BOTH the app
+ * to have opted in (`opts.tracing`) AND the server-side kill-switch to not be off
+ * (`cfg.tracing_enabled`). **Fail-open**: an absent/`true` flag counts as enabled, so
+ * an old or unreachable `/v1/replay/config` never silently disables tracing. Split out
+ * as a tiny exported predicate so the gating decision is unit-testable without booting
+ * rrweb (which `instrumentWeb` imports). See `RecorderConfig.tracing_enabled`.
+ */
+export declare function tracingActive(opts: Pick<InstrumentWebOptions, "tracing">, cfg: Pick<RecorderConfig, "tracing_enabled">): boolean;
+/**
+ * Pure: is browser error / console capture active for this run? On by default
+ * (`opts.errors !== false`) AND gated by the server-side kill-switch
+ * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
+ */
+export declare function errorCaptureActive(opts: Pick<InstrumentWebOptions, "errors">, cfg: Pick<RecorderConfig, "errors_enabled">): boolean;
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export declare function instrumentWeb(opts: InstrumentWebOptions): Promise<() => void>;

package/dist/web.js

@@ -81,6 +81,25 @@ export class ReplayTransport {
 }
 const DEFAULT_FLUSH_MS = 5000;
 const DEFAULT_FLUSH_EVENTS = 200;
+/**
+ * Pure: is browser distributed tracing active for this run? Requires BOTH the app
+ * to have opted in (`opts.tracing`) AND the server-side kill-switch to not be off
+ * (`cfg.tracing_enabled`). **Fail-open**: an absent/`true` flag counts as enabled, so
+ * an old or unreachable `/v1/replay/config` never silently disables tracing. Split out
+ * as a tiny exported predicate so the gating decision is unit-testable without booting
+ * rrweb (which `instrumentWeb` imports). See `RecorderConfig.tracing_enabled`.
+ */
+export function tracingActive(opts, cfg) {
+    return !!opts.tracing && cfg.tracing_enabled !== false;
+}
+/**
+ * Pure: is browser error / console capture active for this run? On by default
+ * (`opts.errors !== false`) AND gated by the server-side kill-switch
+ * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
+ */
+export function errorCaptureActive(opts, cfg) {
+    return opts.errors !== false && cfg.errors_enabled !== false;
+}
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
  *  Returns a stop() function. Safe to call in any browser; no-ops on the server. */
 export async function instrumentWeb(opts) {
@@ -113,7 +132,9 @@ export async function instrumentWeb(opts) {
     //    a real CLIENT span per outbound fetch + propagates W3C context to the backend.
     let stopTracing = () => { };
     let fetchPatched = false;
-    if (opts.tracing) {
+    // Gated by the server kill-switch (cfg.tracing_enabled) as well as the app opt-in —
+    // fail-open, so an unreachable/old config can't disable tracing. See tracingActive.
+    if (tracingActive(opts, cfg)) {
         const exporter = new BrowserTraceExporter({
             endpoint, apiKey: opts.apiKey, service: opts.service, fetchImpl: originalFetch,
             resourceAttributes: releaseAttrs,
@@ -157,7 +178,9 @@ export async function instrumentWeb(opts) {
     // 2b. Browser error / console log collection — ON by default, INDEPENDENT of both
     //     tracing and replay sampling. Exports OTLP logs to /v1/logs via the original fetch.
     let stopErrors = () => { };
-    if (opts.errors !== false) {
+    // Gated by the server kill-switch (cfg.errors_enabled) as well as the opts.errors
+    // default — fail-open. See errorCaptureActive.
+    if (errorCaptureActive(opts, cfg)) {
         const unpatchErrors = startErrorCapture({
             exporter: logsExporter,
             sessionId,

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.11.1",
+  "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"