@a5c-ai/genty-runtime 5.1.1-staging.583e3d9a6ed7

package/dist/telemetry/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
+ * and in-memory implementations.
+ */
+export { TelemetrySpanStatus, type TelemetryEvent, type TelemetrySpan, type TelemetryProvider, type TelemetryExporter, type TelemetryConfig, type TraceContext, type TelemetrySpanStartOptions, type TelemetryExportResult, } from "./types";
+export { HttpTelemetryExporter, InMemoryTelemetryProvider, } from "./provider";
+export type { HttpTelemetrySend, InMemoryTelemetryProviderOptions, } from "./provider";
+export { AuditLog, type AuditEntry, type AuditFilter, } from "./audit-log";
+export { SpanTree, type SpanTreeNode, type SerializedSpanTreeNode, } from "./span-tree";
+export { createTraceContext, parseTraceParent, serializeTraceParent, type CreateTraceContextOptions, } from "./traceContext";
+export { FileTelemetryExporter, InMemoryTelemetryExporter, NoopTelemetryExporter, OtlpHttpTraceExporter, type OtlpHttpTraceExporterOptions, } from "./exporters";
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,GAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,gCAAgC,GACjC,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,yBAAyB,GAC/B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,aAAa,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtlpHttpTraceExporter = exports.NoopTelemetryExporter = exports.InMemoryTelemetryExporter = exports.FileTelemetryExporter = exports.serializeTraceParent = exports.parseTraceParent = exports.createTraceContext = exports.SpanTree = exports.AuditLog = exports.InMemoryTelemetryProvider = exports.HttpTelemetryExporter = exports.TelemetrySpanStatus = void 0;
+/**
+ * Telemetry module — OpenTelemetry-aligned structured telemetry interfaces
+ * and in-memory implementations.
+ */
+var types_1 = require("./types");
+Object.defineProperty(exports, "TelemetrySpanStatus", { enumerable: true, get: function () { return types_1.TelemetrySpanStatus; } });
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "HttpTelemetryExporter", { enumerable: true, get: function () { return provider_1.HttpTelemetryExporter; } });
+Object.defineProperty(exports, "InMemoryTelemetryProvider", { enumerable: true, get: function () { return provider_1.InMemoryTelemetryProvider; } });
+var audit_log_1 = require("./audit-log");
+Object.defineProperty(exports, "AuditLog", { enumerable: true, get: function () { return audit_log_1.AuditLog; } });
+var span_tree_1 = require("./span-tree");
+Object.defineProperty(exports, "SpanTree", { enumerable: true, get: function () { return span_tree_1.SpanTree; } });
+var traceContext_1 = require("./traceContext");
+Object.defineProperty(exports, "createTraceContext", { enumerable: true, get: function () { return traceContext_1.createTraceContext; } });
+Object.defineProperty(exports, "parseTraceParent", { enumerable: true, get: function () { return traceContext_1.parseTraceParent; } });
+Object.defineProperty(exports, "serializeTraceParent", { enumerable: true, get: function () { return traceContext_1.serializeTraceParent; } });
+var exporters_1 = require("./exporters");
+Object.defineProperty(exports, "FileTelemetryExporter", { enumerable: true, get: function () { return exporters_1.FileTelemetryExporter; } });
+Object.defineProperty(exports, "InMemoryTelemetryExporter", { enumerable: true, get: function () { return exporters_1.InMemoryTelemetryExporter; } });
+Object.defineProperty(exports, "NoopTelemetryExporter", { enumerable: true, get: function () { return exporters_1.NoopTelemetryExporter; } });
+Object.defineProperty(exports, "OtlpHttpTraceExporter", { enumerable: true, get: function () { return exporters_1.OtlpHttpTraceExporter; } });

package/dist/telemetry/provider.d.ts

@@ -0,0 +1,57 @@
+/**
+ * InMemoryTelemetryProvider — in-process telemetry backend for development,
+ * testing, and single-process agent runtimes.
+ *
+ * Stores spans in memory and supports flush/drain for export pipelines.
+ */
+import type { TelemetryExporter, TelemetryExportResult, TelemetryProvider, TelemetrySpan, TelemetryEvent, TelemetrySpanStartOptions } from "./types";
+import { TelemetrySpanStatus } from "./types";
+export interface InMemoryTelemetryProviderOptions {
+    exporters?: TelemetryExporter[];
+}
+export declare class FileTelemetryExporter implements TelemetryExporter {
+    private readonly filePath;
+    constructor(filePath: string);
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+}
+export type HttpTelemetrySend = (url: string, payload: unknown) => Promise<void>;
+export declare class HttpTelemetryExporter implements TelemetryExporter {
+    private readonly url;
+    private readonly send;
+    constructor(url: string, send?: HttpTelemetrySend);
+    export(spans: readonly TelemetrySpan[]): Promise<TelemetryExportResult>;
+}
+/**
+ * In-memory telemetry provider that satisfies the TelemetryProvider interface.
+ *
+ * - `startSpan` creates a new span and tracks it as active.
+ * - `endSpan` marks a span as completed and moves it to the completed set.
+ * - `recordEvent` appends a discrete event to an active span.
+ * - `flush` returns all completed spans and clears the completed buffer.
+ * - `getActiveSpans` returns all currently open (un-ended) spans.
+ */
+export declare class InMemoryTelemetryProvider implements TelemetryProvider {
+    /** Active (in-flight) spans keyed by spanId. */
+    private readonly active;
+    /** Completed spans awaiting flush. */
+    private readonly completed;
+    /** Maps spanId -> traceId so child spans inherit the parent's trace. */
+    private readonly traceIndex;
+    private readonly exporters;
+    constructor(options?: InMemoryTelemetryProviderOptions);
+    startSpan(name: string, parentSpanId?: string): Promise<TelemetrySpan>;
+    startSpan(name: string, options?: TelemetrySpanStartOptions): Promise<TelemetrySpan>;
+    endSpan(spanId: string, status?: TelemetrySpanStatus): Promise<void>;
+    recordEvent(spanId: string, event: TelemetryEvent): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Drain completed spans — returns and clears the completed buffer.
+     *
+     * Unlike `flush()` (which satisfies the TelemetryProvider interface and
+     * returns void), this method hands the span data back to the caller.
+     */
+    drain(): Promise<TelemetrySpan[]>;
+    /** Return a snapshot of all currently open (un-ended) spans. */
+    getActiveSpans(): TelemetrySpan[];
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/telemetry/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/telemetry/provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAoB9C,MAAM,WAAW,gCAAgC;IAC/C,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,qBAAa,qBAAsB,YAAW,iBAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAEvC,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAO9E;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjF,qBAAa,qBAAsB,YAAW,iBAAiB;IAE3D,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,iBAAmC;IAGtD,MAAM,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAK9E;AAaD;;;;;;;;GAQG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;gBAEpC,OAAO,CAAC,EAAE,gCAAgC;IAMhD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IACtE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,aAAa,CAAC;IA2CpF,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAMvC,gEAAgE;IAChE,cAAc,IAAI,aAAa,EAAE;CAGlC"}

package/dist/telemetry/provider.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * InMemoryTelemetryProvider — in-process telemetry backend for development,
+ * testing, and single-process agent runtimes.
+ *
+ * Stores spans in memory and supports flush/drain for export pipelines.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryTelemetryProvider = exports.HttpTelemetryExporter = exports.FileTelemetryExporter = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const types_1 = require("./types");
+class FileTelemetryExporter {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async export(spans) {
+        if (spans.length === 0)
+            return { ok: true, exported: 0 };
+        await node_fs_1.promises.mkdir(path.dirname(this.filePath), { recursive: true });
+        const payload = spans.map((span) => JSON.stringify(redactSpan(span))).join("\n") + "\n";
+        await node_fs_1.promises.appendFile(this.filePath, payload, "utf-8");
+        return { ok: true, exported: spans.length };
+    }
+}
+exports.FileTelemetryExporter = FileTelemetryExporter;
+class HttpTelemetryExporter {
+    url;
+    send;
+    constructor(url, send = defaultHttpSend) {
+        this.url = url;
+        this.send = send;
+    }
+    async export(spans) {
+        if (spans.length === 0)
+            return { ok: true, exported: 0 };
+        await this.send(this.url, toOtlpPayload(spans.map(redactSpan)));
+        return { ok: true, exported: spans.length };
+    }
+}
+exports.HttpTelemetryExporter = HttpTelemetryExporter;
+function toReadonly(span) {
+    return {
+        ...span,
+        attributes: { ...span.attributes },
+        events: span.events.map((event) => ({
+            ...event,
+            attributes: event.attributes ? { ...event.attributes } : undefined,
+        })),
+    };
+}
+/**
+ * In-memory telemetry provider that satisfies the TelemetryProvider interface.
+ *
+ * - `startSpan` creates a new span and tracks it as active.
+ * - `endSpan` marks a span as completed and moves it to the completed set.
+ * - `recordEvent` appends a discrete event to an active span.
+ * - `flush` returns all completed spans and clears the completed buffer.
+ * - `getActiveSpans` returns all currently open (un-ended) spans.
+ */
+class InMemoryTelemetryProvider {
+    /** Active (in-flight) spans keyed by spanId. */
+    active = new Map();
+    /** Completed spans awaiting flush. */
+    completed = [];
+    /** Maps spanId -> traceId so child spans inherit the parent's trace. */
+    traceIndex = new Map();
+    exporters;
+    constructor(options) {
+        this.exporters = options?.exporters ?? [];
+    }
+    async startSpan(name, optionsOrParentSpanId) {
+        const spanId = (0, node_crypto_1.randomUUID)();
+        const options = typeof optionsOrParentSpanId === "string"
+            ? { parentSpanId: optionsOrParentSpanId }
+            : optionsOrParentSpanId;
+        const parentSpanId = options?.traceContext?.spanId ?? options?.parentSpanId;
+        let traceId;
+        if (options?.traceContext) {
+            traceId = options.traceContext.traceId;
+        }
+        else if (parentSpanId) {
+            // Inherit traceId from the parent span.
+            traceId = this.traceIndex.get(parentSpanId) ?? (0, node_crypto_1.randomUUID)();
+        }
+        else {
+            traceId = (0, node_crypto_1.randomUUID)();
+        }
+        const span = {
+            name,
+            traceId,
+            spanId,
+            parentSpanId,
+            startTime: new Date().toISOString(),
+            status: types_1.TelemetrySpanStatus.Unset,
+            attributes: {
+                ...options?.attributes,
+                ...(options?.correlationId
+                    ? { "babysitter.correlation_id": options.correlationId }
+                    : {}),
+                ...(options?.traceContext?.correlationId && !options?.correlationId
+                    ? { "babysitter.correlation_id": options.traceContext.correlationId }
+                    : {}),
+            },
+            events: [],
+        };
+        this.active.set(spanId, span);
+        this.traceIndex.set(spanId, traceId);
+        return toReadonly(span);
+    }
+    async endSpan(spanId, status) {
+        const span = this.active.get(spanId);
+        if (!span) {
+            return; // Silently ignore unknown/already-ended spans.
+        }
+        span.endTime = new Date().toISOString();
+        span.status = status ?? types_1.TelemetrySpanStatus.Ok;
+        this.active.delete(spanId);
+        this.completed.push(span);
+    }
+    async recordEvent(spanId, event) {
+        const span = this.active.get(spanId);
+        if (!span) {
+            return; // Silently ignore events on unknown/ended spans.
+        }
+        span.events.push(event);
+    }
+    async flush() {
+        const spans = this.completed.map(toReadonly);
+        for (const exporter of this.exporters) {
+            await exporter.export(spans);
+        }
+        this.completed.length = 0;
+    }
+    /**
+     * Drain completed spans — returns and clears the completed buffer.
+     *
+     * Unlike `flush()` (which satisfies the TelemetryProvider interface and
+     * returns void), this method hands the span data back to the caller.
+     */
+    async drain() {
+        return this.completed.splice(0).map(toReadonly);
+    }
+    // ---------- Extra helpers (not on interface) ----------
+    /** Return a snapshot of all currently open (un-ended) spans. */
+    getActiveSpans() {
+        return [...this.active.values()].map(toReadonly);
+    }
+}
+exports.InMemoryTelemetryProvider = InMemoryTelemetryProvider;
+function redactSpan(span) {
+    return {
+        ...span,
+        attributes: redactAttributes(span.attributes),
+        events: span.events.map((event) => ({
+            ...event,
+            attributes: event.attributes ? redactAttributes(event.attributes) : undefined,
+        })),
+    };
+}
+function redactAttributes(attributes) {
+    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
+        key,
+        isSecretKey(key) || (typeof value === "string" && looksSecretValue(value))
+            ? "[REDACTED]"
+            : value,
+    ]));
+}
+function isSecretKey(key) {
+    return /(token|secret|password|api[_-]?key|authorization|credential)/i.test(key);
+}
+function looksSecretValue(value) {
+    return /(bearer\s+\S+|token=\S+|password=\S+|secret=\S+)/i.test(value);
+}
+function toOtlpPayload(spans) {
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: [] },
+                scopeSpans: [
+                    {
+                        scope: { name: "@a5c-ai/genty-runtime" },
+                        spans: spans.map((span) => ({
+                            traceId: span.traceId,
+                            spanId: span.spanId,
+                            parentSpanId: span.parentSpanId,
+                            name: span.name,
+                            startTimeUnixNano: isoToUnixNano(span.startTime),
+                            endTimeUnixNano: span.endTime ? isoToUnixNano(span.endTime) : undefined,
+                            status: { code: span.status },
+                            attributes: toOtlpAttributes(span.attributes),
+                            events: span.events.map((event) => ({
+                                name: event.name,
+                                timeUnixNano: isoToUnixNano(event.timestamp),
+                                attributes: event.attributes ? toOtlpAttributes(event.attributes) : [],
+                            })),
+                        })),
+                    },
+                ],
+            },
+        ],
+    };
+}
+function toOtlpAttributes(attributes) {
+    return Object.entries(attributes).map(([key, value]) => ({
+        key,
+        value: typeof value === "string"
+            ? { stringValue: value }
+            : typeof value === "number"
+                ? { doubleValue: value }
+                : { boolValue: value },
+    }));
+}
+function isoToUnixNano(value) {
+    return String(BigInt(new Date(value).getTime()) * 1000000n);
+}
+async function defaultHttpSend(url, payload) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        throw new Error(`Telemetry export failed with HTTP ${response.status}`);
+    }
+}

package/dist/telemetry/span-tree.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SpanTree — builds a parent/child tree from a flat list of TelemetrySpans.
+ *
+ * Useful for rendering trace waterfalls, computing subtree durations, and
+ * serializing trace hierarchies to JSON for the observer UI.
+ */
+import type { TelemetrySpan } from "./types";
+/** A tree node wrapping a span with its children. */
+export interface SpanTreeNode {
+    readonly span: TelemetrySpan;
+    readonly children: SpanTreeNode[];
+}
+/** Serializable representation of a SpanTreeNode. */
+export interface SerializedSpanTreeNode {
+    readonly spanId: string;
+    readonly name: string;
+    readonly traceId: string;
+    readonly parentSpanId?: string;
+    readonly startTime: string;
+    readonly endTime?: string;
+    readonly status: string;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly events: Array<{
+        readonly name: string;
+        readonly timestamp: string;
+        readonly attributes?: Record<string, string | number | boolean>;
+    }>;
+    readonly children: SerializedSpanTreeNode[];
+}
+/** Tree built from a flat span list. */
+export declare class SpanTree {
+    /** All nodes keyed by spanId for O(1) lookup. */
+    private readonly nodes;
+    /** Root node ids (spans with no parent or whose parent is unknown). */
+    private readonly rootIds;
+    /** Insert a span into the tree, linking it to its parent if present. */
+    addSpan(span: TelemetrySpan): void;
+    /** Get direct children of a span. */
+    getChildren(spanId: string): TelemetrySpan[];
+    /** Get top-level spans (those with no parent). */
+    getRoots(): TelemetrySpan[];
+    /** Serialize the full tree to a JSON-safe structure. */
+    toJSON(): SerializedSpanTreeNode[];
+    private serializeNode;
+}
+//# sourceMappingURL=span-tree.d.ts.map

package/dist/telemetry/span-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-tree.d.ts","sourceRoot":"","sources":["../../src/telemetry/span-tree.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;KACjE,CAAC,CAAC;IACH,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CAC7C;AAMD,wCAAwC;AACxC,qBAAa,QAAQ;IACnB,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,wEAAwE;IACxE,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAgClC,qCAAqC;IACrC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IAM5C,kDAAkD;IAClD,QAAQ,IAAI,aAAa,EAAE;IAO3B,wDAAwD;IACxD,MAAM,IAAI,sBAAsB,EAAE;IAOlC,OAAO,CAAC,aAAa;CAmBtB"}

package/dist/telemetry/span-tree.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * SpanTree — builds a parent/child tree from a flat list of TelemetrySpans.
+ *
+ * Useful for rendering trace waterfalls, computing subtree durations, and
+ * serializing trace hierarchies to JSON for the observer UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanTree = void 0;
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/** Tree built from a flat span list. */
+class SpanTree {
+    /** All nodes keyed by spanId for O(1) lookup. */
+    nodes = new Map();
+    /** Root node ids (spans with no parent or whose parent is unknown). */
+    rootIds = [];
+    /** Insert a span into the tree, linking it to its parent if present. */
+    addSpan(span) {
+        // Create or retrieve the node for this span.
+        let node = this.nodes.get(span.spanId);
+        if (node) {
+            // Node was pre-created as a placeholder by a child — update the span.
+            node.span = span;
+        }
+        else {
+            node = { span, children: [] };
+            this.nodes.set(span.spanId, node);
+        }
+        if (span.parentSpanId) {
+            let parentNode = this.nodes.get(span.parentSpanId);
+            if (!parentNode) {
+                // Parent hasn't been added yet — create a placeholder.
+                parentNode = {
+                    span: undefined,
+                    children: [],
+                };
+                this.nodes.set(span.parentSpanId, parentNode);
+            }
+            // Avoid duplicate children on re-add.
+            if (!parentNode.children.some((c) => c.span?.spanId === span.spanId)) {
+                parentNode.children.push(node);
+            }
+        }
+        else {
+            if (!this.rootIds.includes(span.spanId)) {
+                this.rootIds.push(span.spanId);
+            }
+        }
+    }
+    /** Get direct children of a span. */
+    getChildren(spanId) {
+        const node = this.nodes.get(spanId);
+        if (!node)
+            return [];
+        return node.children.map((c) => c.span);
+    }
+    /** Get top-level spans (those with no parent). */
+    getRoots() {
+        return this.rootIds
+            .map((id) => this.nodes.get(id))
+            .filter((n) => n != null && n.span != null)
+            .map((n) => n.span);
+    }
+    /** Serialize the full tree to a JSON-safe structure. */
+    toJSON() {
+        return this.getRoots()
+            .map((root) => this.nodes.get(root.spanId))
+            .filter((n) => n != null)
+            .map((n) => this.serializeNode(n));
+    }
+    serializeNode(node) {
+        const { span } = node;
+        return {
+            spanId: span.spanId,
+            name: span.name,
+            traceId: span.traceId,
+            parentSpanId: span.parentSpanId,
+            startTime: span.startTime,
+            endTime: span.endTime,
+            status: span.status,
+            attributes: { ...span.attributes },
+            events: span.events.map((e) => ({
+                name: e.name,
+                timestamp: e.timestamp,
+                ...(e.attributes ? { attributes: { ...e.attributes } } : {}),
+            })),
+            children: node.children.map((c) => this.serializeNode(c)),
+        };
+    }
+}
+exports.SpanTree = SpanTree;

package/dist/telemetry/traceContext.d.ts

@@ -0,0 +1,10 @@
+import type { TraceContext } from "./types";
+export declare function parseTraceParent(header: string): TraceContext | null;
+export declare function serializeTraceParent(context: TraceContext): string;
+export interface CreateTraceContextOptions {
+    parent?: TraceContext;
+    correlationId?: string;
+    sampled?: boolean;
+}
+export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;
+//# sourceMappingURL=traceContext.d.ts.map

package/dist/telemetry/traceContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceContext.d.ts","sourceRoot":"","sources":["../../src/telemetry/traceContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQ5C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQpE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,YAAY,CAYpF"}

package/dist/telemetry/traceContext.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceParent = parseTraceParent;
+exports.serializeTraceParent = serializeTraceParent;
+exports.createTraceContext = createTraceContext;
+const node_crypto_1 = require("node:crypto");
+const TRACEPARENT_PATTERN = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+function allZero(value) {
+    return /^0+$/.test(value);
+}
+function parseTraceParent(header) {
+    const match = TRACEPARENT_PATTERN.exec(header.trim());
+    if (!match)
+        return null;
+    const [, version, traceId, spanId, traceFlags] = match;
+    if (version !== "00" || allZero(traceId) || allZero(spanId)) {
+        return null;
+    }
+    return { version, traceId, spanId, traceFlags };
+}
+function serializeTraceParent(context) {
+    return `${context.version}-${context.traceId}-${context.spanId}-${context.traceFlags}`;
+}
+function createTraceContext(options) {
+    const traceId = options?.parent?.traceId ?? randomHex(16);
+    const spanId = randomHex(8);
+    const traceFlags = options?.sampled === false ? "00" : options?.parent?.traceFlags ?? "01";
+    return {
+        version: "00",
+        traceId,
+        spanId,
+        traceFlags,
+        parentSpanId: options?.parent?.spanId,
+        correlationId: options?.correlationId ?? options?.parent?.correlationId,
+    };
+}
+function randomHex(bytes) {
+    let value = (0, node_crypto_1.randomBytes)(bytes).toString("hex");
+    while (allZero(value)) {
+        value = (0, node_crypto_1.randomBytes)(bytes).toString("hex");
+    }
+    return value;
+}