@obsunified/collector 2.0.1

package/src/framework/collector.ts

@@ -0,0 +1,467 @@
+import type { StoredSpan, UsageEventRecord } from "@obsunified/types";
+import { getConfiguredRetentionHours } from "@obsunified/types/constants";
+import type { MiddlewareHandler } from "hono";
+import { Hono } from "hono";
+import { AIStore } from "../lib/ai-store";
+import { runAllDueAnalyses } from "../lib/analyses-runner";
+import { AnalysesStore } from "../lib/analyses-store";
+import { LogsStore } from "../lib/logs-store";
+import { MetricsStore } from "../lib/metrics-store";
+import { aggregatePropagation } from "../lib/propagation-metric";
+import { D1Adapter, dialectFor, type SqlDb, sqlDbFor } from "../lib/sql-db";
+import { TelemetryStore } from "../lib/store";
+import { UsageStore } from "../lib/usage-store";
+import type { CollectorEnv, CollectorRouteContext } from "./env";
+import {
+	type ChildSpanRunner,
+	consoleLogger,
+	type Logger,
+	passthroughChildSpan,
+} from "./logger";
+
+/**
+ * Factory that materializes an `SqlDb` for the request's `env`. Per-request
+ * because Cloudflare's `D1Database` binding only exists once `env` is in
+ * scope; on Workers this is essentially free since `D1Adapter` is a thin
+ * wrapper. Hosts override this to inject a fake DB in tests, a different
+ * engine in alternate runtimes, or a tracing wrapper at the storage layer.
+ */
+export type SqlDbFactory = (env: CollectorEnv) => SqlDb;
+
+const defaultSqlDbFactory: SqlDbFactory = (env) => new D1Adapter(env.DB);
+
+export interface SpanProcessorPlugin {
+	name: string;
+	process(
+		spans: StoredSpan[],
+		context: CollectorRouteContext,
+	): Promise<StoredSpan[]> | StoredSpan[];
+}
+
+export interface UsageEventProcessorPlugin {
+	name: string;
+	process(
+		events: UsageEventRecord[],
+		context: CollectorRouteContext,
+	): Promise<UsageEventRecord[]> | UsageEventRecord[];
+}
+
+export interface CollectorPluginContext {
+	addSpanProcessor(processor: SpanProcessorPlugin): void;
+	addUsageEventProcessor(processor: UsageEventProcessorPlugin): void;
+	getRegisteredPluginNames(): string[];
+}
+
+export interface CollectorPlugin {
+	name: string;
+	register(
+		app: Hono<{ Bindings: CollectorEnv }>,
+		context: CollectorRuntime,
+	): void;
+}
+
+export interface CollectorAuthConfig {
+	/** Single middleware applied to both /v1/* (ingest) and /internal/* (query) routes */
+	// biome-ignore lint/suspicious/noExplicitAny: Hono generic middleware variables require any for contravariant compatibility
+	middleware?: MiddlewareHandler<{ Bindings: CollectorEnv; Variables: any }>;
+	/** @deprecated Use middleware instead. Ingest-only auth for /v1/* routes. */
+	// biome-ignore lint/suspicious/noExplicitAny: Hono generic middleware variables require any for contravariant compatibility
+	ingest?: MiddlewareHandler<{ Bindings: CollectorEnv; Variables: any }>;
+	/** @deprecated Use middleware instead. Query-only auth for /internal/* routes. */
+	// biome-ignore lint/suspicious/noExplicitAny: Hono generic middleware variables require any for contravariant compatibility
+	query?: MiddlewareHandler<{ Bindings: CollectorEnv; Variables: any }>;
+}
+
+export interface CollectorConfig {
+	plugins: CollectorPlugin[];
+	auth?: CollectorAuthConfig;
+	/** Comma-separated allowed origins for CORS on ingest endpoints */
+	allowedOrigins?: string;
+	/** Register dashboard auth routes and middleware */
+	dashboardAuth?: {
+		// biome-ignore lint/suspicious/noExplicitAny: Hono generic middleware variables require any for contravariant compatibility
+		middleware: MiddlewareHandler<{ Bindings: CollectorEnv; Variables: any }>;
+		registerRoutes: (app: Hono<{ Bindings: CollectorEnv }>) => void;
+	};
+	/**
+	 * Pluggable structured logger. Defaults to console output. Pass a logger
+	 * from `@obsunified/telemetry-sdk` to ship the collector's own log output as
+	 * OTLP — see apps/collector/SELF_INSTRUMENTATION.md.
+	 */
+	logger?: Logger;
+	/**
+	 * Wraps async work in a child span on the active request span. Wire this
+	 * to `@obsunified/telemetry-sdk`'s `withChildSpan` from the worker entrypoint to
+	 * surface LLM hops + DB-heavy paths as nested spans. Defaults to
+	 * pass-through.
+	 */
+	withChildSpan?: ChildSpanRunner;
+	/**
+	 * RFC 0008 — override the storage adapter. Per-request factory because
+	 * `env.DB` only exists once a request lands. Defaults to wrapping
+	 * `env.DB` in `D1Adapter`. Override in tests (use `MemSqlDb`) or to add
+	 * a tracing layer at the storage seam.
+	 */
+	sqlDb?: SqlDbFactory;
+}
+
+export class CollectorRuntime implements CollectorPluginContext {
+	private readonly spanProcessors: SpanProcessorPlugin[] = [];
+	private readonly usageEventProcessors: UsageEventProcessorPlugin[] = [];
+	private readonly plugins: string[] = [];
+	private readonly sqlDbFactory: SqlDbFactory;
+	readonly logger: Logger;
+	readonly withChildSpan: ChildSpanRunner;
+
+	constructor(
+		logger: Logger = consoleLogger,
+		withChildSpan: ChildSpanRunner = passthroughChildSpan,
+		sqlDbFactory: SqlDbFactory = defaultSqlDbFactory,
+	) {
+		this.logger = logger;
+		this.withChildSpan = withChildSpan;
+		this.sqlDbFactory = sqlDbFactory;
+	}
+
+	/**
+	 * Materialize an `SqlDb` for this request. Stores will accept this
+	 * directly once Phase 1.5 of RFC 0008 lands; until then plugins that
+	 * want to bypass `c.env.DB` can call this to opt in early.
+	 */
+	getSqlDb(env: CollectorEnv): SqlDb {
+		return this.sqlDbFactory(env);
+	}
+
+	registerPlugin(plugin: CollectorPlugin): void {
+		this.plugins.push(plugin.name);
+	}
+
+	addSpanProcessor(processor: SpanProcessorPlugin): void {
+		this.spanProcessors.push(processor);
+	}
+
+	addUsageEventProcessor(processor: UsageEventProcessorPlugin): void {
+		this.usageEventProcessors.push(processor);
+	}
+
+	getRegisteredPluginNames(): string[] {
+		return [...this.plugins];
+	}
+
+	createRouteContext(
+		env: CollectorEnv,
+		hono: CollectorRouteContext["hono"],
+	): CollectorRouteContext {
+		return {
+			hono,
+			env,
+			now: new Date(),
+			logger: this.logger,
+		};
+	}
+
+	createStore(env: CollectorEnv): TelemetryStore {
+		return new TelemetryStore(this.getSqlDb(env));
+	}
+
+	createUsageStore(env: CollectorEnv): UsageStore {
+		return new UsageStore(this.getSqlDb(env));
+	}
+
+	async runSpanProcessors(
+		spans: StoredSpan[],
+		context: CollectorRouteContext,
+	): Promise<StoredSpan[]> {
+		let nextSpans = spans;
+
+		for (const processor of this.spanProcessors) {
+			const inputCount = nextSpans.length;
+			nextSpans = await this.withChildSpan(
+				`process.${processor.name}`,
+				async (span) => {
+					const out = await processor.process(nextSpans, context);
+					span.setAttribute("processor.kind", "span");
+					span.setAttribute("processor.name", processor.name);
+					span.setAttribute("processor.input_count", inputCount);
+					span.setAttribute("processor.output_count", out.length);
+					if (out.length !== inputCount)
+						span.setAttribute("processor.delta_count", out.length - inputCount);
+					return out;
+				},
+			);
+		}
+
+		return nextSpans;
+	}
+
+	async runUsageEventProcessors(
+		events: UsageEventRecord[],
+		context: CollectorRouteContext,
+	): Promise<UsageEventRecord[]> {
+		let nextEvents = events;
+
+		for (const processor of this.usageEventProcessors) {
+			const inputCount = nextEvents.length;
+			nextEvents = await this.withChildSpan(
+				`process.${processor.name}`,
+				async (span) => {
+					const out = await processor.process(nextEvents, context);
+					span.setAttribute("processor.kind", "usage");
+					span.setAttribute("processor.name", processor.name);
+					span.setAttribute("processor.input_count", inputCount);
+					span.setAttribute("processor.output_count", out.length);
+					if (out.length !== inputCount)
+						span.setAttribute("processor.delta_count", out.length - inputCount);
+					return out;
+				},
+			);
+		}
+
+		return nextEvents;
+	}
+}
+
+export const createTelemetryCollectorApp = (
+	pluginsOrConfig: CollectorPlugin[] | CollectorConfig,
+): Hono<{ Bindings: CollectorEnv }> => {
+	const config: CollectorConfig = Array.isArray(pluginsOrConfig)
+		? { plugins: pluginsOrConfig }
+		: pluginsOrConfig;
+
+	const app = new Hono<{ Bindings: CollectorEnv }>();
+	const runtime = new CollectorRuntime(
+		config.logger,
+		config.withChildSpan,
+		config.sqlDb,
+	);
+
+	const allowedCorsOrigin = (origin: string | undefined, env: CollectorEnv) => {
+		const allowedOrigins = config.allowedOrigins || env.ALLOWED_ORIGINS || "";
+		const allowList = allowedOrigins
+			.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean);
+		return origin && allowList.includes(origin) ? origin : undefined;
+	};
+
+	// Health endpoint — no auth required. Includes millisecond server time so
+	// browser SDKs can estimate clock offset without relying on coarse Date.
+	app.get("/health", (c) => {
+		const allowedOrigin = allowedCorsOrigin(c.req.header("Origin"), c.env);
+		const res = c.json({ status: "ok", serverTimeMs: Date.now() });
+		if (allowedOrigin)
+			res.headers.set("Access-Control-Allow-Origin", allowedOrigin);
+		return res;
+	});
+
+	// CORS for ingest endpoints (browser SDK sends directly)
+	app.use("/v1/*", async (c, next) => {
+		const origin = c.req.header("Origin");
+		const allowedOrigin = allowedCorsOrigin(origin, c.env);
+
+		if (c.req.method === "OPTIONS") {
+			const headers: Record<string, string> = {
+				"Access-Control-Allow-Methods": "POST, OPTIONS",
+				"Access-Control-Allow-Headers":
+					"Content-Type, Authorization, X-API-Key, X-Project-Id, Cache-Control, X-Telemetry-Self, X-Obs-Interaction, X-Obs-Session-Id",
+				"Access-Control-Max-Age": "86400",
+			};
+			if (allowedOrigin) {
+				headers["Access-Control-Allow-Origin"] = allowedOrigin;
+			}
+			return new Response(null, { status: 204, headers });
+		}
+
+		await next();
+
+		// Mutate the response headers directly rather than using c.header(),
+		// which queues the header for a response Hono is about to construct —
+		// no-op when downstream middleware already finalized the response via
+		// `c.json(...)` (e.g. auth returning 401). Without this, error
+		// responses ship CORS-naked and browsers misreport them as CORS
+		// blocks instead of the underlying status.
+		if (allowedOrigin) {
+			c.res.headers.set("Access-Control-Allow-Origin", allowedOrigin);
+		}
+	});
+
+	// Ingest auth (API key) — always on /v1/* when configured.
+	if (config.auth?.middleware) {
+		app.use("/v1/*", config.auth.middleware);
+	} else if (config.auth?.ingest) {
+		// Legacy: explicit ingest-only middleware
+		app.use("/v1/*", config.auth.ingest);
+	}
+
+	// Dashboard auth (session cookie) — owns /internal/* when configured.
+	// Routes for login/check/logout are always registered so the dashboard
+	// can authenticate regardless of subsequent middleware placement.
+	if (config.dashboardAuth) {
+		config.dashboardAuth.registerRoutes(app);
+		app.use("/dashboard/*", config.dashboardAuth.middleware);
+		app.use("/internal/*", config.dashboardAuth.middleware);
+	} else if (config.auth?.middleware) {
+		// No dashboard auth configured — fall back to applying the unified
+		// ingest auth to /internal/* too, preserving the earlier single-auth
+		// contract for deployments that haven't adopted dashboard auth yet.
+		app.use("/internal/*", config.auth.middleware);
+	} else if (config.auth?.query) {
+		app.use("/internal/*", config.auth.query);
+	}
+
+	for (const plugin of config.plugins) {
+		runtime.registerPlugin(plugin);
+		plugin.register(app, runtime);
+	}
+
+	app.get("/internal/collector/plugins", (c) => {
+		return c.json({
+			plugins: runtime.getRegisteredPluginNames(),
+			timestamp: new Date().toISOString(),
+		});
+	});
+
+	return app;
+};
+
+/**
+ * Scheduled handler that purges expired telemetry and usage rows.
+ * Wire into wrangler.toml: `[triggers] crons = ["0 * * * *"]`
+ * Source: AgentOwl + DecisionOps
+ */
+export const createRetentionCleanupHandler = (options?: {
+	logger?: Logger;
+}) => {
+	const logger = options?.logger ?? consoleLogger;
+	return {
+		async scheduled(
+			_event: ScheduledEvent,
+			env: CollectorEnv,
+			_ctx: ExecutionContext,
+		): Promise<void> {
+			const db = sqlDbFor(env);
+			const telemetryStore = new TelemetryStore(db);
+			const usageStore = new UsageStore(db);
+			const logsStore = new LogsStore(db);
+			const aiStore = new AIStore(db);
+			const metricsStore = new MetricsStore(db);
+			const analysesStore = new AnalysesStore(db);
+
+			const [
+				telemetryPurged,
+				usagePurged,
+				logsPurged,
+				aiPurged,
+				metricsPurged,
+				analysesPurged,
+			] = await Promise.all([
+				telemetryStore.purgeExpired(),
+				usageStore.purgeExpired(),
+				logsStore.purgeExpired(),
+				aiStore.purgeExpired(),
+				metricsStore.purgeExpired(),
+				analysesStore.purgeExpired(),
+			]);
+
+			// RFC 0007 Phase 4.10 — profile_blobs retention. Cascade
+			// foreign key on profile_trace_index handles the join rows;
+			// we still need to delete the R2 blobs, which we do
+			// best-effort by reading the URLs first.
+			let profilesPurged = 0;
+			try {
+				const dialect = dialectFor(db);
+				const expiredProfiles = await db
+					.prepare(
+						`SELECT id, blob_url FROM profile_blobs WHERE expires_at < ${dialect.now()} LIMIT 500`,
+					)
+					.all<{ id: string; blob_url: string }>();
+				if (expiredProfiles.results.length > 0 && env.PROFILES_BUCKET) {
+					await Promise.allSettled(
+						expiredProfiles.results.map((p) =>
+							env.PROFILES_BUCKET?.delete(p.blob_url),
+						),
+					);
+				}
+				const deleted = await db
+					.prepare(
+						`DELETE FROM profile_blobs WHERE expires_at < ${dialect.now()}`,
+					)
+					.run();
+				profilesPurged = deleted.meta.changes;
+			} catch (err) {
+				logger.error("[retention-cleanup] profile purge failed", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+
+			logger.info("[retention-cleanup] purged expired rows", {
+				spans: telemetryPurged,
+				usage: usagePurged,
+				logs: logsPurged,
+				ai_calls: aiPurged,
+				metric_points: metricsPurged,
+				analysis_results: analysesPurged,
+				profile_blobs: profilesPurged,
+			});
+
+			// RFC 0004 Phase 1.8 — emit interaction_id propagation counters.
+			// Hourly aggregation rides the retention cron because cadence
+			// matches and both touch the same projects' tables.
+			try {
+				const propagation = await aggregatePropagation(db, new Date(), logger);
+				logger.info("[propagation-metric] hourly aggregation complete", {
+					projects: propagation.projects,
+					points_written: propagation.pointsWritten,
+				});
+			} catch (err) {
+				logger.error("[propagation-metric] aggregation failed", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+	};
+};
+
+/**
+ * RFC 0002 Stage 1 — run any due Analyses. Cheap to call frequently because
+ * `runAllDueAnalyses` filters by `last_run + refreshSeconds < now` before
+ * touching D1.
+ *
+ * Wire to a per-minute trigger in wrangler.toml: `crons = ["* * * * *"]`.
+ * Kept distinct from retention so the per-minute tick doesn't sweep every
+ * retention table every cycle.
+ */
+export const createAnalysesRunHandler = (options?: {
+	logger?: Logger;
+	tracer?: ChildSpanRunner;
+}) => {
+	const logger = options?.logger ?? consoleLogger;
+	const tracer = options?.tracer;
+	return {
+		async scheduled(
+			_event: ScheduledEvent,
+			env: CollectorEnv,
+			_ctx: ExecutionContext,
+		): Promise<void> {
+			try {
+				const retentionHours = getConfiguredRetentionHours(env.RETENTION_HOURS);
+				const summary = await runAllDueAnalyses({
+					env,
+					retentionHours,
+					logger,
+					tracer,
+				});
+				logger.info("[analyses] scheduled run summary", {
+					refreshed: summary.refreshed,
+					ran: summary.ran,
+					failed: summary.failed,
+					narrated: summary.narrated,
+				});
+			} catch (error) {
+				logger.error("[analyses] scheduled run failed", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		},
+	};
+};

package/src/framework/env.ts

@@ -0,0 +1,90 @@
+import type { Context, Hono } from "hono";
+import type { Logger } from "./logger";
+
+/**
+ * Collector worker bindings + env vars.
+ *
+ * Lives here, not in `@obsunified/types`, because it references Cloudflare
+ * Workers ambient globals (`D1Database`, `R2Bucket`,
+ * `DurableObjectNamespace`) that other packages — notably the web
+ * dashboard — should not transitively depend on.
+ */
+export interface CollectorEnv {
+	DB: D1Database;
+	REPLAYS_BUCKET?: R2Bucket;
+	/**
+	 * RFC 0007 — pprof profile blob storage. Keyed by `${projectId}/${ts}/${profileId}.pprof.gz`.
+	 * Same dispatch pattern as REPLAYS_BUCKET — when unbound, the receiver
+	 * falls back to filesystem under `PROFILE_BLOB_DIR` (Node) or returns
+	 * 503 (Workers).
+	 */
+	PROFILES_BUCKET?: R2Bucket;
+	/** Durable Object namespace for live-tail SSE pub/sub. Optional — when
+	 *  unbound the /internal/telemetry/tail endpoint returns 503. */
+	TAIL_HUB?: DurableObjectNamespace;
+	/** Write-only API key for SDK ingest endpoints (/v1/*) */
+	INGEST_KEY?: string;
+	/** Password for dashboard login */
+	DASHBOARD_PASSWORD?: string;
+	/** Comma-separated allowed origins for CORS (e.g. "https://my-app.com,https://staging.my-app.com") */
+	ALLOWED_ORIGINS?: string;
+	/** Set to "true" to allow unauthenticated ingest (local dev only) */
+	ALLOW_UNAUTHENTICATED?: string;
+	TELEMETRY_REDACT_FIELDS?: string;
+	/**
+	 * Local/test escape hatch for payload capture. Production should prefer the
+	 * per-project `payload_capture_enabled` flag, which defaults to false.
+	 */
+	OBS_PAYLOAD_CAPTURE_DEFAULT?: string;
+	RETENTION_HOURS?: string;
+	/**
+	 * Stage 3 narrative pipeline (RFC 0002).
+	 * Either ANTHROPIC_API_KEY or OPENAI_API_KEY enables the narrate pass +
+	 * Ask box. When neither is set, panels remain data-only.
+	 *
+	 * If both are set, OpenAI wins — configuring both is presumed deliberate.
+	 *
+	 * - ANTHROPIC_API_KEY: enables Anthropic /messages.
+	 * - OPENAI_API_KEY: enables OpenAI /chat/completions. Use OPENAI_BASE_URL
+	 *   to point at compatible endpoints (openrouter, vLLM, azure, ollama).
+	 * - NARRATIVE_MODEL: model id. Defaults are provider-specific
+	 *   (claude-haiku-4-5 for anthropic, gpt-4o-mini for openai).
+	 * - NARRATIVE_BUDGET_PER_HOUR: max narrative writes per project per hour.
+	 *   Acts as a safety rail against a flapping panel running up cost.
+	 */
+	ANTHROPIC_API_KEY?: string;
+	OPENAI_API_KEY?: string;
+	OPENAI_BASE_URL?: string;
+	NARRATIVE_MODEL?: string;
+	NARRATIVE_BUDGET_PER_HOUR?: string;
+	/**
+	 * Self-instrumentation — collector dogfoods itself into the `obs-dashboard`
+	 * project via @obsunified/telemetry-sdk. When unset, self-instrumentation is a
+	 * no-op (collector still runs normally). See apps/collector/SELF_INSTRUMENTATION.md.
+	 */
+	OBS_DASHBOARD_INGEST_KEY?: string;
+	/** Self-URL for cron-time telemetry exports (no inbound request to derive from). */
+	OBS_COLLECTOR_SELF_URL?: string;
+	/**
+	 * When "true", the worker's self-instrumentation middleware awaits its
+	 * span/log export instead of using `ctx.waitUntil`. Miniflare drops
+	 * waitUntil after the response, losing post-async telemetry. Set in
+	 * `.dev.vars` only; production CF Workers should leave this unset.
+	 */
+	OBS_SELF_AWAIT_EXPORTS?: string;
+	/** @deprecated Use INGEST_KEY instead */
+	TELEMETRY_INGEST_TOKEN?: string;
+	/** @deprecated Use INGEST_KEY instead */
+	USAGE_INGEST_TOKEN?: string;
+	/** @deprecated Use DASHBOARD_PASSWORD instead */
+	TELEMETRY_QUERY_TOKEN?: string;
+}
+
+export interface CollectorRouteContext {
+	hono: Context<{ Bindings: CollectorEnv }>;
+	env: CollectorEnv;
+	now: Date;
+	logger: Logger;
+}
+
+export type CollectorApp = Hono<{ Bindings: CollectorEnv }>;

package/src/framework/logger.ts

@@ -0,0 +1,81 @@
+/**
+ * Pluggable logger interface for the collector framework.
+ *
+ * Structurally compatible with `@obsunified/telemetry-sdk`'s `Logger`, so the worker
+ * entrypoint can do:
+ *
+ *   import { createLogger } from "@obsunified/telemetry-sdk";
+ *   createDefaultCollectorApp({ logger: createLogger("obs-collector") });
+ *
+ * The framework package intentionally does not import telemetry-sdk to keep
+ * the dependency graph one-way (SDK depends on collector contracts, not the
+ * other way around). Anything that conforms to this interface works.
+ *
+ * When no logger is supplied, the framework falls back to a console-backed
+ * logger so out-of-the-box deployments keep their existing log output.
+ */
+export interface Logger {
+	debug(message: string, attributes?: Record<string, unknown>): void;
+	info(message: string, attributes?: Record<string, unknown>): void;
+	warn(message: string, attributes?: Record<string, unknown>): void;
+	error(message: string, attributes?: Record<string, unknown>): void;
+}
+
+const formatAttrs = (attributes?: Record<string, unknown>): string => {
+	if (!attributes || Object.keys(attributes).length === 0) return "";
+	try {
+		return ` ${JSON.stringify(attributes)}`;
+	} catch {
+		return "";
+	}
+};
+
+export const consoleLogger: Logger = {
+	debug: (message, attributes) =>
+		console.debug(`${message}${formatAttrs(attributes)}`),
+	info: (message, attributes) =>
+		console.log(`${message}${formatAttrs(attributes)}`),
+	warn: (message, attributes) =>
+		console.warn(`${message}${formatAttrs(attributes)}`),
+	error: (message, attributes) =>
+		console.error(`${message}${formatAttrs(attributes)}`),
+};
+
+/**
+ * Minimal handle exposed to a `ChildSpanRunner` callback so the wrapped fn
+ * can stamp attributes / events / status onto the span as it learns about
+ * them (e.g., LLM token counts that are only known after the response).
+ *
+ * Structurally compatible with `ChildSpan` from `@obsunified/telemetry-sdk` so the
+ * worker entrypoint can pass the SDK's child span through directly without
+ * a bespoke adapter.
+ */
+export interface ChildSpanHandle {
+	setAttribute(key: string, value: unknown): void;
+	addEvent?(name: string, attributes?: Record<string, unknown>): void;
+	setStatus?(code: number, message?: string): void;
+}
+
+/**
+ * Wraps an async fn in a child span attached to the active parent span.
+ * Structurally compatible with `withChildSpan` from `@obsunified/telemetry-sdk`.
+ * Default is pass-through — wire from the worker entrypoint to enable.
+ *
+ * The wrapped fn receives a `ChildSpanHandle` so it can stamp attributes
+ * after the fact (e.g., `gen_ai.usage.input_tokens` once the LLM response
+ * arrives). When unwired, the handle's setters are no-ops.
+ */
+export type ChildSpanRunner = <T>(
+	name: string,
+	fn: (span: ChildSpanHandle) => Promise<T>,
+	attributes?: Record<string, unknown>,
+) => Promise<T>;
+
+const NOOP_HANDLE: ChildSpanHandle = {
+	setAttribute() {},
+	addEvent() {},
+	setStatus() {},
+};
+
+export const passthroughChildSpan: ChildSpanRunner = async (_name, fn) =>
+	fn(NOOP_HANDLE);