agent-telemetry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brannon Lucas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# agent-telemetry
+
+Lightweight JSONL telemetry for AI agent backends. 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).
+
+## Install
+
+```bash
+bun add agent-telemetry
+```
+
+> **Node.js users:** This package ships TypeScript source (no build step). You'll need a bundler that handles `.ts` imports (esbuild, tsup, Vite, etc.).
+
+## Quick Start
+
+```typescript
+import { createTelemetry, generateTraceId, type PresetEvents } from 'agent-telemetry'
+
+// createTelemetry is async (one-time runtime probe). The returned emit() is synchronous.
+const telemetry = await createTelemetry<PresetEvents>()
+
+telemetry.emit({
+  kind: 'http.request',
+  traceId: generateTraceId(),
+  method: 'GET',
+  path: '/api/health',
+  status: 200,
+  duration_ms: 12,
+})
+```
+
+Each call to `emit()` appends a JSON line to `logs/telemetry.jsonl` with an auto-injected `timestamp`:
+
+```jsonl
+{"kind":"http.request","traceId":"0a1b2c3d4e5f67890a1b2c3d4e5f6789","method":"GET","path":"/api/health","status":200,"duration_ms":12,"timestamp":"2026-02-24T21:00:00.000Z"}
+```
+
+## How It Works
+
+The library connects three layers of tracing — HTTP requests, event dispatch, and background jobs — 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)
+```
+
+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.
+
+## Full-Stack Example
+
+Create **one** telemetry instance and share it across both adapters:
+
+```typescript
+// lib/telemetry.ts
+import { createTelemetry, type PresetEvents } from 'agent-telemetry'
+
+export const telemetry = await createTelemetry<PresetEvents>()
+```
+
+```typescript
+// server.ts
+import { Hono } from 'hono'
+import { Inngest } from 'inngest'
+import { createHonoTrace, getTraceContext } from 'agent-telemetry/hono'
+import { createInngestTrace } from 'agent-telemetry/inngest'
+import { telemetry } from './lib/telemetry'
+
+// --- HTTP tracing ---
+const trace = createHonoTrace({
+  telemetry,
+  entityPatterns: [
+    { segment: 'users', key: 'userId' },
+    { segment: 'posts', key: 'postId' },
+  ],
+})
+
+const app = new Hono()
+app.use('*', trace)
+
+// Propagate traceId into background job dispatch
+app.post('/api/users/:id/process', async (c) => {
+  await inngest.send({
+    name: 'app/user.process',
+    data: { userId: c.req.param('id'), ...getTraceContext(c) },
+  })
+  return c.json({ ok: true })
+})
+
+// --- Background job tracing ---
+const inngestTrace = createInngestTrace({
+  telemetry,
+  entityKeys: ['userId', 'postId'],
+})
+
+const inngest = new Inngest({ id: 'my-app', middleware: [inngestTrace] })
+```
+
+This produces a correlated trace:
+```jsonl
+{"kind":"http.request","traceId":"aabb...","method":"POST","path":"/api/users/550e8400-e29b-41d4-a716-446655440000/process","status":200,"duration_ms":45,"entities":{"userId":"550e8400-e29b-41d4-a716-446655440000"},"timestamp":"..."}
+{"kind":"job.dispatch","traceId":"aabb...","parentSpanId":"cc11...","eventName":"app/user.process","entities":{"userId":"550e8400-e29b-41d4-a716-446655440000"},"timestamp":"..."}
+{"kind":"job.start","traceId":"aabb...","spanId":"dd22...","functionId":"process-user","timestamp":"..."}
+{"kind":"job.end","traceId":"aabb...","spanId":"dd22...","functionId":"process-user","duration_ms":230,"status":"success","timestamp":"..."}
+```
+
+All four events share the same `traceId`. Filter with `jq 'select(.traceId == "aabb...")'` to see the full chain.
+
+## Custom Events
+
+Extend the type system with your own event kinds:
+
+```typescript
+import { createTelemetry, type HttpEvents, type JobEvents } from 'agent-telemetry'
+
+type MyEvents = HttpEvents | JobEvents | {
+  kind: 'custom.checkout'
+  traceId: string
+  orderId: string
+  amount: number
+}
+
+const telemetry = await createTelemetry<MyEvents>()
+
+telemetry.emit({
+  kind: 'custom.checkout',
+  traceId: 'trace-1',
+  orderId: 'order-abc',
+  amount: 4999,
+})
+```
+
+## Hono Adapter
+
+```typescript
+import { createHonoTrace, getTraceContext } from 'agent-telemetry/hono'
+
+const trace = createHonoTrace({
+  telemetry,
+  entityPatterns: [            // Extract entity IDs from URL path segments
+    { segment: 'users', key: 'userId' },
+    { segment: 'posts', key: 'postId' },
+  ],
+  isEnabled: () => true,       // Guard function (default: () => true)
+})
+
+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
+- 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.
+
+## Inngest Adapter
+
+```typescript
+import { createInngestTrace } from 'agent-telemetry/inngest'
+
+const trace = createInngestTrace({
+  telemetry,
+  name: 'my-app/trace',               // Middleware name (default: 'agent-telemetry/trace')
+  entityKeys: ['userId', 'orderId'],   // Keys to extract from event.data (default: [])
+})
+
+const inngest = new Inngest({ id: 'my-app', middleware: [trace] })
+```
+
+The middleware:
+- Emits `job.start` and `job.end` events for function lifecycle (with duration and error tracking)
+- Emits `job.dispatch` events for outgoing event sends
+- 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
+
+## Configuration
+
+```typescript
+const telemetry = await createTelemetry({
+  logDir: 'logs',              // Directory for log files (default: 'logs')
+  filename: 'telemetry.jsonl', // Log filename (default: 'telemetry.jsonl')
+  maxSize: 5_000_000,          // Max file size before rotation (default: 5MB)
+  maxBackups: 3,               // Number of rotated backups (default: 3)
+  prefix: '[TEL]',             // Console fallback prefix (default: '[TEL]')
+  isEnabled: () => true,       // Guard function (default: () => true)
+})
+```
+
+When `isEnabled` returns `false`, `emit()` is a no-op. Useful for environment-based guards:
+
+```typescript
+const telemetry = await createTelemetry({
+  isEnabled: () => process.env.NODE_ENV === 'development',
+})
+```
+
+## Preset Event Types
+
+| Type | Events | Description |
+|------|--------|-------------|
+| `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 |
+| `PresetEvents` | All of the above | Combined preset union |
+
+## Utilities
+
+```typescript
+import {
+  generateTraceId,
+  generateSpanId,
+  extractEntities,
+  extractEntitiesFromEvent,
+} from 'agent-telemetry'
+
+generateTraceId()  // → '0a1b2c3d4e5f67890a1b2c3d4e5f6789' (32 hex chars)
+generateSpanId()   // → '0a1b2c3d4e5f6789' (16 hex chars)
+
+// Extract entity IDs from URL paths (matches UUID segments only)
+extractEntities('/api/users/550e8400-e29b-41d4-a716-446655440000/posts/6ba7b810-9dad-11d1-80b4-00c04fd430c8', [
+  { segment: 'users', key: 'userId' },
+  { segment: 'posts', key: 'postId' },
+])
+// → { userId: '550e8400-...', postId: '6ba7b810-...' }
+
+extractEntities('/api/users/john', [{ segment: 'users', key: 'userId' }])
+// → undefined (non-UUID values are skipped)
+
+// Extract entity IDs from event data objects
+extractEntitiesFromEvent({ userId: 'abc', count: 5 }, ['userId', 'postId'])
+// → { userId: 'abc' }
+```
+
+## Runtime Detection
+
+The writer automatically detects the runtime environment:
+
+| Runtime | Behavior |
+|---------|----------|
+| **Bun / Node.js** | Writes to filesystem with size-based rotation |
+| **Cloudflare Workers** | Falls back to `console.log` with `[TEL]` prefix |
+
+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.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "agent-telemetry",
+	"version": "0.1.0",
+	"description": "Lightweight JSONL telemetry for AI agent backends. Zero deps, framework adapters included.",
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./src/index.ts",
+			"types": "./src/index.ts"
+		},
+		"./hono": {
+			"import": "./src/adapters/hono.ts",
+			"types": "./src/adapters/hono.ts"
+		},
+		"./inngest": {
+			"import": "./src/adapters/inngest.ts",
+			"types": "./src/adapters/inngest.ts"
+		}
+	},
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"check": "bun run typecheck && bun run lint && bun test"
+	},
+	"peerDependencies": {
+		"hono": ">=4.0.0",
+		"inngest": ">=3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"hono": {
+			"optional": true
+		},
+		"inngest": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.0",
+		"@types/bun": "latest",
+		"hono": "^4.7.0",
+		"inngest": "^3.0.0",
+		"typescript": "^5.7.0"
+	},
+	"license": "MIT",
+	"author": "Brannon Lucas",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/brannonlucas/agent-telemetry.git"
+	},
+	"keywords": [
+		"telemetry",
+		"observability",
+		"jsonl",
+		"agent",
+		"ai",
+		"tracing",
+		"hono",
+		"inngest"
+	]
+}

package/src/adapters/hono.ts

@@ -0,0 +1,120 @@
+/**
+ * Hono Adapter
+ *
+ * Creates Hono middleware that generates trace IDs per request, emits
+ * http.request telemetry events, and provides getTraceContext() for
+ * injecting trace context into downstream dispatches.
+ *
+ * Uses the W3C `traceparent` header for trace propagation.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type HttpEvents } from 'agent-telemetry'
+ * import { createHonoTrace, getTraceContext } from 'agent-telemetry/hono'
+ *
+ * const telemetry = await createTelemetry<HttpEvents>()
+ * const trace = createHonoTrace({ telemetry })
+ *
+ * app.use('*', trace)
+ * ```
+ */
+
+import type { Context, MiddlewareHandler } from "hono";
+import { extractEntities } from "../entities.ts";
+import { generateSpanId, generateTraceId } from "../ids.ts";
+import { formatTraceparent, parseTraceparent } from "../traceparent.ts";
+import type { EntityPattern, HttpRequestEvent, Telemetry } from "../types.ts";
+
+/** Options for Hono trace middleware. */
+export interface HonoTraceOptions {
+	/** 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;
+}
+
+/** Hono variable keys for trace storage. */
+const TRACE_ID_VAR = "traceId" as const;
+const SPAN_ID_VAR = "spanId" as const;
+
+/**
+ * Create Hono middleware that traces HTTP requests.
+ *
+ * Generates a traceId per request (or propagates a valid incoming `traceparent`),
+ * stores it on the Hono context, sets the `traceparent` response header, and emits
+ * an http.request event on completion.
+ */
+export function createHonoTrace(options: HonoTraceOptions): MiddlewareHandler {
+	const { telemetry, entityPatterns, isEnabled } = options;
+
+	return async (c, next) => {
+		if (isEnabled && !isEnabled()) {
+			return next();
+		}
+
+		const parsed = parseTraceparent(c.req.header("traceparent"));
+		const traceId = parsed?.traceId ?? generateTraceId();
+		const spanId = generateSpanId();
+
+		c.set(TRACE_ID_VAR, traceId);
+		c.set(SPAN_ID_VAR, spanId);
+
+		const start = performance.now();
+		let error: string | undefined;
+
+		try {
+			await next();
+		} catch (err) {
+			error = err instanceof Error ? err.message : "Unknown error";
+			throw err;
+		} finally {
+			const status = error && c.res.status < 400 ? 500 : c.res.status;
+			const duration_ms = Math.round(performance.now() - start);
+			const path = c.req.path;
+
+			c.header("traceparent", formatTraceparent(traceId, spanId));
+
+			const event: HttpRequestEvent = {
+				kind: "http.request",
+				traceId,
+				method: c.req.method,
+				path,
+				status,
+				duration_ms,
+			};
+
+			if (entityPatterns) {
+				const entities = extractEntities(path, entityPatterns);
+				if (entities) event.entities = entities;
+			}
+
+			if (error) event.error = error;
+
+			telemetry.emit(event);
+		}
+	};
+}
+
+/**
+ * Get trace context from a Hono request context.
+ *
+ * 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 (c) => {
+ *   await queue.send({ ...payload, ...getTraceContext(c) })
+ * })
+ * ```
+ */
+export function getTraceContext(
+	c: Context,
+): { _trace: { traceId: string; parentSpanId: string } } | Record<string, never> {
+	const traceId = c.get(TRACE_ID_VAR) as string | undefined;
+	const spanId = c.get(SPAN_ID_VAR) as string | undefined;
+	if (!traceId) return {};
+	return { _trace: { traceId, parentSpanId: spanId ?? generateSpanId() } };
+}

package/src/adapters/inngest.ts

@@ -0,0 +1,128 @@
+/**
+ * Inngest Adapter
+ *
+ * Creates Inngest middleware that emits job.start/job.end lifecycle events
+ * and job.dispatch events for outgoing event sends.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type JobEvents } from 'agent-telemetry'
+ * import { createInngestTrace } from 'agent-telemetry/inngest'
+ *
+ * const telemetry = await createTelemetry<JobEvents>()
+ * const trace = createInngestTrace({ telemetry })
+ *
+ * const inngest = new Inngest({ id: 'my-app', middleware: [trace] })
+ * ```
+ */
+
+import { InngestMiddleware } from "inngest";
+import { extractEntitiesFromEvent } from "../entities.ts";
+import { generateSpanId, generateTraceId } from "../ids.ts";
+import type {
+	JobDispatchEvent,
+	JobEndEvent,
+	JobEvents,
+	JobStartEvent,
+	Telemetry,
+} from "../types.ts";
+
+/** Options for the Inngest trace middleware. */
+export interface InngestTraceOptions {
+	/** Telemetry instance to emit events through. */
+	telemetry: Telemetry<JobEvents>;
+	/** Middleware name. Default: "agent-telemetry/trace". */
+	name?: string;
+	/** Keys to extract as entities from event data. Default: []. */
+	entityKeys?: string[];
+}
+
+/**
+ * Create Inngest middleware that traces function runs and event dispatches.
+ *
+ * Hooks:
+ * - onFunctionRun: emits job.start on entry, job.end on completion
+ * - onSendEvent: emits job.dispatch for outgoing events with _trace context
+ */
+export function createInngestTrace(options: InngestTraceOptions): InngestMiddleware.Any {
+	const { telemetry, name = "agent-telemetry/trace", entityKeys = [] } = options;
+
+	return new InngestMiddleware({
+		name,
+		init() {
+			return {
+				onFunctionRun({ ctx, fn }) {
+					const eventData = (ctx.event.data ?? {}) as Record<string, unknown>;
+					const trace = eventData._trace as { traceId: string; parentSpanId: string } | undefined;
+
+					const traceId = trace?.traceId ?? generateTraceId();
+					const spanId = generateSpanId();
+					const runId = ctx.runId;
+					const functionId = fn.id("");
+					const entities =
+						entityKeys.length > 0 ? extractEntitiesFromEvent(eventData, entityKeys) : undefined;
+					const start = Date.now();
+
+					const startEvent: JobStartEvent = {
+						kind: "job.start",
+						traceId,
+						spanId,
+						functionId,
+						runId,
+						entities,
+					};
+					telemetry.emit(startEvent);
+
+					return {
+						finished({ result }) {
+							const duration_ms = Date.now() - start;
+							const hasError = result.error != null;
+
+							const endEvent: JobEndEvent = {
+								kind: "job.end",
+								traceId,
+								spanId,
+								functionId,
+								runId,
+								duration_ms,
+								status: hasError ? "error" : "success",
+								error: hasError
+									? ((result.error as Error)?.message ?? String(result.error))
+									: undefined,
+							};
+							telemetry.emit(endEvent);
+						},
+					};
+				},
+
+				onSendEvent() {
+					return {
+						transformInput({ payloads }) {
+							for (const payload of payloads) {
+								const data = ((payload as { data?: unknown }).data ?? {}) as Record<
+									string,
+									unknown
+								>;
+								const trace = data._trace as { traceId: string; parentSpanId: string } | undefined;
+
+								if (trace) {
+									const dispatchEvent: JobDispatchEvent = {
+										kind: "job.dispatch",
+										traceId: trace.traceId,
+										parentSpanId: trace.parentSpanId,
+										eventName: (payload as { name: string }).name,
+										entities:
+											entityKeys.length > 0
+												? extractEntitiesFromEvent(data, entityKeys)
+												: undefined,
+									};
+									telemetry.emit(dispatchEvent);
+								}
+							}
+						},
+					};
+				},
+			};
+		},
+	});
+}

package/src/entities.ts

@@ -0,0 +1,84 @@
+/**
+ * Entity Extraction
+ *
+ * Configurable extraction of entity IDs from URL paths and event payloads.
+ * Users provide their own patterns — no framework-specific defaults.
+ */
+
+import type { EntityPattern } from "./types.ts";
+
+const UUID_RE = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+
+/**
+ * Extract entity IDs from a URL path using the provided patterns.
+ *
+ * Scans path segments for pattern matches. When a segment matches a pattern's
+ * `segment` value, the following segment is tested against UUID format and
+ * captured under the pattern's `key`.
+ *
+ * @example
+ * ```ts
+ * const patterns = [
+ *   { segment: 'users', key: 'userId' },
+ *   { segment: 'posts', key: 'postId' },
+ * ]
+ * extractEntities(
+ *   '/api/users/550e8400-e29b-41d4-a716-446655440000/posts/6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+ *   patterns,
+ * )
+ * // → { userId: '550e8400-e29b-41d4-a716-446655440000', postId: '6ba7b810-9dad-11d1-80b4-00c04fd430c8' }
+ * ```
+ */
+export function extractEntities(
+	path: string,
+	patterns: EntityPattern[],
+): Record<string, string> | undefined {
+	const segments = path.split("/");
+	const entities: Record<string, string> = {};
+	let found = false;
+
+	for (let i = 0; i < segments.length - 1; i++) {
+		for (const pattern of patterns) {
+			if (segments[i] === pattern.segment) {
+				const next = segments[i + 1];
+				if (next && UUID_RE.test(next)) {
+					entities[pattern.key] = next;
+					found = true;
+				}
+			}
+		}
+	}
+
+	return found ? entities : undefined;
+}
+
+/**
+ * Extract entity IDs from an event data payload.
+ *
+ * Scans the data object for string values at the specified keys.
+ *
+ * @example
+ * ```ts
+ * extractEntitiesFromEvent({ userId: 'abc', count: 5 }, ['userId', 'postId'])
+ * // → { userId: 'abc' }
+ * ```
+ */
+export function extractEntitiesFromEvent(
+	data: Record<string, unknown> | undefined,
+	keys: string[],
+): Record<string, string> | undefined {
+	if (!data) return undefined;
+
+	const entities: Record<string, string> = {};
+	let found = false;
+
+	for (const key of keys) {
+		const val = data[key];
+		if (typeof val === "string") {
+			entities[key] = val;
+			found = true;
+		}
+	}
+
+	return found ? entities : undefined;
+}

package/src/ids.ts

@@ -0,0 +1,16 @@
+/**
+ * ID Generation
+ *
+ * Trace and span ID generators using crypto.randomUUID().
+ * Compatible with Node.js, Bun, and Cloudflare Workers.
+ */
+
+/** Generate a 32-char hex trace ID (UUID v4 without dashes). */
+export function generateTraceId(): string {
+	return crypto.randomUUID().replaceAll("-", "");
+}
+
+/** Generate a 16-char hex span ID (first half of a trace ID). */
+export function generateSpanId(): string {
+	return crypto.randomUUID().replaceAll("-", "").slice(0, 16);
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * agent-telemetry
+ *
+ * Lightweight JSONL telemetry for AI agent backends.
+ * Zero runtime dependencies. Framework adapters for Hono and Inngest.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry, type PresetEvents } from 'agent-telemetry'
+ *
+ * const telemetry = await createTelemetry<PresetEvents>()
+ * telemetry.emit({ kind: 'http.request', traceId: '...', method: 'GET', path: '/', status: 200, duration_ms: 12 })
+ * ```
+ */
+
+import type { BaseTelemetryEvent, Telemetry, TelemetryConfig } from "./types.ts";
+import { createWriter } from "./writer.ts";
+
+/**
+ * Create a telemetry instance.
+ *
+ * Async because runtime detection (filesystem probe) happens once at startup.
+ * The returned `emit()` function is synchronous and never throws.
+ */
+export async function createTelemetry<TEvent extends BaseTelemetryEvent = BaseTelemetryEvent>(
+	config?: TelemetryConfig,
+): Promise<Telemetry<TEvent>> {
+	const isEnabled = config?.isEnabled ?? (() => true);
+
+	const writer = await createWriter({
+		logDir: config?.logDir,
+		filename: config?.filename,
+		maxSize: config?.maxSize,
+		maxBackups: config?.maxBackups,
+		prefix: config?.prefix,
+	});
+
+	return {
+		emit(event: TEvent): void {
+			try {
+				if (!isEnabled()) return;
+				const line = JSON.stringify({ ...event, timestamp: new Date().toISOString() });
+				writer.write(line);
+			} catch {
+				// emit never throws — telemetry must not crash the host application
+			}
+		},
+	};
+}
+
+// Re-export all public types
+export type {
+	BaseTelemetryEvent,
+	EntityPattern,
+	ExternalCallEvent,
+	ExternalEvents,
+	HttpEvents,
+	HttpRequestEvent,
+	JobDispatchEvent,
+	JobEndEvent,
+	JobEvents,
+	JobStartEvent,
+	JobStepEvent,
+	PresetEvents,
+	Telemetry,
+	TelemetryConfig,
+	TraceContext,
+} from "./types.ts";
+
+// Re-export utilities
+export { generateSpanId, generateTraceId } from "./ids.ts";
+export { extractEntities, extractEntitiesFromEvent } from "./entities.ts";
+export { formatTraceparent, parseTraceparent } from "./traceparent.ts";
+export type { Traceparent } from "./traceparent.ts";

package/src/traceparent.ts

@@ -0,0 +1,56 @@
+/**
+ * W3C Trace Context — traceparent header parsing and formatting.
+ *
+ * Implements the `traceparent` header format defined in
+ * https://www.w3.org/TR/trace-context/#traceparent-header
+ *
+ * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
+ * Example: 00-4bf92f3577b86cd56163f2543210c4a0-00f067aa0ba902b7-01
+ */
+
+/** Parsed representation of a `traceparent` header. */
+export interface Traceparent {
+	version: string
+	traceId: string
+	parentId: string
+	traceFlags: string
+}
+
+const TRACEPARENT_RE = /^([\da-f]{2})-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})$/
+const ALL_ZEROS_32 = '0'.repeat(32)
+const ALL_ZEROS_16 = '0'.repeat(16)
+
+/**
+ * Parse a `traceparent` header value.
+ *
+ * Returns the parsed components, or `null` if the header is missing,
+ * malformed, or violates the W3C spec (e.g. all-zero trace-id/parent-id).
+ */
+export function parseTraceparent(header: string | undefined | null): Traceparent | null {
+	if (!header) return null
+
+	const match = TRACEPARENT_RE.exec(header.trim().toLowerCase())
+	if (!match) return null
+
+	// Captures are guaranteed by the regex match above
+	const version = match[1] as string
+	const traceId = match[2] as string
+	const parentId = match[3] as string
+	const traceFlags = match[4] as string
+
+	// W3C spec: all-zero trace-id and parent-id are invalid
+	if (traceId === ALL_ZEROS_32 || parentId === ALL_ZEROS_16) return null
+
+	return { version, traceId, parentId, traceFlags }
+}
+
+/**
+ * Format a `traceparent` header value from components.
+ *
+ * @param traceId  32-char lowercase hex trace ID
+ * @param parentId 16-char lowercase hex parent/span ID
+ * @param flags    2-char hex trace flags (default: "01" = sampled)
+ */
+export function formatTraceparent(traceId: string, parentId: string, flags = '01'): string {
+	return `00-${traceId}-${parentId}-${flags}`
+}

package/src/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Type definitions for agent-telemetry.
+ *
+ * Provides base event types, preset event families (HttpEvents, JobEvents,
+ * ExternalEvents), configuration interfaces, and the Telemetry handle type.
+ */
+
+// ============================================================================
+// Base Event
+// ============================================================================
+
+/** Fields present on every telemetry event after emission. */
+export interface BaseTelemetryEvent {
+	kind: string;
+	traceId: string;
+	timestamp?: string;
+}
+
+// ============================================================================
+// Preset Event Families
+// ============================================================================
+
+export interface HttpRequestEvent extends BaseTelemetryEvent {
+	kind: "http.request";
+	method: string;
+	path: string;
+	status: number;
+	duration_ms: number;
+	entities?: Record<string, string>;
+	error?: string;
+}
+
+/** All HTTP-related events. */
+export type HttpEvents = HttpRequestEvent;
+
+export interface JobStartEvent extends BaseTelemetryEvent {
+	kind: "job.start";
+	spanId: string;
+	functionId: string;
+	runId?: string;
+	entities?: Record<string, string>;
+}
+
+export interface JobEndEvent extends BaseTelemetryEvent {
+	kind: "job.end";
+	spanId: string;
+	functionId: string;
+	runId?: string;
+	duration_ms: number;
+	status: "success" | "error";
+	error?: string;
+}
+
+export interface JobDispatchEvent extends BaseTelemetryEvent {
+	kind: "job.dispatch";
+	parentSpanId: string;
+	eventName: string;
+	entities?: Record<string, string>;
+}
+
+export interface JobStepEvent extends BaseTelemetryEvent {
+	kind: "job.step";
+	spanId: string;
+	stepId: string;
+	duration_ms: number;
+	status: "success" | "error";
+}
+
+/** All background job events. */
+export type JobEvents = JobStartEvent | JobEndEvent | JobDispatchEvent | JobStepEvent;
+
+export interface ExternalCallEvent extends BaseTelemetryEvent {
+	kind: "external.call";
+	spanId: string;
+	service: string;
+	operation: string;
+	duration_ms: number;
+	status: "success" | "error";
+}
+
+/** All external service call events. */
+export type ExternalEvents = ExternalCallEvent;
+
+/** Union of all preset event types. */
+export type PresetEvents = HttpEvents | JobEvents | ExternalEvents;
+
+// ============================================================================
+// Entity Extraction
+// ============================================================================
+
+/** A pattern for extracting entity IDs from URL path segments. */
+export interface EntityPattern {
+	/** The URL path segment that precedes the entity ID (e.g. "users"). */
+	segment: string;
+	/** The key name for the extracted ID (e.g. "userId"). */
+	key: string;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/** Configuration for the telemetry writer. */
+export interface TelemetryConfig {
+	/** Directory for log files. Default: "logs" relative to cwd. */
+	logDir?: string;
+	/** Log filename (without directory). Default: "telemetry.jsonl". */
+	filename?: string;
+	/** Max file size in bytes before rotation. Default: 5_000_000 (5MB). */
+	maxSize?: number;
+	/** Number of rotated backup files to keep. Default: 3. */
+	maxBackups?: number;
+	/** Prefix for console.log fallback lines. Default: "[TEL]". */
+	prefix?: string;
+	/** Guard function — return false to disable emission. Default: () => true. */
+	isEnabled?: () => boolean;
+}
+
+/** The telemetry handle returned by createTelemetry(). */
+export interface Telemetry<TEvent extends BaseTelemetryEvent = PresetEvents> {
+	/** Emit a telemetry event. Synchronous. Never throws. */
+	emit: (event: TEvent) => void;
+}
+
+// ============================================================================
+// Trace Context
+// ============================================================================
+
+/** Trace context passed between HTTP requests and background jobs. */
+export interface TraceContext {
+	traceId: string;
+	parentSpanId: string;
+	traceFlags?: string;
+}

package/src/writer.ts

@@ -0,0 +1,131 @@
+/**
+ * JSONL Writer
+ *
+ * Writes telemetry events to a JSONL file with size-based rotation.
+ * Auto-detects runtime: uses filesystem when available (Node/Bun),
+ * falls back to console.log with a configurable prefix (Cloudflare Workers).
+ *
+ * The writer is initialized asynchronously (runtime probe), but the returned
+ * write function is synchronous and never throws.
+ */
+
+export interface WriterConfig {
+	logDir: string
+	filename: string
+	maxSize: number
+	maxBackups: number
+	prefix: string
+}
+
+export interface Writer {
+	write: (line: string) => void
+}
+
+const DEFAULTS: WriterConfig = {
+	logDir: 'logs',
+	filename: 'telemetry.jsonl',
+	maxSize: 5_000_000,
+	maxBackups: 3,
+	prefix: '[TEL]',
+}
+
+/**
+ * Create a writer that appends JSONL lines to a file with rotation.
+ * Falls back to console.log if the filesystem is unavailable.
+ */
+export async function createWriter(config?: Partial<WriterConfig>): Promise<Writer> {
+	const cfg: WriterConfig = {
+		logDir: config?.logDir ?? DEFAULTS.logDir,
+		filename: config?.filename ?? DEFAULTS.filename,
+		maxSize: config?.maxSize ?? DEFAULTS.maxSize,
+		maxBackups: config?.maxBackups ?? DEFAULTS.maxBackups,
+		prefix: config?.prefix ?? DEFAULTS.prefix,
+	}
+	const writeToConsole = (line: string): void => {
+		// biome-ignore lint/suspicious/noConsole: intentional fallback for runtimes without filesystem
+		console.log(`${cfg.prefix} ${line}`)
+	}
+
+	try {
+		const fs = await import('node:fs')
+		const path = await import('node:path')
+
+		const logDir = path.resolve(cfg.logDir)
+		const logFile = path.join(logDir, cfg.filename)
+
+		// Probe: verify filesystem actually works
+		// (Cloudflare's nodejs_compat stubs succeed silently)
+		fs.mkdirSync(logDir, { recursive: true })
+		if (!fs.existsSync(logDir)) {
+			throw new Error('Filesystem probe failed')
+		}
+
+		let useConsoleFallback = false
+
+		const rotate = (): void => {
+			if (!fs.existsSync(logFile)) return
+
+			if (cfg.maxBackups <= 0) {
+				fs.unlinkSync(logFile)
+				return
+			}
+
+			const oldestBackup = `${logFile}.${cfg.maxBackups}`
+			if (fs.existsSync(oldestBackup)) {
+				fs.unlinkSync(oldestBackup)
+			}
+
+			for (let i = cfg.maxBackups - 1; i >= 1; i--) {
+				const from = `${logFile}.${i}`
+				const to = `${logFile}.${i + 1}`
+				if (fs.existsSync(from)) {
+					fs.renameSync(from, to)
+				}
+			}
+
+			fs.renameSync(logFile, `${logFile}.1`)
+		}
+
+		return {
+			write(line: string) {
+				if (useConsoleFallback) {
+					writeToConsole(line)
+					return
+				}
+
+				try {
+					const lineWithNewline = `${line}\n`
+					const incomingSize = Buffer.byteLength(lineWithNewline)
+					let currentSize = 0
+
+					try {
+						currentSize = fs.statSync(logFile).size
+					} catch (err) {
+						const isEnoent =
+							typeof err === 'object' &&
+							err !== null &&
+							'code' in err &&
+							(err as { code?: unknown }).code === 'ENOENT'
+						if (!isEnoent) {
+							throw err
+						}
+					}
+
+					if (cfg.maxSize > 0 && currentSize + incomingSize > cfg.maxSize) {
+						rotate()
+					}
+
+					fs.appendFileSync(logFile, lineWithNewline)
+				} catch {
+					useConsoleFallback = true
+					writeToConsole(line)
+				}
+			},
+		}
+	} catch {
+		// Import failed or filesystem probe failed — console fallback
+		return {
+			write: writeToConsole,
+		}
+	}
+}