@heystack/otel 0.15.0 → 0.16.0

package/README.md

@@ -13,7 +13,7 @@ Always read your key from the environment — never paste it into source:
 HEYSTACK_API_KEY=sk_live_…
 ```
 
-> **Use `@heystack/otel` `>=0.15.0`.** 0.15 extends direct Workers instrumentation to D1 sessions and batches. Cloudflare native OTel remains the preferred path for Workers; direct SDK export is a compatibility fallback when native tracing is unavailable. See [Migration](#migration--versioning) below.
+> **Use `@heystack/otel` `>=0.16.0`.** 0.16 extends direct Workers instrumentation to Durable Objects, Workflows, and the remaining Worker lifecycle entry points while preserving host-object return semantics. Cloudflare native OTel remains the preferred path for Workers; direct SDK export is a compatibility fallback when native tracing is unavailable. See [Migration](#migration--versioning) below.
 
 ## Runtime matrix
 
@@ -615,6 +615,7 @@ As belt-and-suspenders the exporter also drops any span whose HTTP target points
 
 ## Migration / versioning
 
+- **`0.16.0`** — **complete direct Workers lifecycle and binding coverage.** Durable Object namespace stubs now trace `fetch` and RPC calls with W3C trace propagation; Workflow bindings trace creation, batch creation, lookup, instance lifecycle methods, and deletion operations. Direct instrumentation also covers scheduled, queue, email, Tail Worker, and related Worker entry points, while preserving synchronous values, native promises, custom thenables, upgrade responses, host-object identity, and callback-scoped native span ownership. Service-binding propagation now respects caller-supplied request headers. No breaking changes.
 - **`0.15.0`** — **direct Workers D1 session and batch coverage.** With `nativeTracing: "direct"` and `instrumentBindings` enabled, prepared D1 statements, database/session `batch`, database `exec`, and statements created through `withSession` now receive child spans. Native Cloudflare OTel remains the recommended Workers path because it preserves Cloudflare's platform trace/log tree; use direct export only where `ctx.tracing` is unavailable. No breaking changes.
 - **`0.14.0`** — **gen_ai enrichment under Cloudflare native tracing, Mistral + AI-gateway detection, streaming usage; OpenTelemetry JS SDK 2.x.** (1) `/workers`: under `nativeTracing: "auto" | "native"` `instrument()` never installed the fetch wrapper, so native-mode Workers emitted **no** `gen_ai.*` telemetry. It now installs a lean LLM-only wrapper that opens a native `<operation> <provider>` span (e.g. `chat mistral`) with request/response `gen_ai.*` for detected providers and passes every other subrequest through untouched. (2) New provider **Mistral** (`api.mistral.ai`) and a new `ai.gateways` option (`[{ hostSuffix, pathPattern }]`, e.g. `{ hostSuffix: "wafersecurity.ai", pathPattern: "/p/:tenant/:provider" }`) that resolves the provider from an AI-gateway URL and stamps `heystack.ai.gateway`; `gemini` → `google`, `workers-ai` → `cloudflare`. New `gen_ai.operation.name`. (3) **Streaming (`text/event-stream`) responses now yield usage**: the body is `tee()`d and scanned line-by-line for `usage`/`usageMetadata`, model, id and finish reason only (never content); the span stays open until the stream closes. Google (`usageMetadata`) and Mistral response shapes added to the JSON path too. (4) New `/workers` exports `genAiRequestAttrs` / `genAiResponseAttrs` for manual `withSpan` spans around `env.AI.run` or any non-`fetch` LLM call. Native `error.type` now keeps the exception class instead of being overwritten with `error`. (5) All `@opentelemetry/*` dependencies move to the 2.x SDK line (`core`/`sdk-trace-base`/`resources` ^2.11, `sdk-node`/`exporter-trace-otlp-http` ^0.222, `auto-instrumentations-node` ^0.80, `semantic-conventions` ^1.43), clearing the downstream Dependabot alerts the 1.x line surfaced through this package (GHSA-8988-4f7v-96qf in `@opentelemetry/core`, GHSA-q7rr-3cgh-j5r3 in `sdk-node` / `auto-instrumentations-node` / `exporter-prometheus`, GHSA-45rx-2jwx-cxfr in `propagator-jaeger`). **Node ≥ 18.19 (or ≥ 20.6) is now required on `/node` and `/next`** — the 2.x SDK dropped Node 14/16. If you pass your own `instrumentations` array to `initHeystack`, upgrade those `@opentelemetry/instrumentation-*` packages to a release that peers on `@opentelemetry/core@^2` (the auto-instrumentations 0.80 set already does). `/workers` is still WinterCG-safe (no `node:*` imports). No other API changes; all new options are optional.
 - **`0.13.0`** — **Cloudflare-native tracing and complete Workers platform coverage.** On runtimes exposing `ctx.tracing`, `/workers` now joins Cloudflare's authoritative invocation trace instead of creating and exporting a duplicate tree. `nativeTracing: "auto"` is the default; `withCloudflareSpan(ctx, ...)` adds async-safe business spans, while fetch, queue, and scheduled handlers are enriched in the native tree. The new `/workers/agents` entry maps Cloudflare Agents observability callbacks and Tail Worker diagnostics to structured, redacted telemetry. Direct OTLP remains available with `nativeTracing: "direct"` for runtimes without the native API. Heystack ingest now preserves full OTLP trace/log fidelity, accepts OTLP metrics, and can import Workers Analytics metrics through the app-scoped Cloudflare connector. Native mode needs no Worker API-key secret and must not be combined with direct export.

package/dist/traceparent.d.ts

@@ -0,0 +1,8 @@
+interface TraceparentSpanContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: number;
+}
+/** Encode a span context as W3C traceparent, preserving the low flags byte. */
+export declare function makeTraceparent(context: TraceparentSpanContext): string;
+export {};

package/dist/traceparent.js

@@ -0,0 +1,5 @@
+/** Encode a span context as W3C traceparent, preserving the low flags byte. */
+export function makeTraceparent(context) {
+    const flags = (context.traceFlags & 0xff).toString(16).padStart(2, "0");
+    return `00-${context.traceId}-${context.spanId}-${flags}`;
+}

package/dist/workers-agents.d.ts

@@ -1,5 +1,5 @@
 import { type Span } from "@opentelemetry/api";
-import { type CloudflareNativeTracing } from "./workers";
+import { type CloudflareNativeTracing } from "./workers.js";
 /** Structural equivalent of the Agents SDK event; no `agents` peer required. */
 export interface CloudflareAgentEvent {
     type: string;

package/dist/workers-agents.js

@@ -1,5 +1,5 @@
 import { trace } from "@opentelemetry/api";
-import { withCloudflareSpan, } from "./workers";
+import { withCloudflareSpan, } from "./workers.js";
 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) {

package/dist/workers-bindings.d.ts

@@ -10,11 +10,19 @@ export interface InstrumentBindingsOpts {
      */
     startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
     /**
-     * `true`  → auto-detect and wrap all supported Cloudflare bindings.
+     * `true`  → auto-detect and wrap every supported Cloudflare binding.
      * `string[]` → only wrap bindings whose env key is listed.
      */
     select: boolean | string[];
 }
+/**
+ * Run `fn`, ending `span` in `finally` and recording exceptions + ERROR status
+ * on failure (re-throwing). Internal helper shared with the class-level
+ * wrappers in workers.ts.
+ */
+export declare function runWithSpan<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+/** Internal proxy builder shared with the class-level wrappers in workers.ts. */
+export declare function makeProxy(target: any, handlers: Record<string, Function>): any;
 /**
  * Build a new args array for `fetch(input, init?)` with a `traceparent` header
  * injected WITHOUT mutating the caller's original Request or init object.
@@ -37,6 +45,8 @@ export declare function injectTraceparentArgs(args: any[], traceparent: string):
  * - Workflow: `get`+`create`+`createBatch`
  * - Rate limit: `limit`
  * - Analytics Engine: `writeDataPoint`
+ * - Durable Object namespace: `idFromName`+`get`+`newUniqueId` (stub fetch/RPC spans)
+ * - Workflow binding: `create`+`createBatch`+`get` and not a DO namespace
  * - Service binding / Fetcher: `fetch` (last branch; most generic)
  *
  * Unrecognised bindings are passed through unchanged.

package/dist/workers-bindings.js

@@ -1,14 +1,15 @@
 // ---------------------------------------------------------------------------
 // Cloudflare binding instrumentation for @heystack/otel/workers.
 //
-// Wraps stable Cloudflare binding APIs with OTel child spans so that binding
-// operations are visible as children of the active request span.
+// Wraps supported Cloudflare data, AI, messaging, Durable Object, Workflow,
+// and Service binding operations with OTel child spans.
 //
-// WinterCG-safe: no `node:*` imports. Span factory is injected so the logic
+// WinterCG-safe: no Node-builtin imports. Span factory is injected so the logic
 // is pure and unit-testable without a global provider.
 // ---------------------------------------------------------------------------
 import { context, SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { isTracingSuppressed } from "@opentelemetry/core";
+import { makeTraceparent } from "./traceparent.js";
 // ---------------------------------------------------------------------------
 // Duck-type detectors — conservative; require the distinctive method set
 // exactly as documented in the task brief.
@@ -63,7 +64,12 @@ function isServiceLike(b) {
 // ---------------------------------------------------------------------------
 // Span lifecycle helper
 // ---------------------------------------------------------------------------
-async function runWithSpan(span, fn) {
+/**
+ * Run `fn`, ending `span` in `finally` and recording exceptions + ERROR status
+ * on failure (re-throwing). Internal helper shared with the class-level
+ * wrappers in workers.ts.
+ */
+export async function runWithSpan(span, fn) {
     try {
         return await fn();
     }
@@ -95,11 +101,80 @@ function runSyncWithSpan(span, fn) {
         span.end();
     }
 }
+function isPromiseLike(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function recordSpanError(span, error) {
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+    });
+}
+/** Trace a call without replacing synchronous, Promise, or custom thenable results. */
+function runWithSpanPreservingReturn(span, fn) {
+    try {
+        const result = fn();
+        if (isPromiseLike(result)) {
+            let settled = false;
+            const finish = (error, failed = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (failed) {
+                    try {
+                        recordSpanError(span, error);
+                    }
+                    catch {
+                        // Instrumentation must not alter the observed thenable's behaviour.
+                    }
+                }
+                try {
+                    span.end();
+                }
+                catch {
+                    // Instrumentation must not alter the observed thenable's behaviour.
+                }
+            };
+            try {
+                const observer = result.then(() => finish(), (error) => finish(error, true));
+                // A non-compliant custom thenable may reject the observer despite the
+                // rejection callback above. Consume that rejection without replacing
+                // or awaiting the original RPC/Promise object returned to the caller.
+                if (isPromiseLike(observer)) {
+                    try {
+                        observer.then(undefined, () => undefined);
+                    }
+                    catch {
+                        // Calling then() is best-effort for exotic host thenables.
+                    }
+                }
+            }
+            catch (error) {
+                finish(error, true);
+            }
+            return result;
+        }
+        span.end();
+        return result;
+    }
+    catch (error) {
+        recordSpanError(span, error);
+        span.end();
+        throw error;
+    }
+}
+/** Transform either a synchronous result or a promise without changing its category. */
+function mapReturn(result, map) {
+    return isPromiseLike(result) ? Promise.resolve(result).then(map) : map(result);
+}
 // ---------------------------------------------------------------------------
 // Proxy helper — intercepts listed handlers, falls through to prototype for rest
 // ---------------------------------------------------------------------------
 const rawTarget = Symbol("heystack.rawBindingTarget");
-function makeProxy(target, handlers) {
+/** Internal proxy builder shared with the class-level wrappers in workers.ts. */
+export function makeProxy(target, handlers) {
     return new Proxy(target, {
         get(t, prop, receiver) {
             if (prop === rawTarget)
@@ -455,6 +530,14 @@ function wrapAnalyticsEngine(binding, opts, name) {
 export function injectTraceparentArgs(args, traceparent) {
     const [input, ...rest] = args;
     if (input instanceof Request) {
+        const originalInit = rest[0];
+        if (originalInit?.headers !== undefined) {
+            const init = { ...originalInit };
+            const headers = new Headers(originalInit.headers);
+            headers.set("traceparent", traceparent);
+            init.headers = headers;
+            return [input, init, ...rest.slice(1)];
+        }
         const headers = new Headers(input.headers);
         headers.set("traceparent", traceparent);
         return [new Request(input, { headers }), ...rest];
@@ -474,13 +557,202 @@ function wrapService(binding, opts, name) {
             }
             const span = opts.startSpan(`Service ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
             const sc = span.spanContext();
-            const traceparent = `00-${sc.traceId}-${sc.spanId}-01`;
+            const traceparent = makeTraceparent(sc);
             const injectedArgs = injectTraceparentArgs(args, traceparent);
             return runWithSpan(span, () => binding.fetch(...injectedArgs));
         },
     });
 }
 // ---------------------------------------------------------------------------
+// Durable Object namespace binding
+// ---------------------------------------------------------------------------
+/** DO namespace detector using the real synchronous Cloudflare API surface. */
+function isDurableObjectNamespaceLike(b) {
+    return (typeof b?.idFromName === "function" &&
+        typeof b?.get === "function" &&
+        typeof b?.newUniqueId === "function");
+}
+/** Fetcher/DO members that are platform operations or must retain host semantics. */
+const DO_STUB_RPC_EXCLUDED = new Set([
+    "fetch",
+    "connect",
+    "alarm",
+    "webSocketMessage",
+    "webSocketClose",
+    "webSocketError",
+    "id",
+    "name",
+    "dup",
+    "constructor",
+    "then",
+]);
+/** Wrap a DO stub: CLIENT spans on fetch (+ traceparent injection) and RPC calls. */
+function wrapDurableObjectStub(stub, opts, name) {
+    const fetch = (...args) => {
+        if (isTracingSuppressed(context.active()))
+            return stub.fetch(...args);
+        const span = opts.startSpan(`DO ${name} fetch`, { "peer.service": name }, SpanKind.CLIENT);
+        const sc = span.spanContext();
+        // Propagate into the DO so its own spans join this trace.
+        const injectedArgs = injectTraceparentArgs(args, makeTraceparent(sc));
+        return runWithSpanPreservingReturn(span, () => stub.fetch(...injectedArgs));
+    };
+    // workerd exposes RPC methods through a wildcard property hook, so method
+    // names are not enumerable. Resolve and wrap them lazily on first access.
+    const rpcMethods = new Map();
+    return new Proxy(stub, {
+        get(target, property) {
+            if (property === "fetch")
+                return fetch;
+            const value = Reflect.get(target, property, target);
+            if (typeof property !== "string" ||
+                typeof value !== "function" ||
+                DO_STUB_RPC_EXCLUDED.has(property) ||
+                property in Object.prototype) {
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+            const cached = rpcMethods.get(property);
+            if (cached)
+                return cached;
+            // Capture the host callable returned for this property. Calling it with
+            // the original stub as receiver preserves both ordinary and workerd RPC
+            // method semantics; the wrapper itself remains stable across reads.
+            const method = value;
+            const wrapped = (...args) => {
+                if (isTracingSuppressed(context.active())) {
+                    return Reflect.apply(method, target, args);
+                }
+                const span = opts.startSpan(`DO ${name} ${property}`, { "peer.service": name, "rpc.method": property }, SpanKind.CLIENT);
+                return runWithSpanPreservingReturn(span, () => Reflect.apply(method, target, args));
+            };
+            rpcMethods.set(property, wrapped);
+            return wrapped;
+        },
+    });
+}
+function wrapDurableObjectNamespace(ns, opts, name) {
+    const handlers = {
+        // Namespace lookup is local and synchronous. Trace the returned stub's
+        // actual fetch/RPC calls, not get() itself.
+        get: (...args) => wrapDurableObjectStub(ns.get(...args), opts, name),
+    };
+    if (typeof ns.getByName === "function") {
+        handlers.getByName = (...args) => wrapDurableObjectStub(ns.getByName(...args), opts, name);
+    }
+    if (typeof ns.jurisdiction === "function") {
+        handlers.jurisdiction = (...args) => wrapDurableObjectNamespace(ns.jurisdiction(...args), opts, name);
+    }
+    // idFromName/idFromString/newUniqueId are synchronous local operations and
+    // fall through untouched.
+    return makeProxy(ns, handlers);
+}
+// ---------------------------------------------------------------------------
+// Workflows binding wrapper
+// ---------------------------------------------------------------------------
+/** Workflow binding: exposes create/createBatch/get and is not a DO namespace. */
+function isWorkflowBindingLike(b) {
+    return (typeof b?.create === "function" &&
+        typeof b?.createBatch === "function" &&
+        typeof b?.get === "function" &&
+        !isDurableObjectNamespaceLike(b));
+}
+const WORKFLOW_INSTANCE_METHODS = [
+    "pause",
+    "resume",
+    "terminate",
+    "restart",
+    "status",
+    "sendEvent",
+];
+function workflowId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value && typeof value === "object") {
+        const id = value.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return undefined;
+}
+function workflowBatchIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(workflowId).filter((id) => id !== undefined);
+}
+function wrapWorkflowInstance(instance, opts, name) {
+    if (!instance || typeof instance !== "object")
+        return instance;
+    const target = instance;
+    const handlers = {};
+    const instanceId = workflowId(instance);
+    for (const method of WORKFLOW_INSTANCE_METHODS) {
+        if (typeof target[method] !== "function")
+            continue;
+        handlers[method] = (...args) => {
+            const underlying = target[method];
+            if (isTracingSuppressed(context.active())) {
+                return underlying.apply(instance, args);
+            }
+            const attrs = {
+                "cloudflare.workflow.namespace": name,
+            };
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            const span = opts.startSpan(`Workflow ${method}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => underlying.apply(instance, args));
+        };
+    }
+    return makeProxy(instance, handlers);
+}
+function wrapWorkflowBindingResult(value, op, opts, name, span) {
+    if (op === "deleteBatch")
+        return value;
+    if (op === "createBatch") {
+        if (!Array.isArray(value))
+            return value;
+        const returnedIds = workflowBatchIds(value);
+        if (span && returnedIds.length > 0) {
+            span.setAttribute("cloudflare.workflow.instance_ids", returnedIds);
+        }
+        return value.map((item) => wrapWorkflowInstance(item, opts, name));
+    }
+    const returnedId = workflowId(value);
+    if (span && returnedId !== undefined) {
+        span.setAttribute("cloudflare.workflow.instance_id", returnedId);
+    }
+    return wrapWorkflowInstance(value, opts, name);
+}
+function wrapWorkflowBinding(binding, opts, name) {
+    const baseAttrs = {
+        "cloudflare.workflow.namespace": name,
+        "cloudflare.binding.type": "workflow",
+        "cloudflare.binding.name": name,
+    };
+    const ops = ["create", "createBatch", "get", "deleteBatch"];
+    const handlers = {};
+    for (const op of ops) {
+        handlers[op] = (...args) => {
+            if (isTracingSuppressed(context.active())) {
+                return mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name));
+            }
+            const attrs = { ...baseAttrs };
+            const instanceId = workflowId(args[0]);
+            const batchIds = op === "createBatch" || op === "deleteBatch" ? workflowBatchIds(args[0]) : [];
+            if (instanceId !== undefined) {
+                attrs["cloudflare.workflow.instance_id"] = instanceId;
+            }
+            if (batchIds.length > 0) {
+                attrs["cloudflare.workflow.instance_ids"] = batchIds;
+                attrs["cloudflare.workflow.batch.size"] = batchIds.length;
+            }
+            const span = opts.startSpan(`Workflow ${op}`, attrs, SpanKind.CLIENT);
+            return runWithSpanPreservingReturn(span, () => mapReturn(binding[op](...args), (value) => wrapWorkflowBindingResult(value, op, opts, name, span)));
+        };
+    }
+    return makeProxy(binding, handlers);
+}
+// ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
 /**
@@ -497,6 +769,8 @@ function wrapService(binding, opts, name) {
  * - Workflow: `get`+`create`+`createBatch`
  * - Rate limit: `limit`
  * - Analytics Engine: `writeDataPoint`
+ * - Durable Object namespace: `idFromName`+`get`+`newUniqueId` (stub fetch/RPC spans)
+ * - Workflow binding: `create`+`createBatch`+`get` and not a DO namespace
  * - Service binding / Fetcher: `fetch` (last branch; most generic)
  *
  * Unrecognised bindings are passed through unchanged.
@@ -538,6 +812,12 @@ export function instrumentEnv(env, opts) {
         else if (isQueueLike(binding)) {
             result[key] = wrapQueue(binding, opts, key);
         }
+        else if (isDurableObjectNamespaceLike(binding)) {
+            result[key] = wrapDurableObjectNamespace(binding, opts, key);
+        }
+        else if (isWorkflowBindingLike(binding)) {
+            result[key] = wrapWorkflowBinding(binding, opts, key);
+        }
         else if (isWorkflowLike(binding)) {
             result[key] = wrapWorkflow(binding, opts, key);
         }

package/dist/workers.d.ts

@@ -1,4 +1,4 @@
-import { type Span } from "@opentelemetry/api";
+import { SpanKind, type Span } from "@opentelemetry/api";
 import { type Context, type ContextManager } from "@opentelemetry/api";
 import { BasicTracerProvider, type ReadableSpan, type SpanExporter } from "@opentelemetry/sdk-trace-base";
 import { type HeystackOptions } from "./core.js";
@@ -92,6 +92,8 @@ export declare class HeystackSpanExporter implements SpanExporter {
     readonly ingestHost: string;
     private readonly headers;
     private shutdownState;
+    /** Exports rejected before network work because the in-flight cap was hit. */
+    droppedPending: number;
     /**
      * In-flight export fetches. Each `export()` adds its settled-when-the-POST-
      * completes promise here and removes it on `finally`. `forceFlush()` awaits
@@ -112,10 +114,21 @@ export declare class HeystackSpanExporter implements SpanExporter {
     waitUntil?: (p: Promise<unknown>) => void;
     constructor(options: HeystackOptions);
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * POST the batch with ONE bounded automatic retry for network errors / 429 /
+     * 5xx. Honours `Retry-After` (seconds form) on 429 within the total backoff
+     * cap; after retries are exhausted it preserves plain FAILED semantics via
+     * `resultCallback`. The returned promise never rejects.
+     */
+    private postWithRetry;
+    /** Reserve a tracked slot synchronously before starting any network work. */
+    private reservePending;
     /**
      * Hand `p` to the OpenNext Cloudflare request context's `ctx.waitUntil`.
      * Resolves the accessor first (awaiting its in-flight load if needed) so an
      * export that fired before the dynamic import settled is still covered.
+     * Sets `outcome.borrowed` when (and only when) a real `waitUntil` received
+     * `p` — the signal the no-handoff advisory keys off.
      */
     private handOffToCloudflareContext;
     private warnedWaitUntilFailure;
@@ -235,13 +248,11 @@ export interface WorkersConfig {
 /** 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;
+    setAttribute(key: string, value?: string | number | boolean): 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;
+    enterSpan<T, A extends unknown[]>(name: string, callback: (span: CloudflareNativeSpan, ...args: A) => T, ...args: A): T;
 }
 /**
  * A `BasicTracerProvider` with the underlying `HeystackSpanExporter` attached so
@@ -273,9 +284,9 @@ export declare function createTracerProvider(config: HeystackOptions & {
  * context across `await` boundaries — child spans created after an `await`
  * inside a handler are correctly parented to the request's root span.
  *
- * WinterCG-safe: it does NOT import `node:async_hooks`; instead it uses the
- * ALS global that the runtime exposes. Falls back to `SyncStackContextManager`
- * when the global is absent (Deno, Bun without globals, etc.).
+ * WinterCG-safe: it does NOT import the Node-only async_hooks builtin; instead
+ * it uses the ALS global that the runtime exposes. Falls back to
+ * `SyncStackContextManager` when the global is absent (Deno, Bun without globals, etc.).
  */
 export declare class AlsContextManager implements ContextManager {
     private _als;
@@ -311,10 +322,12 @@ export declare function __resetContextManager(): void;
  * FLUSH: on Next-on-OpenNext (where `@opennextjs/cloudflare` is present) the
  * exporter automatically borrows the Cloudflare request context's
  * `ctx.waitUntil` so the export POST completes before the isolate is torn down
- * — no app hook needed. For other workerd setups without it, call
- * `flushHeystack()` (which awaits the export fetch) from a response hook, hand
- * it to `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in
- * the config (highest priority). Returns the provider.
+ * — no app hook needed. For other workerd setups without it, wrap your
+ * handler's ExecutionContext with {@link wrapExecutionContext} (every
+ * `ctx.waitUntil` then also schedules the export drain), call `flushHeystack()`
+ * (which awaits the export fetch) from a response hook, hand it to
+ * `ctx.waitUntil(flushHeystack())`, or pass an explicit `waitUntil` in the
+ * config (highest priority). Returns the provider.
  */
 export declare function initHeystackWorkers(config: WorkersConfig & {
     apiKey: string;
@@ -328,21 +341,25 @@ export declare function initHeystackWorkers(config: WorkersConfig & {
  * isolate is torn down. Best-effort no-op if no provider is registered.
  */
 export declare function flushHeystack(): Promise<void>;
+export declare function wrapExecutionContext<Props>(ctx: ExecutionContext<Props>): ExecutionContext<Props>;
 /** Reset the singleton global provider. Internal/testing helper. */
 export declare function __resetProvider(): void;
-/** Reset the once-only no-key warning. Internal/testing helper. */
+/** Reset the once-only warnings. Internal/testing helper. */
 export declare function __resetWarnings(): void;
 /**
  * The shape of a Worker's default export. `fetch` is the common entrypoint, but
- * a Worker may also export `queue` / `scheduled` / `tail` (and arbitrary other
- * siblings). `instrument()` forwards ALL of these untouched except `fetch`
- * (always traced) and `queue` / `scheduled` (traced when present) — so wrapping
- * a Worker never drops a handler Cloudflare requires for deploy.
+ * a Worker may also export `queue` / `scheduled` / `tail` / `email` (and
+ * arbitrary other siblings). `instrument()` traces `fetch`, `queue`,
+ * `scheduled`, `email` and `tail` when present — every other sibling is
+ * forwarded untouched, so wrapping never drops a handler Cloudflare requires
+ * for deploy.
  */
 interface WorkerHandler<E> {
     fetch?(req: Request, env: E, ctx: ExecutionContext): Promise<Response> | Response;
     queue?(batch: MessageBatch<any>, env: E, ctx: ExecutionContext): Promise<void> | void;
     scheduled?(controller: ScheduledController, env: E, ctx: ExecutionContext): Promise<void> | void;
+    email?(message: ForwardableEmailMessage, env: E, ctx: ExecutionContext): Promise<void> | void;
+    tail?(events: TraceItem[], env: E, ctx: ExecutionContext): Promise<void> | void;
     [key: string]: unknown;
 }
 /**
@@ -370,8 +387,8 @@ interface WorkerHandler<E> {
  * ALL HANDLERS FORWARDED: the returned object spreads `handler`, so sibling
  * handlers a Worker exports (`tail`, `email`, etc.) are preserved — Cloudflare
  * won't reject the deploy for a missing handler. `fetch` is always replaced with
- * a traced wrapper; `queue` and `scheduled` are wrapped (and traced) when
- * present; everything else is forwarded untouched.
+ * a traced wrapper; `queue`, `scheduled`, `email` and `tail` are wrapped (and
+ * traced) when present; everything else is forwarded untouched.
  *
  * If no API key is available (neither `config.apiKey` nor
  * `env.HEYSTACK_API_KEY`), the handler runs untraced.
@@ -383,7 +400,7 @@ interface WorkerHandler<E> {
  * traced key is present (and non-optional) exactly when it exists on the input
  * handler, so a `{ fetch }` Worker yields a non-optional `fetch`.
  */
-type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled"> & (H extends {
+type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled" | "email" | "tail"> & (H extends {
     fetch: unknown;
 } ? {
     fetch: (req: Request, env: E, ctx: ExecutionContext) => Promise<Response>;
@@ -395,6 +412,14 @@ type Instrumented<E, H> = Omit<H, "fetch" | "queue" | "scheduled"> & (H extends
     scheduled: unknown;
 } ? {
     scheduled: (controller: ScheduledController, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown) & (H extends {
+    email: unknown;
+} ? {
+    email: (message: ForwardableEmailMessage, env: E, ctx: ExecutionContext) => Promise<void>;
+} : unknown) & (H extends {
+    tail: unknown;
+} ? {
+    tail: (events: TraceItem[], env: E, ctx: ExecutionContext) => Promise<void>;
 } : unknown);
 /**
  * Recover a handler's concrete env type from whichever traced entrypoint it
@@ -412,6 +437,52 @@ type EnvOf<H> = H extends {
     scheduled: (controller: ScheduledController, env: infer E, ctx: ExecutionContext) => unknown;
 } ? E : unknown;
 export declare function instrument<H extends WorkerHandler<any>>(handler: H, config: WorkersConfig): Instrumented<EnvOf<H>, H>;
+export interface InstrumentClassesOpts {
+    /**
+     * Factory that creates and starts a new span. Called at method-invocation
+     * time. For integration: omit it — the global `heystack` tracer is used with
+     * the active context (or the explicit `parentCtx`). For unit tests inject a
+     * fake so no global provider is required.
+     */
+    startSpan?: (name: string, attrs: Record<string, unknown>, kind?: SpanKind, parentCtx?: Context) => Span;
+}
+/**
+ * Decorate a Durable Object class:
+ * - constructor: wraps the incoming `state` so `state.storage` operations emit
+ *   INTERNAL child spans (`DO storage get|put|delete|list`) with key/count attrs.
+ * - `fetch()`: SERVER span named `<METHOD> <path>` (like instrument()'s fetch
+ *   wrapper), continuing an inbound W3C traceparent, recording status/duration.
+ * - `alarm()`: INTERNAL span.
+ * - RPC prototype methods: SERVER span `DO rpc <method>` with rpc.method attrs.
+ *
+ * Every root span schedules flushHeystack() via `state.waitUntil` so exports
+ * complete before isolate teardown. Instance arrow-function methods assigned in
+ * the constructor are not enumerable on the prototype and stay unwrapped.
+ *
+ *   export class Counter extends DurableObject {
+ *     // ...
+ *   }
+ *   export const Counter = wrapDurableObjectClass(BaseCounter); // or decorate in place
+ */
+export declare function wrapDurableObjectClass<C extends {
+    readonly prototype: object;
+}>(cls: C, opts?: InstrumentClassesOpts): C;
+/**
+ * Decorate a Cloudflare Workflows entrypoint class so its `run(event, step)`
+ * emits a `workflow run` INTERNAL span with workflow identity/schedule metadata
+ * (never payload content), and the handed-out
+ * step object's methods become traced versions (see {@link wrapWorkflowStep}):
+ * `step.do(name, fn)` → INTERNAL span named `step <name>` with success/error
+ * status (step retries manifest as whole-run replays by the engine and are not
+ * observable at this layer, so no retry attribute is emitted), and
+ * sleep/sleepUntil/waitForEvent/waitForName → short marker spans.
+ *
+ * Every completed run schedules flushHeystack() via the entrypoint state's
+ * `waitUntil` so exports survive isolate teardown.
+ */
+export declare function wrapWorkflowEntrypointClass<C extends {
+    readonly prototype: object;
+}>(cls: C, opts?: InstrumentClassesOpts): C;
 /**
  * Run `fn` inside a new child span named `name`. The span is automatically
  * parented to the currently-active span (via `context.active()`), started