agent-telemetry 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # agent-telemetry
 
-Lightweight JSONL telemetry for AI agent backends. Zero runtime dependencies.
+Lightweight JSONL telemetry for easier AI agent consumption. Zero runtime dependencies.
 
-Writes structured telemetry events to rotating JSONL files in development. Falls back to `console.log` in runtimes without filesystem access (Cloudflare Workers). Includes framework adapters for [Hono](https://hono.dev) and [Inngest](https://inngest.com).
+Writes structured telemetry events to rotating JSONL files in development. Falls back to `console.log` in runtimes without filesystem access (Cloudflare Workers). Includes framework adapters for Hono, Inngest, Express, Fastify, Prisma, Supabase, a generic traced fetch wrapper, and browser trace-context helpers.
 
 ## Install
 
@@ -38,21 +38,16 @@ Each call to `emit()` appends a JSON line to `logs/telemetry.jsonl` with an auto
 
 ## How It Works
 
-The library connects three layers of tracing — HTTP requests, event dispatch, and background jobs — through a shared `traceId`:
+The library connects every layer of your stack through a shared `traceId`:
 
 ```
-Browser → HTTP Request → Hono Middleware (parses/generates traceparent)
-                              ↓
-                         getTraceContext(c)  →  { _trace: { traceId, parentSpanId } }
-                              ↓
-                         inngest.send({ data: { ...payload, ...getTraceContext(c) } })
-                              ↓
-                         Inngest Middleware (reads _trace from event data)
-                              ↓
-                         job.start / job.end (same traceId)
+Inbound HTTP  →  Database Queries  →  External API Calls  →  Background Jobs
+  Hono            Prisma               Traced Fetch           Inngest
+  Express         Supabase (PostgREST)  Supabase (auth/
+  Fastify                                storage/functions)
 ```
 
-One `traceId` follows a request from the HTTP boundary through dispatch into background job execution. The Hono adapter uses the [W3C `traceparent`](https://www.w3.org/TR/trace-context/) header for propagation, enabling interop with OpenTelemetry and other standards-compliant tools. Query your JSONL logs by `traceId` to see the full chain.
+One `traceId` follows a request from the HTTP boundary through database queries, external API calls, and into background job execution. `spanId`/`parentSpanId` fields preserve parent-child relationships inside that trace. HTTP adapters use the [W3C `traceparent`](https://www.w3.org/TR/trace-context/) header for propagation, enabling interop with OpenTelemetry and other standards-compliant tools. Query your JSONL logs by `traceId` to see the full chain.
 
 ## Full-Stack Example
 
@@ -157,10 +152,10 @@ app.use('*', trace)
 The middleware:
 - Parses the incoming W3C `traceparent` header, or generates a fresh trace ID if absent/invalid
 - Sets `traceparent` on the response for client-side correlation (format: `00-{traceId}-{spanId}-01`)
-- Emits `http.request` events with method, path, status, duration, and extracted entities
+- Emits `http.request` events with method, path, status, duration, extracted entities, and span linkage (`spanId`, `parentSpanId`)
 - Extracts entity IDs from URL paths — looks for a matching `segment`, then checks if the next segment is a UUID
 
-`getTraceContext(c)` returns `{ _trace: { traceId, parentSpanId } }` for spreading into dispatch payloads. Returns `{}` if no trace middleware is active.
+`getTraceContext(c)` returns `{ _trace: { traceId, parentSpanId, traceFlags } }` for spreading into dispatch payloads. Returns `{}` if no trace middleware is active.
 
 ## Inngest Adapter
 
@@ -182,6 +177,150 @@ The middleware:
 - Reads `traceId` from the `_trace` field in `event.data` (set by `getTraceContext()` at the dispatch site)
 - Generates a new `traceId` when no `_trace` is present, so every function run is always traceable
 
+## Fetch Adapter
+
+Wraps any `fetch` call with telemetry. Does not monkey-patch the global — returns a new function with identical semantics.
+
+```typescript
+import { createTracedFetch } from 'agent-telemetry/fetch'
+
+const fetch = createTracedFetch({
+  telemetry,
+  baseFetch: globalThis.fetch,       // Optional — default: globalThis.fetch
+  getTraceContext: () => ctx,         // Optional — correlate with parent request
+  propagateTo: (url) => url.origin === 'https://api.my-app.com', // Optional header allowlist
+  onResponseTraceparent: (tp) => {    // Optional response callback
+    console.log(tp)
+  },
+  isEnabled: () => true,             // Optional guard
+})
+
+const res = await fetch('https://api.stripe.com/v1/charges', { method: 'POST' })
+```
+
+- Emits `external.call` events with `service` (hostname), `operation` (`METHOD /pathname`), and span linkage (`spanId`, optional `parentSpanId`)
+- `duration_ms` measures time-to-headers (TTFB) — the Response body is returned untouched for streaming
+- Handles all three fetch input types: `string`, `URL`, `Request`
+- Can inject outbound `traceparent` headers using `propagateTo` (default: same-origin only in browser, disabled elsewhere)
+- Non-2xx responses return normally (not thrown); network errors re-throw after emitting
+
+## Browser Trace Context
+
+Use the browser helpers to continue the same trace from UI requests into server adapters.
+
+```typescript
+import { createBrowserTraceContext, createBrowserTracedFetch } from 'agent-telemetry/browser'
+
+const trace = createBrowserTraceContext({
+  // Optional SSR bootstrap: <meta name="traceparent" content="00-...">
+  initialTraceparent: document.querySelector('meta[name="traceparent"]')?.getAttribute('content'),
+})
+
+const fetch = createBrowserTracedFetch({
+  trace,
+  // Default is same-origin only. Keep this allowlist strict.
+  propagateTo: (url) => url.origin === window.location.origin,
+})
+
+await fetch('/api/users')
+```
+
+- `createBrowserTraceContext()` bootstraps from `initialTraceparent`, then `<meta name="traceparent">`, then fresh IDs
+- `createBrowserTracedFetch()` injects W3C `traceparent` on allowed requests and can adopt response `traceparent`
+- `trace.withSpan(name, fn)` creates a child span for user actions and restores the previous parent span after completion
+
+## Prisma Adapter
+
+Traces all Prisma model operations via `$extends()`. No runtime `@prisma/client` import — the extension is structurally compatible.
+
+```typescript
+import { createPrismaTrace } from 'agent-telemetry/prisma'
+
+const prisma = new PrismaClient().$extends(createPrismaTrace({
+  telemetry,
+  getTraceContext: () => ctx,         // Optional — correlate with parent request
+  isEnabled: () => true,             // Optional guard
+}))
+```
+
+- Emits `db.query` events with `provider: "prisma"`, `model` (e.g. `"User"`), `operation` (e.g. `"findMany"`), and span linkage (`spanId`, optional `parentSpanId`)
+- Requires Prisma 5.0.0+ (stable `$extends` API)
+- No access to raw SQL at the query extension level — model and operation names only
+
+## Express Adapter
+
+Standard Express middleware with the same tracing pattern as Hono. No `express` or `@types/express` runtime dependency.
+
+```typescript
+import { createExpressTrace, getTraceContext } from 'agent-telemetry/express'
+
+app.use(createExpressTrace({
+  telemetry,
+  entityPatterns: [
+    { segment: 'users', key: 'userId' },
+  ],
+  isEnabled: () => true,
+}))
+
+app.post('/api/users/:id', (req, res) => {
+  // Propagate trace context to downstream services
+  const ctx = getTraceContext(req)
+  res.json({ ok: true })
+})
+```
+
+- Emits `http.request` events with method, path (query string stripped), status, duration, entities, and span linkage
+- Parses/sets W3C `traceparent` header for propagation
+- Uses `req.route.path` for parameterized patterns (e.g. `/users/:id`), falls back to `req.originalUrl`
+- Handles both `res.on("finish")` and `res.on("close")` to capture aborted requests
+
+## Fastify Adapter
+
+Fastify plugin using `onRequest`/`onResponse` hooks. No `fastify` runtime dependency — uses `Symbol.for("skip-override")` instead of `fastify-plugin`.
+
+```typescript
+import { createFastifyTrace, getTraceContext } from 'agent-telemetry/fastify'
+
+app.register(createFastifyTrace({
+  telemetry,
+  entityPatterns: [
+    { segment: 'users', key: 'userId' },
+  ],
+  isEnabled: () => true,
+}))
+```
+
+- Emits `http.request` events using `reply.elapsedTime` for high-resolution duration, including span linkage
+- Strips query strings from emitted `path` values
+- Parses/sets W3C `traceparent` header for propagation
+- Uses `request.routeOptions.url` for parameterized route patterns
+- Requires Fastify 4.0.0+ (`reply.elapsedTime` not available in 3.x)
+
+## Supabase Adapter
+
+A traced `fetch` that parses Supabase URL patterns to emit rich, service-aware telemetry. PostgREST calls become `db.query` events; auth/storage/functions calls become `external.call` events.
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+import { createSupabaseTrace } from 'agent-telemetry/supabase'
+
+const tracedFetch = createSupabaseTrace({ telemetry })
+const supabase = createClient(url, key, { global: { fetch: tracedFetch } })
+```
+
+URL pattern classification:
+
+| Pattern | Event | Fields |
+|---------|-------|--------|
+| `/rest/v{N}/{table}` | `db.query` | `model: table`, `operation: select\|insert\|update\|delete` |
+| `/auth/v{N}/{endpoint}` | `external.call` | `service: "supabase-auth"` |
+| `/storage/v{N}/object/{bucket}` | `external.call` | `service: "supabase-storage"` |
+| `/functions/v{N}/{name}` | `external.call` | `service: "supabase-functions"` |
+
+- Each `fetch` invocation emits one event — Supabase's built-in retry logic generates separate events per retry
+- Realtime (WebSocket) subscriptions are not intercepted (they don't use `fetch`)
+- Uses `Telemetry<SupabaseEvents>` (`DbQueryEvent | ExternalCallEvent` union)
+
 ## Configuration
 
 ```typescript
@@ -210,6 +349,8 @@ const telemetry = await createTelemetry({
 | `HttpEvents` | `http.request` | HTTP request/response telemetry |
 | `JobEvents` | `job.start`, `job.end`, `job.dispatch`, `job.step` | Background job lifecycle |
 | `ExternalEvents` | `external.call` | External service calls |
+| `DbEvents` | `db.query` | Database query telemetry |
+| `SupabaseEvents` | `db.query`, `external.call` | Supabase-specific union |
 | `PresetEvents` | All of the above | Combined preset union |
 
 ## Utilities
@@ -251,7 +392,7 @@ The writer automatically detects the runtime environment:
 
 Detection happens once during `createTelemetry()` — it probes the filesystem by creating the log directory and verifying it exists. Cloudflare's `nodejs_compat` stubs succeed silently on `mkdirSync` but fail the existence check, triggering the console fallback.
 
-The returned `emit()` function is synchronous and **never throws**, even with malformed data or filesystem errors. Telemetry must not crash the host application.
+The returned `emit()` function is synchronous, non-blocking, and **never throws**, even with malformed data or filesystem errors. Telemetry must not crash the host application.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "agent-telemetry",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Lightweight JSONL telemetry for AI agent backends. Zero deps, framework adapters included.",
 	"type": "module",
 	"exports": {
@@ -15,11 +15,33 @@
 		"./inngest": {
 			"import": "./src/adapters/inngest.ts",
 			"types": "./src/adapters/inngest.ts"
+		},
+		"./fetch": {
+			"import": "./src/adapters/fetch.ts",
+			"types": "./src/adapters/fetch.ts"
+		},
+		"./prisma": {
+			"import": "./src/adapters/prisma.ts",
+			"types": "./src/adapters/prisma.ts"
+		},
+		"./express": {
+			"import": "./src/adapters/express.ts",
+			"types": "./src/adapters/express.ts"
+		},
+		"./fastify": {
+			"import": "./src/adapters/fastify.ts",
+			"types": "./src/adapters/fastify.ts"
+		},
+		"./supabase": {
+			"import": "./src/adapters/supabase.ts",
+			"types": "./src/adapters/supabase.ts"
+		},
+		"./browser": {
+			"import": "./src/browser.ts",
+			"types": "./src/browser.ts"
 		}
 	},
-	"files": [
-		"src"
-	],
+	"files": ["src"],
 	"scripts": {
 		"test": "bun test",
 		"typecheck": "tsc --noEmit",
@@ -27,10 +49,14 @@
 		"check": "bun run typecheck && bun run lint && bun test"
 	},
 	"peerDependencies": {
+		"fastify": ">=4.0.0",
 		"hono": ">=4.0.0",
 		"inngest": ">=3.0.0"
 	},
 	"peerDependenciesMeta": {
+		"fastify": {
+			"optional": true
+		},
 		"hono": {
 			"optional": true
 		},
@@ -41,6 +67,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.0",
 		"@types/bun": "latest",
+		"fastify": "^5.7.4",
 		"hono": "^4.7.0",
 		"inngest": "^3.0.0",
 		"typescript": "^5.7.0"
@@ -58,7 +85,12 @@
 		"agent",
 		"ai",
 		"tracing",
+		"express",
+		"fastify",
+		"fetch",
 		"hono",
-		"inngest"
+		"inngest",
+		"prisma",
+		"supabase"
 	]
 }

package/src/adapters/express.ts

@@ -0,0 +1,188 @@
+/**
+ * Express Adapter
+ *
+ * Creates Express middleware that traces HTTP requests. Emits http.request
+ * telemetry events with method, path, status, duration, and extracted entities.
+ *
+ * No runtime import of express — uses inline types for req/res/next.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type HttpEvents } from 'agent-telemetry'
+ * import { createExpressTrace, getTraceContext } from 'agent-telemetry/express'
+ *
+ * const telemetry = await createTelemetry<HttpEvents>()
+ * app.use(createExpressTrace({ telemetry }))
+ * ```
+ */
+
+import { extractEntities } from "../entities.ts";
+import { startSpanFromTraceparent } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
+import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
+
+// ============================================================================
+// Inline Express Types (no runtime import of express)
+// ============================================================================
+
+interface ExpressRequest {
+	method: string;
+	originalUrl: string;
+	url: string;
+	headers: Record<string, string | string[] | undefined>;
+	route?: { path?: string };
+}
+
+interface ExpressResponse {
+	statusCode: number;
+	setHeader(name: string, value: string): void;
+	on(event: string, listener: () => void): void;
+}
+
+type ExpressNextFunction = (err?: unknown) => void;
+
+/** Express middleware function signature. */
+export type ExpressMiddleware = (
+	req: ExpressRequest,
+	res: ExpressResponse,
+	next: ExpressNextFunction,
+) => void;
+
+// ============================================================================
+// Request-Scoped Trace Storage
+// ============================================================================
+
+const traceStore = new WeakMap<object, { traceId: string; spanId: string; traceFlags: string }>();
+
+function stripQueryAndFragment(url: string): string {
+	const queryIdx = url.indexOf("?");
+	const hashIdx = url.indexOf("#");
+	const cutIdx =
+		queryIdx === -1 ? hashIdx : hashIdx === -1 ? queryIdx : Math.min(queryIdx, hashIdx);
+	const clean = cutIdx === -1 ? url : url.slice(0, cutIdx);
+	return clean || "/";
+}
+
+// ============================================================================
+// Options
+// ============================================================================
+
+/** Options for Express trace middleware. */
+export interface ExpressTraceOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<HttpRequestEvent>;
+	/** Entity patterns for extracting IDs from URL paths. */
+	entityPatterns?: EntityPattern[];
+	/** Guard function — return false to skip tracing for a request. */
+	isEnabled?: () => boolean;
+}
+
+// ============================================================================
+// Middleware Factory
+// ============================================================================
+
+/**
+ * Create Express middleware that traces HTTP requests.
+ *
+ * Generates a traceId per request (or propagates a valid incoming
+ * `traceparent`), stores it on a WeakMap keyed by the request object,
+ * sets the `traceparent` response header, and emits an http.request
+ * event on completion.
+ *
+ * Listens on both `"finish"` and `"close"` response events with an
+ * emit-once guard to handle aborted requests without double-emission.
+ */
+export function createExpressTrace(options: ExpressTraceOptions): ExpressMiddleware {
+	const { telemetry, entityPatterns, isEnabled } = options;
+
+	return (req, res, next) => {
+		if (isEnabled && !isEnabled()) {
+			next();
+			return;
+		}
+
+		const incoming = Array.isArray(req.headers.traceparent)
+			? req.headers.traceparent[0]
+			: req.headers.traceparent;
+		const span = startSpanFromTraceparent(incoming);
+
+		traceStore.set(req, {
+			traceId: span.traceId,
+			spanId: span.spanId,
+			traceFlags: span.traceFlags,
+		});
+		res.setHeader("traceparent", formatTraceparent(span.traceId, span.spanId, span.traceFlags));
+
+		const start = performance.now();
+		let emitted = false;
+
+		const emitOnce = () => {
+			if (emitted) return;
+			emitted = true;
+
+			const duration_ms = Math.round(performance.now() - start);
+			const requestPath = stripQueryAndFragment(req.originalUrl || req.url || "/");
+			const path = req.route?.path ?? requestPath;
+
+			const event: HttpRequestEvent = {
+				kind: "http.request",
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
+				method: req.method,
+				path,
+				status: res.statusCode,
+				duration_ms,
+			};
+
+			if (entityPatterns) {
+				const entities = extractEntities(requestPath, entityPatterns);
+				if (entities) event.entities = entities;
+			}
+
+			if (res.statusCode >= 500) {
+				event.error = `HTTP ${res.statusCode}`;
+			}
+
+			telemetry.emit(event);
+		};
+
+		res.on("finish", emitOnce);
+		res.on("close", emitOnce);
+
+		next();
+	};
+}
+
+// ============================================================================
+// Trace Context Accessor
+// ============================================================================
+
+/**
+ * Get trace context from an Express request object.
+ *
+ * Returns an object with `_trace` suitable for spreading into event
+ * dispatch payloads to propagate the trace across async boundaries.
+ *
+ * @example
+ * ```ts
+ * app.post('/api/process', (req, res) => {
+ *   await queue.send({ ...payload, ...getTraceContext(req) })
+ * })
+ * ```
+ */
+export function getTraceContext(
+	req: object,
+):
+	| { _trace: { traceId: string; parentSpanId: string; traceFlags?: string } }
+	| Record<string, never> {
+	const stored = traceStore.get(req);
+	if (!stored) return {};
+	return {
+		_trace: {
+			traceId: stored.traceId,
+			parentSpanId: stored.spanId,
+			traceFlags: stored.traceFlags,
+		},
+	};
+}

package/src/adapters/fastify.ts

@@ -0,0 +1,207 @@
+/**
+ * Fastify Adapter
+ *
+ * Creates a Fastify plugin that traces HTTP requests via onRequest/onResponse
+ * hooks. Uses reply.elapsedTime for high-resolution duration measurement.
+ *
+ * No runtime import of fastify -- uses inline types and Symbol.for("skip-override")
+ * instead of the fastify-plugin package.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type HttpEvents } from 'agent-telemetry'
+ * import { createFastifyTrace, getTraceContext } from 'agent-telemetry/fastify'
+ *
+ * const telemetry = await createTelemetry<HttpEvents>()
+ * app.register(createFastifyTrace({ telemetry }))
+ * ```
+ */
+
+import { extractEntities } from "../entities.ts";
+import { startSpanFromTraceparent } from "../trace-context.ts";
+import { formatTraceparent } from "../traceparent.ts";
+import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
+
+// ---------------------------------------------------------------------------
+// Inline Fastify types (no runtime import)
+// ---------------------------------------------------------------------------
+
+interface FastifyRequest {
+	method: string;
+	url: string;
+	headers: Record<string, string | string[] | undefined>;
+	routeOptions?: { url?: string };
+}
+
+interface FastifyReply {
+	statusCode: number;
+	elapsedTime: number;
+	header(name: string, value: string): FastifyReply;
+}
+
+interface FastifyInstance {
+	addHook(
+		name: "onRequest",
+		hook: (request: FastifyRequest, reply: FastifyReply, done: () => void) => void,
+	): void;
+	addHook(
+		name: "onResponse",
+		hook: (request: FastifyRequest, reply: FastifyReply, done: () => void) => void,
+	): void;
+}
+
+type FastifyPluginCallback = ((
+	instance: FastifyInstance,
+	opts: Record<string, unknown>,
+	done: () => void,
+) => void) & {
+	[key: symbol]: unknown;
+};
+
+// ---------------------------------------------------------------------------
+// Trace storage (keyed on Fastify request wrapper, not request.raw)
+// ---------------------------------------------------------------------------
+
+const traceStore = new WeakMap<
+	object,
+	{ traceId: string; spanId: string; parentSpanId?: string; traceFlags: string }
+>();
+
+function stripQueryAndFragment(url: string): string {
+	const queryIdx = url.indexOf("?");
+	const hashIdx = url.indexOf("#");
+	const cutIdx =
+		queryIdx === -1 ? hashIdx : hashIdx === -1 ? queryIdx : Math.min(queryIdx, hashIdx);
+	const clean = cutIdx === -1 ? url : url.slice(0, cutIdx);
+	return clean || "/";
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options for the Fastify trace plugin. */
+export interface FastifyTraceOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<HttpRequestEvent>;
+	/** Entity patterns for extracting IDs from URL paths. */
+	entityPatterns?: EntityPattern[];
+	/** Guard function -- return false to skip tracing for a request. */
+	isEnabled?: () => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Fastify plugin that traces HTTP requests.
+ *
+ * Registers onRequest and onResponse hooks. The onRequest hook generates
+ * a traceId (or propagates a valid incoming `traceparent`), stores it in
+ * a WeakMap keyed on the Fastify request object, and sets the response
+ * `traceparent` header. The onResponse hook emits an http.request event
+ * using `reply.elapsedTime` for high-resolution duration.
+ */
+export function createFastifyTrace(options: FastifyTraceOptions): FastifyPluginCallback {
+	const { telemetry, entityPatterns, isEnabled } = options;
+
+	const plugin = (instance: FastifyInstance, _opts: Record<string, unknown>, done: () => void) => {
+		instance.addHook("onRequest", (request, reply, hookDone) => {
+			if (isEnabled && !isEnabled()) {
+				hookDone();
+				return;
+			}
+
+			const incoming = Array.isArray(request.headers.traceparent)
+				? request.headers.traceparent[0]
+				: request.headers.traceparent;
+			const span = startSpanFromTraceparent(incoming);
+
+			traceStore.set(request, {
+				traceId: span.traceId,
+				spanId: span.spanId,
+				parentSpanId: span.parentSpanId,
+				traceFlags: span.traceFlags,
+			});
+			reply.header("traceparent", formatTraceparent(span.traceId, span.spanId, span.traceFlags));
+			hookDone();
+		});
+
+		instance.addHook("onResponse", (request, reply, hookDone) => {
+			const trace = traceStore.get(request);
+			if (!trace) {
+				hookDone();
+				return;
+			}
+
+			const requestPath = stripQueryAndFragment(request.url);
+			const path = request.routeOptions?.url ?? requestPath;
+			const duration_ms = Math.round(reply.elapsedTime);
+
+			const event: HttpRequestEvent = {
+				kind: "http.request",
+				traceId: trace.traceId,
+				spanId: trace.spanId,
+				parentSpanId: trace.parentSpanId,
+				method: request.method,
+				path,
+				status: reply.statusCode,
+				duration_ms,
+			};
+
+			if (entityPatterns) {
+				// Extract entities from the actual URL (with real IDs),
+				// not the parameterized route pattern
+				const entities = extractEntities(requestPath, entityPatterns);
+				if (entities) event.entities = entities;
+			}
+
+			telemetry.emit(event);
+			hookDone();
+		});
+
+		done();
+	};
+
+	// Fastify encapsulation decorators (replaces fastify-plugin dependency)
+	const decorated = plugin as FastifyPluginCallback;
+	decorated[Symbol.for("skip-override")] = true;
+	decorated[Symbol.for("fastify.display-name")] = "agent-telemetry";
+
+	return decorated;
+}
+
+// ---------------------------------------------------------------------------
+// Trace context accessor
+// ---------------------------------------------------------------------------
+
+/**
+ * Get trace context from a Fastify request object.
+ *
+ * Returns an object with `_trace` suitable for spreading into event
+ * dispatch payloads to propagate the trace across async boundaries.
+ *
+ * @example
+ * ```ts
+ * app.post('/api/process', async (request, reply) => {
+ *   await queue.send({ ...payload, ...getTraceContext(request) })
+ * })
+ * ```
+ */
+export function getTraceContext(
+	request: unknown,
+):
+	| { _trace: { traceId: string; parentSpanId: string; traceFlags?: string } }
+	| Record<string, never> {
+	if (!request || typeof request !== "object") return {};
+	const trace = traceStore.get(request);
+	if (!trace) return {};
+	return {
+		_trace: {
+			traceId: trace.traceId,
+			parentSpanId: trace.spanId,
+			traceFlags: trace.traceFlags,
+		},
+	};
+}