@aryasaatvik/motel 0.3.0

package/src/motel.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test"
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+import rootPackage from "../package.json" with { type: "json" }
+
+const expectedVersion = `${rootPackage.version}\n`
+
+const motel = async (...args: ReadonlyArray<string>) => {
+	const child = Bun.spawn({
+		cmd: [process.execPath, "run", "src/motel.ts", ...args],
+		cwd: process.cwd(),
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [exitCode, stdout, stderr] = await Promise.all([
+		child.exited,
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+	])
+	return { exitCode, stdout, stderr }
+}
+
+const assertMcpStartsCleanly = async (cmd: ReadonlyArray<string>, cwd = process.cwd()) => {
+	const process = Bun.spawn({ cmd: [...cmd], cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" })
+	const earlyExit = await Promise.race([process.exited.then((exitCode) => ({ exitCode })), Bun.sleep(500).then(() => null)])
+	expect(earlyExit).toBeNull()
+	process.kill()
+	await process.exited
+	expect(await new Response(process.stdout).text()).toBe("")
+	expect(await new Response(process.stderr).text()).toBe("")
+}
+
+describe("motel command tree", () => {
+	test("renders native root and subcommand help", async () => {
+		const root = await motel("--help")
+		expect(root.exitCode).toBe(0)
+		expect(root.stdout).toContain("motel <subcommand>")
+		expect(root.stdout).not.toContain("bun run cli")
+		expect(root.stderr).toBe("")
+
+		const leaf = await motel("trace-stats", "--help")
+		expect(leaf.exitCode).toBe(0)
+		expect(leaf.stdout).toContain("motel trace-stats")
+		expect(leaf.stderr).toBe("")
+
+		const service = await motel("service", "install", "--help")
+		expect(service.exitCode).toBe(0)
+		expect(service.stdout).toContain("motel service install")
+		expect(service.stdout).toContain("--replace")
+		expect(service.stderr).toBe("")
+	})
+
+	test("keeps both version aliases to the bare package version", async () => {
+		for (const flag of ["--version", "-v"]) {
+			const result = await motel(flag)
+			expect(result.exitCode).toBe(0)
+			expect(result.stdout).toBe(expectedVersion)
+			expect(result.stderr).toBe("")
+		}
+	})
+
+	test("renders focused usage for invalid command and enum input", async () => {
+		const unknown = await motel("not-a-command")
+		expect(unknown.exitCode).toBe(1)
+		expect(unknown.stdout).toContain("motel <subcommand>")
+		expect(unknown.stderr).toContain('Unknown subcommand "not-a-command"')
+
+		const invalidAggregation = await motel("trace-stats", "service", "nope")
+		expect(invalidAggregation.exitCode).toBe(1)
+		expect(invalidAggregation.stdout).toContain("motel trace-stats")
+		expect(invalidAggregation.stderr).toContain('Invalid value for argument <aggregation>: "nope"')
+
+		const invalidFilter = await motel("search-traces", "attr.bad")
+		expect(invalidFilter.exitCode).toBe(1)
+		expect(invalidFilter.stdout).toContain("motel search-traces")
+		expect(invalidFilter.stderr).toContain("attribute filters must use attr.<key>=<value>")
+	})
+
+	test("prints JSON command output without CLI banners", async () => {
+		const result = await motel("endpoints")
+		expect(result.exitCode).toBe(0)
+		expect(result.stderr).toBe("")
+		expect(JSON.parse(result.stdout)).toMatchObject({
+			baseUrl: "http://127.0.0.1:27686",
+			queryUrl: "http://127.0.0.1:27686",
+		})
+	})
+
+	test("keeps the MCP command path protocol-clean", async () => {
+		await assertMcpStartsCleanly([process.execPath, "run", "src/motel.ts", "mcp"])
+		await assertMcpStartsCleanly([process.execPath, "run", "src/mcp.ts"])
+	})
+
+	test("keeps the foreground server alive until it receives a signal", async () => {
+		const runtimeDir = fs.mkdtempSync(path.join(os.tmpdir(), "motel-server-cli-"))
+		const port = 30000 + Math.floor(Math.random() * 1000)
+		const server = Bun.spawn({
+			cmd: [process.execPath, "run", "src/motel.ts", "server"],
+			cwd: process.cwd(),
+			env: {
+				...process.env,
+				MOTEL_RUNTIME_DIR: runtimeDir,
+				MOTEL_OTEL_DB_PATH: path.join(runtimeDir, "telemetry.sqlite"),
+				MOTEL_OTEL_PORT: String(port),
+				MOTEL_OTEL_BASE_URL: `http://127.0.0.1:${port}`,
+				MOTEL_OTEL_QUERY_URL: `http://127.0.0.1:${port}`,
+			},
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		try {
+			let healthy = false
+			for (let attempt = 0; attempt < 40; attempt++) {
+				try {
+					const response = await fetch(`http://127.0.0.1:${port}/api/health`)
+					healthy = response.ok
+				} catch {
+					await Bun.sleep(25)
+				}
+				if (healthy) break
+			}
+			expect(healthy).toBe(true)
+			expect(await Promise.race([server.exited, Bun.sleep(50).then(() => null)])).toBeNull()
+		} finally {
+			server.kill("SIGTERM")
+			await server.exited
+			fs.rmSync(runtimeDir, { recursive: true, force: true })
+		}
+	})
+
+	test("runs the packed motel binary from an isolated temporary prefix", async () => {
+		const temporaryPrefix = fs.mkdtempSync(path.join(os.tmpdir(), "motel-installed-cli-"))
+		try {
+			const pack = Bun.spawn({
+				cmd: ["bun", "pm", "pack", "--destination", temporaryPrefix, "--quiet"],
+				cwd: process.cwd(),
+				stdout: "pipe",
+				stderr: "pipe",
+			})
+			expect(await pack.exited, await new Response(pack.stderr).text()).toBe(0)
+			const tarball = fs.readdirSync(temporaryPrefix).find((entry) => entry.endsWith(".tgz"))
+			expect(tarball).toBeDefined()
+
+			const prefix = path.join(temporaryPrefix, "prefix")
+			fs.mkdirSync(prefix)
+			const install = Bun.spawn({
+				cmd: ["bun", "install", "--cwd", prefix, path.join(temporaryPrefix, tarball!)],
+				cwd: process.cwd(),
+				stdout: "pipe",
+				stderr: "pipe",
+			})
+			expect(await install.exited, await new Response(install.stderr).text()).toBe(0)
+
+			const installed = Bun.spawn({
+				cmd: [path.join(prefix, "node_modules/.bin/motel"), "--version"],
+				cwd: prefix,
+				stdout: "pipe",
+				stderr: "pipe",
+			})
+			const [exitCode, stdout, stderr] = await Promise.all([
+				installed.exited,
+				new Response(installed.stdout).text(),
+				new Response(installed.stderr).text(),
+			])
+			expect(exitCode).toBe(0)
+			expect(stdout).toBe(expectedVersion)
+			expect(stderr).toBe("")
+			await assertMcpStartsCleanly([path.join(prefix, "node_modules/.bin/motel"), "mcp"], prefix)
+			await assertMcpStartsCleanly([path.join(prefix, "node_modules/.bin/motel-mcp")], prefix)
+		} finally {
+			fs.rmSync(temporaryPrefix, { recursive: true, force: true })
+		}
+	})
+})

package/src/motel.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+
+import { BunRuntime, BunServices } from "@effect/platform-bun"
+import { Console, Effect, Layer } from "effect"
+import { CliOutput, Command, Flag } from "effect/unstable/cli"
+import packageJson from "../package.json" with { type: "json" }
+import { queryCommands } from "./cli.js"
+import { applyManagedDaemonEnv } from "./daemon.js"
+import { createLaunchAgentManager, createMotelLifecycle } from "./launchAgent.js"
+
+const json = (value: unknown) => Console.log(JSON.stringify(value, null, 2))
+
+const tui = Command.make("tui", {}, () =>
+	Effect.gen(function*() {
+		yield* applyManagedDaemonEnv
+		yield* Effect.promise(() => import("./index.js"))
+	}),
+).pipe(Command.withDescription("Launch the telemetry TUI"))
+
+const lifecycle = createMotelLifecycle()
+
+const daemon = Command.make("daemon", {}, () =>
+	lifecycle.start.pipe(Effect.andThen(json)),
+).pipe(
+	Command.withAlias("start"),
+	Command.withDescription("Ensure the managed telemetry daemon is running"),
+)
+
+const status = Command.make("status", {}, () =>
+	lifecycle.status.pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Print managed daemon status"))
+
+const stop = Command.make("stop", {}, () =>
+	lifecycle.stop.pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Stop the managed telemetry daemon"))
+
+const restart = Command.make("restart", {}, () =>
+	lifecycle.restart.pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Restart only the managed telemetry daemon"))
+
+const serviceManager = createLaunchAgentManager()
+const serviceInstall = Command.make("install", { replace: Flag.boolean("replace") }, ({ replace }) =>
+	serviceManager.install(replace).pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Install the per-user Motel LaunchAgent"))
+const serviceStatus = Command.make("status", {}, () =>
+	serviceManager.status.pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Print per-user LaunchAgent and daemon status"))
+const serviceUninstall = Command.make("uninstall", {}, () =>
+	serviceManager.uninstall.pipe(Effect.andThen(json)),
+).pipe(Command.withDescription("Unload and remove the per-user Motel LaunchAgent definition"))
+const service = Command.make("service", {}, () =>
+	Effect.fail(new Error("Specify service install, service status, or service uninstall.")),
+).pipe(
+	Command.withDescription("Manage the per-user Motel LaunchAgent"),
+	Command.withSubcommands([serviceInstall, serviceStatus, serviceUninstall]),
+)
+
+const server = Command.make("server", {}, () =>
+	Effect.gen(function*() {
+		yield* applyManagedDaemonEnv
+		yield* Effect.promise(() => import("./server.js"))
+	}),
+).pipe(Command.withDescription("Run the telemetry server in the foreground"))
+
+const mcp = Command.make("mcp", {}, () =>
+	Effect.promise(() => import("./mcp.js")),
+).pipe(Command.withDescription("Run the Motel MCP server over stdio"))
+
+const motel = Command.make("motel", {}, () =>
+	Effect.gen(function*() {
+		yield* applyManagedDaemonEnv
+		yield* Effect.promise(() => import("./index.js"))
+	}),
+).pipe(
+	Command.withDescription("Local OpenTelemetry ingest and inspection"),
+	Command.withSubcommands([tui, daemon, status, stop, restart, service, server, mcp, ...queryCommands]),
+)
+
+const defaultFormatter = CliOutput.defaultFormatter()
+const output = CliOutput.layer({
+	...defaultFormatter,
+	formatVersion: (_, version) => version,
+})
+
+Command.run(motel, { version: packageJson.version }).pipe(
+	Effect.provide(Layer.mergeAll(BunServices.layer, output)),
+	BunRuntime.runMain,
+)

package/src/motelClient.ts

@@ -0,0 +1,353 @@
+import { Effect, Layer, Context } from "effect"
+import { Locator } from "./locator.js"
+
+export class MotelHttpError extends Error {
+	readonly _tag = "MotelHttpError"
+	constructor(
+		readonly status: number,
+		readonly detail: string,
+	) {
+		super(`motel returned HTTP ${status}: ${detail}`)
+	}
+}
+
+type QueryValue = string | number | boolean | null | undefined
+type Query = Readonly<Record<string, QueryValue>>
+type AttributeFilters = Readonly<Record<string, string>>
+
+const appendQuery = (url: URL, query: Query | undefined) => {
+	if (!query) return url
+	for (const [key, value] of Object.entries(query)) {
+		if (value === undefined || value === null || value === "") continue
+		url.searchParams.set(key, String(value))
+	}
+	return url
+}
+
+const appendAttributes = (url: URL, prefix: "attr" | "attrContains", attributes: AttributeFilters | undefined) => {
+	if (!attributes) return url
+	for (const [key, value] of Object.entries(attributes)) {
+		url.searchParams.set(`${prefix}.${key}`, value)
+	}
+	return url
+}
+
+const appendAllAttributes = (
+	url: URL,
+	attributes: AttributeFilters | undefined,
+	attributeContains: AttributeFilters | undefined,
+) => appendAttributes(appendAttributes(url, "attr", attributes), "attrContains", attributeContains)
+
+export type SearchTracesInput = {
+	readonly service?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
+}
+
+export type SearchSpansInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly operation?: string
+	readonly parentOperation?: string
+	readonly status?: "ok" | "error"
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
+}
+
+export type SearchLogsInput = {
+	readonly service?: string
+	readonly severity?: string
+	readonly traceId?: string
+	readonly spanId?: string
+	readonly body?: string
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
+}
+
+export type TraceStatsInput = {
+	readonly groupBy: string
+	readonly agg: "count" | "avg_duration" | "p95_duration" | "error_rate"
+	readonly service?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: AttributeFilters
+}
+
+export type LogStatsInput = {
+	readonly groupBy: string
+	readonly service?: string
+	readonly traceId?: string
+	readonly spanId?: string
+	readonly body?: string
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: AttributeFilters
+}
+
+export type FacetsInput = {
+	readonly type: "traces" | "logs"
+	readonly field: string
+	readonly key?: string
+	readonly service?: string
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export type TraceLogOptions = {
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+}
+
+export type AiCallSearchInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly text?: string
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export type AiCallStatsInput = {
+	readonly groupBy: "provider" | "model" | "functionId" | "sessionId" | "status"
+	readonly agg: "count" | "avg_duration" | "p95_duration" | "total_input_tokens" | "total_output_tokens"
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export class MotelClient extends Context.Service<
+	MotelClient,
+	{
+		readonly searchTraces: (input: SearchTracesInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchSpans: (input: SearchSpansInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTrace: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceSpans: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceLogs: (traceId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpan: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpanLogs: (spanId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchLogs: (input: SearchLogsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchAiCalls: (input: AiCallSearchInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly getAiCall: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly aiCallStats: (input: AiCallStatsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly traceStats: (input: TraceStatsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly logStats: (input: LogStatsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly facets: (input: FacetsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly services: Effect.Effect<unknown, MotelHttpError>
+		readonly health: Effect.Effect<unknown, MotelHttpError>
+		readonly docs: Effect.Effect<unknown, MotelHttpError>
+		readonly getDoc: (name: string) => Effect.Effect<string, MotelHttpError>
+		readonly openapi: Effect.Effect<unknown, MotelHttpError>
+	}
+>()("motel/MotelClient") {}
+
+export const MotelClientLive = Layer.effect(
+	MotelClient,
+	Effect.gen(function* () {
+		const locator = yield* Locator
+
+		const get = <A = unknown>(
+			path: string,
+			query?: Query,
+			attributes?: AttributeFilters,
+			attributeContains?: AttributeFilters,
+		) =>
+			Effect.gen(function* () {
+				const { url } = yield* Effect.mapError(
+					locator.resolve,
+					(err) => new MotelHttpError(0, err.message),
+				)
+				const target = appendAllAttributes(appendQuery(new URL(path, url), query), attributes, attributeContains)
+				return yield* Effect.tryPromise({
+					try: async () => {
+						const res = await fetch(target, { signal: AbortSignal.timeout(5000) })
+						const body = (await res.json().catch(() => ({ error: "invalid json" }))) as A
+						if (!res.ok) throw new MotelHttpError(res.status, JSON.stringify(body))
+						return body
+					},
+					catch: (err) =>
+						err instanceof MotelHttpError ? err : new MotelHttpError(0, (err as Error).message),
+				}).pipe(
+					Effect.tapError((err) => (err.status === 0 ? locator.invalidate : Effect.void)),
+				)
+			})
+
+		return {
+			searchTraces: (input) =>
+				get("/api/traces/search", {
+					service: input.service,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+					cursor: input.cursor,
+				}, input.attributes, input.attributeContains),
+
+			searchSpans: (input) =>
+				get("/api/spans/search", {
+					service: input.service,
+					traceId: input.traceId,
+					operation: input.operation,
+					parentOperation: input.parentOperation,
+					status: input.status,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes, input.attributeContains),
+
+			getTrace: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}`),
+
+			getTraceSpans: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}/spans`),
+
+			getTraceLogs: (traceId, options) =>
+				get(`/api/traces/${encodeURIComponent(traceId)}/logs`, {
+					lookback: options.lookback,
+					limit: options.limit,
+					cursor: options.cursor,
+				}),
+
+			getSpan: (spanId) => get(`/api/spans/${encodeURIComponent(spanId)}`),
+
+			getSpanLogs: (spanId, options) =>
+				get(`/api/spans/${encodeURIComponent(spanId)}/logs`, {
+					lookback: options.lookback,
+					limit: options.limit,
+					cursor: options.cursor,
+				}),
+
+			searchLogs: (input) =>
+				get("/api/logs/search", {
+					service: input.service,
+					severity: input.severity,
+					traceId: input.traceId,
+					spanId: input.spanId,
+					body: input.body,
+					lookback: input.lookback,
+					limit: input.limit,
+					cursor: input.cursor,
+				}, input.attributes, input.attributeContains),
+
+			searchAiCalls: (input) =>
+				get("/api/ai/calls", {
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					text: input.text,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			getAiCall: (spanId) => get(`/api/ai/calls/${encodeURIComponent(spanId)}`),
+
+			aiCallStats: (input) =>
+				get("/api/ai/stats", {
+					groupBy: input.groupBy,
+					agg: input.agg,
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			traceStats: (input) =>
+				get("/api/traces/stats", {
+					groupBy: input.groupBy,
+					agg: input.agg,
+					service: input.service,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes),
+
+			logStats: (input) =>
+				get("/api/logs/stats", {
+					groupBy: input.groupBy,
+					agg: "count",
+					service: input.service,
+					traceId: input.traceId,
+					spanId: input.spanId,
+					body: input.body,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes),
+
+			facets: (input) =>
+				get("/api/facets", {
+					type: input.type,
+					field: input.field,
+					key: input.key,
+					service: input.service,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			services: get("/api/services"),
+
+			health: get("/api/health"),
+
+			docs: get("/api/docs"),
+
+			getDoc: (name) =>
+				Effect.gen(function* () {
+					const { url } = yield* Effect.mapError(locator.resolve, (err) => new MotelHttpError(0, err.message))
+					return yield* Effect.tryPromise({
+						try: async () => {
+							const res = await fetch(new URL(`/api/docs/${encodeURIComponent(name)}`, url), {
+								signal: AbortSignal.timeout(5000),
+							})
+							const body = await res.text()
+							if (!res.ok) throw new MotelHttpError(res.status, body)
+							return body
+						},
+						catch: (err) =>
+							err instanceof MotelHttpError ? err : new MotelHttpError(0, (err as Error).message),
+					}).pipe(Effect.tapError((err) => (err.status === 0 ? locator.invalidate : Effect.void)))
+				}),
+
+			openapi: get("/openapi.json"),
+		}
+	}),
+)

package/src/opentui-jsx.d.ts

@@ -0,0 +1,11 @@
+import type { Key } from "react"
+
+// TypeScript 6 does not preserve React's inherited `key` attribute through
+// OpenTUI's JSX runtime declarations for custom components.
+declare module "@opentui/react/jsx-runtime" {
+	namespace JSX {
+		interface IntrinsicAttributes {
+			readonly key?: Key | null | undefined
+		}
+	}
+}

package/src/otlp.test.ts

@@ -0,0 +1,65 @@
+import rootModule from "@opentelemetry/otlp-transformer/build/esm/generated/root.js"
+import { describe, expect, test } from "bun:test"
+import { normalizeOtlpBinaryId } from "./otlp.ts"
+import { decodeProtobufLogs, decodeProtobufTraces } from "./otlpProtobuf.ts"
+
+describe("normalizeOtlpBinaryId", () => {
+	test("normalizes hex and canonical base64 IDs", () => {
+		expect(normalizeOtlpBinaryId("0123456789ABCDEF", 8)).toBe("0123456789abcdef")
+		expect(normalizeOtlpBinaryId(Buffer.from("0123456789abcdef", "hex").toString("base64"), 8)).toBe("0123456789abcdef")
+		expect(normalizeOtlpBinaryId(Buffer.from("0123456789abcdef0123456789abcdef", "hex").toString("base64"), 16)).toBe("0123456789abcdef0123456789abcdef")
+	})
+
+	test("preserves non-standard human-readable IDs", () => {
+		expect(normalizeOtlpBinaryId("ai-stream-1", 8)).toBe("ai-stream-1")
+		expect(normalizeOtlpBinaryId("ai-stream-2", 8)).toBe("ai-stream-2")
+		expect(normalizeOtlpBinaryId("trace-ai", 16)).toBe("trace-ai")
+	})
+
+	test("returns null for absent IDs", () => {
+		expect(normalizeOtlpBinaryId(null, 16)).toBeNull()
+		expect(normalizeOtlpBinaryId(undefined, 8)).toBeNull()
+		expect(normalizeOtlpBinaryId("", 16)).toBeNull()
+	})
+})
+
+const root = rootModule as unknown as {
+	readonly opentelemetry: {
+		readonly proto: {
+			readonly collector: {
+				readonly trace: { readonly v1: { readonly ExportTraceServiceRequest: { encode: (message: unknown) => { finish: () => Uint8Array } } } }
+				readonly logs: { readonly v1: { readonly ExportLogsServiceRequest: { encode: (message: unknown) => { finish: () => Uint8Array } } } }
+			}
+		}
+	}
+}
+
+describe("protobuf OTLP decoders", () => {
+	test("decodes traces into the JSON ingest shape", () => {
+		const encoded = root.opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest.encode({
+			resourceSpans: [{
+				resource: { attributes: [{ key: "service.name", value: { stringValue: "proto-svc" } }] },
+				scopeSpans: [{ spans: [{
+					traceId: Buffer.from("0123456789abcdef0123456789abcdef", "hex"),
+					spanId: Buffer.from("0123456789abcdef", "hex"),
+					name: "op",
+					startTimeUnixNano: 1,
+					endTimeUnixNano: 2,
+				}] }],
+			}],
+		}).finish()
+		const span = decodeProtobufTraces(encoded).resourceSpans?.[0]?.scopeSpans?.[0]?.spans?.[0]
+		expect(span?.name).toBe("op")
+		expect(normalizeOtlpBinaryId(span?.traceId, 16)).toBe("0123456789abcdef0123456789abcdef")
+		expect(normalizeOtlpBinaryId(span?.spanId, 8)).toBe("0123456789abcdef")
+	})
+
+	test("decodes logs into the JSON ingest shape", () => {
+		const encoded = root.opentelemetry.proto.collector.logs.v1.ExportLogsServiceRequest.encode({
+			resourceLogs: [{ scopeLogs: [{ logRecords: [{ timeUnixNano: 5, severityText: "INFO", body: { stringValue: "hello" } }] }] }],
+		}).finish()
+		const record = decodeProtobufLogs(encoded).resourceLogs?.[0]?.scopeLogs?.[0]?.logRecords?.[0]
+		expect(record?.severityText).toBe("INFO")
+		expect(record?.body?.stringValue).toBe("hello")
+	})
+})