The Open Framework for Building Agents
refactor(eve): extract the local trace reader into a shared harness module (#1444)
Chad Hietala77034480eaf8
diff --git a/.changeset/shared-trace-reader.md b/.changeset/shared-trace-reader.mdnew file mode 100644index 000000000..33c4a22dc--- /dev/null+++ b/.changeset/shared-trace-reader.md@@ -0,0 +1,5 @@+---+"eve": patch+---++The local trace spool reader behind `eve traces` moved into a shared internal module; command behavior is unchanged.diff --git a/packages/eve/src/cli/commands/trace.integration.test.ts b/packages/eve/src/cli/commands/trace.integration.test.tsindex 5e80f9f5f..33f3b3ce3 100644--- a/packages/eve/src/cli/commands/trace.integration.test.ts+++ b/packages/eve/src/cli/commands/trace.integration.test.ts@@ -4,12 +4,9 @@ import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";-import {- listLocalTraces,- resolveLocalTraces,- runTraceListCommand,- runTraceShowCommand,-} from "./trace.js";+import { listLocalTraces } from "#harness/local-trace-reader.js";++import { resolveLocalTraces, runTraceListCommand, runTraceShowCommand } from "./trace.js";const TRACE_ONE = "1".repeat(32);const TRACE_TWO = "2".repeat(32);diff --git a/packages/eve/src/cli/commands/trace.ts b/packages/eve/src/cli/commands/trace.tsindex a9bd71729..eb0d0b033 100644--- a/packages/eve/src/cli/commands/trace.ts+++ b/packages/eve/src/cli/commands/trace.ts@@ -1,75 +1,28 @@-import { readdir, readFile, stat } from "node:fs/promises";-import { basename, join } from "node:path";+import { basename } from "node:path";import { formatElapsed } from "#cli/format-elapsed.js";import { createCliTheme, renderCliSection, sanitizeForTerminal } from "#cli/ui/output.js";+import type { LocalTrace, LocalTraceSpan } from "#harness/local-trace-reader.js";+import {+ compareLocalTraceSpans,+ describeLocalTraceSpan,+ listLocalTraces,+} from "#harness/local-trace-reader.js";-const TRACE_ID_PATTERN = /^[0-9a-f]{32}$/u;-const SPAN_FILE_PATTERN = /^([0-9a-f]{16})\.otlp\.json$/u;-const TRACE_DIRECTORY_SEGMENTS = [".eve", "traces", "v1"] as const;-const TRACE_DISPLAY_DIRECTORY = TRACE_DIRECTORY_SEGMENTS.join("/");-const MAX_SEGMENT_BYTES = 8 * 1024 * 1024;-const MAX_UINT64 = 18_446_744_073_709_551_615n;+const TRACE_DISPLAY_DIRECTORY = ".eve/traces/v1";interface CliTraceLogger {error(message: string): void;log(message: string): void;}-export interface LocalTraceSpan {- readonly attributes: Readonly<Record<string, unknown>>;- readonly endTimeNs: bigint;- readonly name: string;- readonly parentSpanId?: string;- readonly scope?: string;- readonly spanId: string;- readonly startTimeNs: bigint;- readonly statusCode: number;- readonly traceId: string;-}+export type { LocalTrace, LocalTraceSpan };interface SpanExtent {readonly endTimeNs: bigint;readonly startTimeNs: bigint;}-export interface LocalTrace {- readonly agentName?: string;- readonly endTimeNs: bigint;- readonly sessionId?: string;- readonly sessionIds: readonly string[];- readonly spans: readonly LocalTraceSpan[];- readonly startTimeNs: bigint;- readonly traceId: string;- readonly window?: number;-}--/** Reads valid local traces, newest first, while ignoring malformed segments. */-export async function listLocalTraces(appRoot: string): Promise<LocalTrace[]> {- const root = join(appRoot, ...TRACE_DIRECTORY_SEGMENTS);- let entries;- try {- entries = await readdir(root, { withFileTypes: true });- } catch (error) {- if (isMissing(error)) return [];- throw error;- }-- const traces: LocalTrace[] = [];- for (const entry of entries) {- if (!entry.isDirectory() || !TRACE_ID_PATTERN.test(entry.name)) continue;- const trace = await readTrace(root, entry.name).catch(() => undefined);- if (trace !== undefined) traces.push(trace);- }- return traces.sort((left, right) =>- left.startTimeNs === right.startTimeNs- ? left.traceId.localeCompare(right.traceId)- : left.startTimeNs > right.startTimeNs- ? -1- : 1,- );-}-/*** Resolves an exact trace/session id or an unambiguous prefix. One session id* can match several traces, since a long session windows into more than one.@@ -210,132 +163,6 @@ export async function runTraceShowCommand();}-async function readTrace(root: string, traceId: string): Promise<LocalTrace | undefined> {- const segmentsRoot = join(root, traceId, "segments");- let entries;- try {- entries = await readdir(segmentsRoot, { withFileTypes: true });- } catch (error) {- if (isMissing(error)) return undefined;- throw error;- }- const spans = new Map<string, LocalTraceSpan>();- for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {- if (!entry.isFile() || !SPAN_FILE_PATTERN.test(entry.name)) continue;- let content: string;- try {- const path = join(segmentsRoot, entry.name);- if ((await stat(path)).size > MAX_SEGMENT_BYTES) continue;- content = await readFile(path, "utf8");- } catch {- continue;- }- for (const span of parseSegment(content, traceId)) {- if (!spans.has(span.spanId)) spans.set(span.spanId, span);- }- }- if (spans.size === 0) return undefined;- const ordered = [...spans.values()].sort(compareSpans);- const attributes = ordered.map((span) => span.attributes);- const sessionIds = distinctAttributes(attributes, "agent.session.id");- return {- agentName: firstAttribute(attributes, "agent.name"),- endTimeNs: ordered.reduce(- (value, span) => (span.endTimeNs > value ? span.endTimeNs : value),- 0n,- ),- sessionId: sessionIds[0],- sessionIds,- spans: ordered,- startTimeNs: ordered.reduce(- (value, span) => (span.startTimeNs < value ? span.startTimeNs : value),- ordered[0]!.startTimeNs,- ),- traceId,- window: firstNumberAttribute(attributes, "agent.session.window"),- };-}--function parseSegment(content: string, expectedTraceId: string): LocalTraceSpan[] {- try {- const request = JSON.parse(content) as unknown;- if (!isRecord(request) || !Array.isArray(request.resourceSpans)) return [];- const spans: LocalTraceSpan[] = [];- for (const resource of request.resourceSpans) {- if (!isRecord(resource) || !Array.isArray(resource.scopeSpans)) continue;- for (const scoped of resource.scopeSpans) {- if (!isRecord(scoped) || !Array.isArray(scoped.spans)) continue;- const scope =- isRecord(scoped.scope) && typeof scoped.scope.name === "string"- ? scoped.scope.name- : undefined;- for (const rawSpan of scoped.spans) {- const span = parseSpan(rawSpan, expectedTraceId, scope);- if (span !== undefined) spans.push(span);- }- }- }- return spans;- } catch {- return [];- }-}--function parseSpan(- raw: unknown,- expectedTraceId: string,- scope?: string,-): LocalTraceSpan | undefined {- if (!isRecord(raw)) return undefined;- if (- raw.traceId !== expectedTraceId ||- typeof raw.spanId !== "string" ||- !/^[0-9a-f]{16}$/u.test(raw.spanId) ||- typeof raw.name !== "string"- ) {- return undefined;- }- const startTimeNs = parseNanos(raw.startTimeUnixNano);- const endTimeNs = parseNanos(raw.endTimeUnixNano);- if (startTimeNs === undefined || endTimeNs === undefined || endTimeNs < startTimeNs)- return undefined;- return {- attributes: parseAttributes(raw.attributes),- endTimeNs,- name: raw.name,- parentSpanId:- typeof raw.parentSpanId === "string" && /^[0-9a-f]{16}$/u.test(raw.parentSpanId)- ? raw.parentSpanId- : undefined,- scope,- spanId: raw.spanId,- startTimeNs,- statusCode: parseStatusCode(raw.status),- traceId: expectedTraceId,- };-}--function parseAttributes(value: unknown): Record<string, unknown> {- if (!Array.isArray(value)) return {};- const attributes: Record<string, unknown> = {};- for (const entry of value) {- if (!isRecord(entry) || typeof entry.key !== "string" || !isRecord(entry.value)) continue;- const parsed = parseAnyValue(entry.value);- if (parsed !== undefined) attributes[entry.key] = parsed;- }- return attributes;-}--function parseAnyValue(value: Record<string, unknown>): unknown {- for (const key of ["stringValue", "boolValue", "intValue", "doubleValue"] as const) {- if (key in value) return value[key];- }- if (isRecord(value.arrayValue) && Array.isArray(value.arrayValue.values)) {- return value.arrayValue.values.filter(isRecord).map((entry) => parseAnyValue(entry));- }- return undefined;-}-function renderSpanTree(spans: readonly LocalTraceSpan[]): string {const byId = new Map(spans.map((span) => [span.spanId, span]));const children = new Map<string, LocalTraceSpan[]>();@@ -349,8 +176,8 @@ function renderSpanTree(spans: readonly LocalTraceSpan[]): string {children.set(span.parentSpanId, siblings);}}- roots.sort(compareSpans);- for (const siblings of children.values()) siblings.sort(compareSpans);+ roots.sort(compareLocalTraceSpans);+ for (const siblings of children.values()) siblings.sort(compareLocalTraceSpans);const extents = subtreeExtents(spans, children);const lines: string[] = [];@@ -370,12 +197,20 @@ function renderSpanTree(spans: readonly LocalTraceSpan[]): string {});};for (const root of roots) render(root, "", "");- for (const span of [...spans].sort(compareSpans)) {+ for (const span of [...spans].sort(compareLocalTraceSpans)) {if (!visited.has(span.spanId)) render(span, "", "");}return lines.join("\n");}+/**+ * Extent of each span's own range unioned with its descendants', keyed by span id.+ *+ * eve records a span whose lifetime crosses a durable worker boundary — a+ * session window or a turn — as a zero-duration marker, because a span object+ * cannot cross that boundary to be ended later. The tree falls back to this+ * extent for those rows so it shows where the time went.+ */function subtreeExtents(spans: readonly LocalTraceSpan[],children: ReadonlyMap<string, readonly LocalTraceSpan[]>,@@ -405,32 +240,7 @@ function subtreeExtents(}function spanLabel(span: LocalTraceSpan, extent?: SpanExtent): string {- const details: string[] = [];- const turnId = stringAttribute(span, "agent.turn.id");- const stepIndex = valueAttribute(span, "agent.step.index");- const attempt = valueAttribute(span, "agent.step.attempt");- const actionKind = stringAttribute(span, "agent.action.kind");- const actionName = stringAttribute(span, "agent.action.name");- const model =- stringAttribute(span, "agent.model.id") ?? stringAttribute(span, "gen_ai.request.model");- if (span.name === "agent.turn" && turnId !== undefined) {- details.push(sanitizeForTerminal(turnId));- }- if (span.name === "agent.step" && stepIndex !== undefined) {- details.push(- `step ${sanitizeForTerminal(String(stepIndex))}${- attempt === undefined ? "" : `, attempt ${sanitizeForTerminal(String(attempt))}`- }`,- );- }- if (span.name === "agent.action" && actionName !== undefined) {- details.push(- `${sanitizeForTerminal(actionKind ?? "action")}: ${sanitizeForTerminal(actionName)}`,- );- }- if (model !== undefined && span.name.includes("do")) {- details.push(`model ${sanitizeForTerminal(model)}`);- }+ const details = describeLocalTraceSpan(span).map(sanitizeForTerminal);const detail = details.length === 0 ? "" : ` [${details.join(", ")}]`;const error = span.statusCode === 2 ? " ERROR" : "";const recorded = durationMs(span.startTimeNs, span.endTimeNs);@@ -441,73 +251,6 @@ function spanLabel(span: LocalTraceSpan, extent?: SpanExtent): string {return `${sanitizeForTerminal(span.name)}${detail} ${formatElapsed(elapsed)}${error}`;}-function compareSpans(left: LocalTraceSpan, right: LocalTraceSpan): number {- if (left.startTimeNs !== right.startTimeNs) return left.startTimeNs < right.startTimeNs ? -1 : 1;- if (left.endTimeNs !== right.endTimeNs) return left.endTimeNs < right.endTimeNs ? -1 : 1;- return left.name.localeCompare(right.name) || left.spanId.localeCompare(right.spanId);-}--function firstNumberAttribute(- attributes: readonly Readonly<Record<string, unknown>>[],- key: string,-): number | undefined {- for (const values of attributes) {- const value = values[key];- if (typeof value === "number") return value;- if (typeof value === "bigint") return Number(value);- }- return undefined;-}--function distinctAttributes(- attributes: readonly Readonly<Record<string, unknown>>[],- key: string,-): readonly string[] {- const values = new Set<string>();- for (const entry of attributes) {- const value = entry[key];- if (typeof value === "string" && value.length > 0) values.add(value);- }- return [...values];-}--function firstAttribute(- attributes: readonly Readonly<Record<string, unknown>>[],- key: string,-): string | undefined {- for (const values of attributes) {- const value = values[key];- if (typeof value === "string" && value.length > 0) return value;- }- return undefined;-}--function stringAttribute(span: LocalTraceSpan, key: string): string | undefined {- const value = span.attributes[key];- return typeof value === "string" ? value : undefined;-}--function valueAttribute(span: LocalTraceSpan, key: string): string | number | undefined {- const value = span.attributes[key];- return typeof value === "string" || typeof value === "number" ? value : undefined;-}--function parseNanos(value: unknown): bigint | undefined {- if (typeof value !== "string" && typeof value !== "number") return undefined;- try {- const parsed = BigInt(value);- return parsed >= 0n && parsed <= MAX_UINT64 ? parsed : undefined;- } catch {- return undefined;- }-}--function parseStatusCode(value: unknown): number {- if (!isRecord(value)) return 0;- if (typeof value.code === "number") return value.code;- return value.code === "STATUS_CODE_ERROR" ? 2 : 0;-}-function durationMs(start: bigint, end: bigint): number {return Number(end - start) / 1_000_000;}@@ -516,14 +259,6 @@ function toDate(nanoseconds: bigint): Date {return new Date(Number(nanoseconds / 1_000_000n));}-function isMissing(error: unknown): boolean {- return (error as NodeJS.ErrnoException).code === "ENOENT";-}--function isRecord(value: unknown): value is Record<string, unknown> {- return typeof value === "object" && value !== null && !Array.isArray(value);-}-function ambiguousTraceError(traces: readonly LocalTrace[], reference: string): Error {return new Error([diff --git a/packages/eve/src/harness/local-instrumentation-runtime.scenario.test.ts b/packages/eve/src/harness/local-instrumentation-runtime.scenario.test.tsindex 329fe000b..56795d413 100644--- a/packages/eve/src/harness/local-instrumentation-runtime.scenario.test.ts+++ b/packages/eve/src/harness/local-instrumentation-runtime.scenario.test.ts@@ -7,8 +7,8 @@ import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";import { afterEach, describe, expect, it } from "vitest";import { ContextContainer, contextStorage } from "#context/container.js";-import { listLocalTraces } from "#cli/commands/trace.js";import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";+import { listLocalTraces } from "#harness/local-trace-reader.js";import type { InstrumentationAttemptScope } from "#harness/instrumentation-lifecycle.js";import { installLocalInstrumentationRuntime } from "#harness/local-instrumentation-runtime.js";import { LocalTraceSpanProcessor } from "#harness/local-trace-span-processor.js";diff --git a/packages/eve/src/harness/local-trace-reader.ts b/packages/eve/src/harness/local-trace-reader.tsnew file mode 100644index 000000000..aa8e8de3f--- /dev/null+++ b/packages/eve/src/harness/local-trace-reader.ts@@ -0,0 +1,323 @@+/**+ * Reads the local trace spool written by {@link LocalTraceSpanProcessor}.+ *+ * The spool is the contract between the dev-time writer and every viewer+ * (`eve traces`, the TUI trace viewer): one directory per trace under+ * `.eve/traces/v1/<traceId>/segments/`, one immutable OTLP/JSON file per+ * span. Parsing is defensive end to end — malformed or oversized segments+ * are skipped so a partial write never breaks a view.+ */++import { readdir, readFile, stat } from "node:fs/promises";+import { join } from "node:path";++import { resolveLocalTraceSchemaDirectory } from "#harness/local-trace-span-processor.js";++const TRACE_ID_PATTERN = /^[0-9a-f]{32}$/u;+const SPAN_FILE_PATTERN = /^([0-9a-f]{16})\.otlp\.json$/u;+const MAX_SEGMENT_BYTES = 8 * 1024 * 1024;+const MAX_UINT64 = 18_446_744_073_709_551_615n;++export interface LocalTraceSpan {+ readonly attributes: Readonly<Record<string, unknown>>;+ readonly endTimeNs: bigint;+ readonly name: string;+ readonly parentSpanId?: string;+ readonly scope?: string;+ readonly spanId: string;+ readonly startTimeNs: bigint;+ readonly statusCode: number;+ readonly traceId: string;+}++export interface LocalTrace {+ readonly agentName?: string;+ readonly endTimeNs: bigint;+ /** Session that opened the trace, which is the one the list shows. */+ readonly sessionId?: string;+ /**+ * Every session recorded in the trace, opener first.+ *+ * A subagent child records into the window its parent had open, so one+ * trace can hold several sessions and any of their ids resolves to it.+ */+ readonly sessionIds: readonly string[];+ readonly spans: readonly LocalTraceSpan[];+ readonly startTimeNs: bigint;+ readonly traceId: string;+ /** Zero-based session window this trace holds, when the spans record one. */+ readonly window?: number;+}++/** Reads valid local traces, newest first, while ignoring malformed segments. */+export async function listLocalTraces(appRoot: string): Promise<LocalTrace[]> {+ const root = resolveLocalTraceSchemaDirectory(appRoot);+ let entries;+ try {+ entries = await readdir(root, { withFileTypes: true });+ } catch (error) {+ if (isMissing(error)) return [];+ throw error;+ }++ const traces: LocalTrace[] = [];+ for (const entry of entries) {+ if (!entry.isDirectory() || !TRACE_ID_PATTERN.test(entry.name)) continue;+ const trace = await readLocalTrace(root, entry.name).catch(() => undefined);+ if (trace !== undefined) traces.push(trace);+ }+ return traces.sort((left, right) =>+ left.startTimeNs === right.startTimeNs+ ? left.traceId.localeCompare(right.traceId)+ : left.startTimeNs > right.startTimeNs+ ? -1+ : 1,+ );+}++/**+ * Reads one trace from its segments directory, or `undefined` when the trace+ * has no valid spans. Spans come back ordered by start time.+ */+export async function readLocalTrace(+ root: string,+ traceId: string,+): Promise<LocalTrace | undefined> {+ const segmentsRoot = join(root, traceId, "segments");+ let entries;+ try {+ entries = await readdir(segmentsRoot, { withFileTypes: true });+ } catch (error) {+ if (isMissing(error)) return undefined;+ throw error;+ }+ const spans = new Map<string, LocalTraceSpan>();+ for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {+ if (!entry.isFile() || !SPAN_FILE_PATTERN.test(entry.name)) continue;+ let content: string;+ try {+ const path = join(segmentsRoot, entry.name);+ if ((await stat(path)).size > MAX_SEGMENT_BYTES) continue;+ content = await readFile(path, "utf8");+ } catch {+ continue;+ }+ for (const span of parseLocalTraceSegment(content, traceId)) {+ if (!spans.has(span.spanId)) spans.set(span.spanId, span);+ }+ }+ if (spans.size === 0) return undefined;+ return assembleLocalTrace(traceId, [...spans.values()]);+}++/** Sorts spans into timeline order: start, then end, then a stable tiebreak. */+export function compareLocalTraceSpans(left: LocalTraceSpan, right: LocalTraceSpan): number {+ if (left.startTimeNs !== right.startTimeNs) return left.startTimeNs < right.startTimeNs ? -1 : 1;+ if (left.endTimeNs !== right.endTimeNs) return left.endTimeNs < right.endTimeNs ? -1 : 1;+ return left.name.localeCompare(right.name) || left.spanId.localeCompare(right.spanId);+}++/** Builds a trace from already-parsed spans, deriving summary fields. */+export function assembleLocalTrace(traceId: string, spans: readonly LocalTraceSpan[]): LocalTrace {+ const ordered = [...spans].sort(compareLocalTraceSpans);+ const attributes = ordered.map((span) => span.attributes);+ const sessionIds = distinctAttributes(attributes, "agent.session.id");+ return {+ agentName: firstAttribute(attributes, "agent.name"),+ endTimeNs: ordered.reduce(+ (value, span) => (span.endTimeNs > value ? span.endTimeNs : value),+ 0n,+ ),+ sessionId: sessionIds[0],+ sessionIds,+ spans: ordered,+ startTimeNs: ordered.reduce(+ (value, span) => (span.startTimeNs < value ? span.startTimeNs : value),+ ordered[0]!.startTimeNs,+ ),+ traceId,+ window: firstNumberAttribute(attributes, "agent.session.window"),+ };+}++/**+ * Extracts short human-facing details from a span's structural attributes+ * (turn id, step index/attempt, action kind/name, model id) for one-line+ * span labels. Raw values — callers sanitize for their output surface.+ */+export function describeLocalTraceSpan(span: LocalTraceSpan): string[] {+ const details: string[] = [];+ const turnId = stringSpanAttribute(span, "agent.turn.id");+ const stepIndex = valueSpanAttribute(span, "agent.step.index");+ const attempt = valueSpanAttribute(span, "agent.step.attempt");+ const actionKind = stringSpanAttribute(span, "agent.action.kind");+ const actionName = stringSpanAttribute(span, "agent.action.name");+ const model =+ stringSpanAttribute(span, "agent.model.id") ??+ stringSpanAttribute(span, "gen_ai.request.model");+ if (span.name === "agent.turn" && turnId !== undefined) {+ details.push(turnId);+ }+ if (span.name === "agent.step" && stepIndex !== undefined) {+ details.push(+ `step ${String(stepIndex)}${attempt === undefined ? "" : `, attempt ${String(attempt)}`}`,+ );+ }+ if (span.name === "agent.action" && actionName !== undefined) {+ details.push(`${actionKind ?? "action"}: ${actionName}`);+ }+ if (model !== undefined && span.name.includes("do")) {+ details.push(`model ${model}`);+ }+ return details;+}++/** Parses one OTLP/JSON segment file into spans belonging to `expectedTraceId`. */+export function parseLocalTraceSegment(content: string, expectedTraceId: string): LocalTraceSpan[] {+ try {+ const request = JSON.parse(content) as unknown;+ if (!isRecord(request) || !Array.isArray(request.resourceSpans)) return [];+ const spans: LocalTraceSpan[] = [];+ for (const resource of request.resourceSpans) {+ if (!isRecord(resource) || !Array.isArray(resource.scopeSpans)) continue;+ for (const scoped of resource.scopeSpans) {+ if (!isRecord(scoped) || !Array.isArray(scoped.spans)) continue;+ const scope =+ isRecord(scoped.scope) && typeof scoped.scope.name === "string"+ ? scoped.scope.name+ : undefined;+ for (const rawSpan of scoped.spans) {+ const span = parseLocalTraceSpan(rawSpan, expectedTraceId, scope);+ if (span !== undefined) spans.push(span);+ }+ }+ }+ return spans;+ } catch {+ return [];+ }+}++function parseLocalTraceSpan(+ raw: unknown,+ expectedTraceId: string,+ scope?: string,+): LocalTraceSpan | undefined {+ if (!isRecord(raw)) return undefined;+ if (+ raw.traceId !== expectedTraceId ||+ typeof raw.spanId !== "string" ||+ !/^[0-9a-f]{16}$/u.test(raw.spanId) ||+ typeof raw.name !== "string"+ ) {+ return undefined;+ }+ const startTimeNs = parseNanos(raw.startTimeUnixNano);+ const endTimeNs = parseNanos(raw.endTimeUnixNano);+ if (startTimeNs === undefined || endTimeNs === undefined || endTimeNs < startTimeNs)+ return undefined;+ return {+ attributes: parseAttributes(raw.attributes),+ endTimeNs,+ name: raw.name,+ parentSpanId:+ typeof raw.parentSpanId === "string" && /^[0-9a-f]{16}$/u.test(raw.parentSpanId)+ ? raw.parentSpanId+ : undefined,+ scope,+ spanId: raw.spanId,+ startTimeNs,+ statusCode: parseStatusCode(raw.status),+ traceId: expectedTraceId,+ };+}++function parseAttributes(value: unknown): Record<string, unknown> {+ if (!Array.isArray(value)) return {};+ const attributes: Record<string, unknown> = {};+ for (const entry of value) {+ if (!isRecord(entry) || typeof entry.key !== "string" || !isRecord(entry.value)) continue;+ const parsed = parseAnyValue(entry.value);+ if (parsed !== undefined) attributes[entry.key] = parsed;+ }+ return attributes;+}++function parseAnyValue(value: Record<string, unknown>): unknown {+ for (const key of ["stringValue", "boolValue", "intValue", "doubleValue"] as const) {+ if (key in value) return value[key];+ }+ if (isRecord(value.arrayValue) && Array.isArray(value.arrayValue.values)) {+ return value.arrayValue.values.filter(isRecord).map((entry) => parseAnyValue(entry));+ }+ return undefined;+}++function parseNanos(value: unknown): bigint | undefined {+ if (typeof value !== "string" && typeof value !== "number") return undefined;+ try {+ const parsed = BigInt(value);+ return parsed >= 0n && parsed <= MAX_UINT64 ? parsed : undefined;+ } catch {+ return undefined;+ }+}++function parseStatusCode(value: unknown): number {+ if (!isRecord(value)) return 0;+ if (typeof value.code === "number") return value.code;+ return value.code === "STATUS_CODE_ERROR" ? 2 : 0;+}++function firstAttribute(+ attributes: readonly Readonly<Record<string, unknown>>[],+ key: string,+): string | undefined {+ for (const values of attributes) {+ const value = values[key];+ if (typeof value === "string" && value.length > 0) return value;+ }+ return undefined;+}++function firstNumberAttribute(+ attributes: readonly Readonly<Record<string, unknown>>[],+ key: string,+): number | undefined {+ for (const values of attributes) {+ const value = values[key];+ if (typeof value === "number") return value;+ if (typeof value === "bigint") return Number(value);+ }+ return undefined;+}++function distinctAttributes(+ attributes: readonly Readonly<Record<string, unknown>>[],+ key: string,+): readonly string[] {+ const values = new Set<string>();+ for (const entry of attributes) {+ const value = entry[key];+ if (typeof value === "string" && value.length > 0) values.add(value);+ }+ return [...values];+}++function stringSpanAttribute(span: LocalTraceSpan, key: string): string | undefined {+ const value = span.attributes[key];+ return typeof value === "string" ? value : undefined;+}++function valueSpanAttribute(span: LocalTraceSpan, key: string): string | number | undefined {+ const value = span.attributes[key];+ return typeof value === "string" || typeof value === "number" ? value : undefined;+}++function isMissing(error: unknown): boolean {+ return (error as NodeJS.ErrnoException).code === "ENOENT";+}++function isRecord(value: unknown): value is Record<string, unknown> {+ return typeof value === "object" && value !== null && !Array.isArray(value);+}