@oneuptime/common 11.3.25 → 11.3.26

package/build/dist/Server/Utils/AI/Toolbox/Serializer.js

@@ -0,0 +1,188 @@
+/*
+ * Prepares tool results for the LLM prompt: redacts likely secrets/PII,
+ * truncates long fields, and caps total payload size. Everything that enters
+ * the prompt (and therefore leaves for the LLM provider, and is previewed in
+ * LlmLog.requestPrompt) passes through here first.
+ */
+const MAX_ROWS = 50;
+const MAX_FIELD_LENGTH = 500;
+const MAX_PAYLOAD_BYTES = 16 * 1024;
+/*
+ * These are security redactions, not the fingerprint-normalization regexes
+ * (those normalize numbers/uuids for grouping and do not cover credentials).
+ */
+const REDACTION_RULES = [
+    {
+        name: "jwt",
+        regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/g,
+        replacement: "[redacted-jwt]",
+    },
+    {
+        name: "bearer",
+        regex: /Bearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
+        replacement: "Bearer [redacted-token]",
+    },
+    {
+        name: "email",
+        regex: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+        replacement: "[redacted-email]",
+    },
+    {
+        name: "ipv4",
+        regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+        replacement: "[redacted-ip]",
+    },
+    {
+        /*
+         * Long hex blobs are usually secrets (SHA-256 digests, 40+ char API
+         * keys). But W3C/OTel trace IDs are exactly 32 hex chars and span IDs
+         * exactly 16 — redacting those would break the documented
+         * search_logs → get_trace pivot, since the model would never see the ID
+         * it needs to pass back. So only redact runs of 33+ hex chars, which
+         * preserves both ID lengths while still catching typical hash-length
+         * secrets. Labeled secrets of any length are still caught by
+         * key-value-secret below.
+         */
+        name: "hex-secret",
+        regex: /\b[0-9a-fA-F]{33,}\b/g,
+        replacement: "[redacted-hex]",
+    },
+    {
+        name: "key-value-secret",
+        regex: /\b(password|passwd|secret|api[_-]?key|access[_-]?token|authorization)\b(\s*[:=]\s*)("[^"]{4,}"|'[^']{4,}'|[^\s,;&]{4,})/gi,
+        replacement: "$1$2[redacted]",
+    },
+];
+export default class ToolResultSerializer {
+    // Single pass per rule: count and substitute ($1/$2 groups) together.
+    static applyRedactionRule(text, rule) {
+        let count = 0;
+        const result = text.replace(rule.regex, (...matchArgs) => {
+            count++;
+            return rule.replacement.replace(/\$(\d)/g, (_full, groupIndex) => {
+                var _a;
+                return String((_a = matchArgs[Number(groupIndex)]) !== null && _a !== void 0 ? _a : "");
+            });
+        });
+        return { text: result, count };
+    }
+    static redact(text) {
+        let redacted = text;
+        let count = 0;
+        for (const rule of REDACTION_RULES) {
+            const applied = this.applyRedactionRule(redacted, rule);
+            redacted = applied.text;
+            count += applied.count;
+        }
+        return { text: redacted, count };
+    }
+    // Byte-accurate truncation (substring counts UTF-16 units, not bytes).
+    static truncateToBytes(text, maxBytes) {
+        if (Buffer.byteLength(text, "utf8") <= maxBytes) {
+            return text;
+        }
+        return Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+    }
+    static truncateField(value) {
+        if (value.length <= MAX_FIELD_LENGTH) {
+            return { value, truncated: false };
+        }
+        return {
+            value: `${value.substring(0, MAX_FIELD_LENGTH)}… [truncated]`,
+            truncated: true,
+        };
+    }
+    static serializeValue(value) {
+        if (value === null || value === undefined) {
+            return "";
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof value === "object") {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    }
+    /*
+     * Serialize rows as a compact markdown-ish record list. Applies row cap,
+     * per-field truncation, redaction and total payload cap.
+     */
+    static serializeRows(rows, totalRowCount) {
+        let isTruncated = false;
+        let redactionCount = 0;
+        let rowsToSerialize = rows;
+        if (rows.length > MAX_ROWS) {
+            rowsToSerialize = rows.slice(0, MAX_ROWS);
+            isTruncated = true;
+        }
+        const lines = [];
+        for (const row of rowsToSerialize) {
+            const parts = [];
+            for (const key of Object.keys(row)) {
+                const rawValue = this.serializeValue(row[key]);
+                if (!rawValue) {
+                    continue;
+                }
+                const redacted = this.redact(rawValue);
+                redactionCount += redacted.count;
+                const truncated = this.truncateField(redacted.text);
+                if (truncated.truncated) {
+                    isTruncated = true;
+                }
+                parts.push(`${key}=${truncated.value}`);
+            }
+            lines.push(`- ${parts.join(" | ")}`);
+        }
+        let text = lines.join("\n");
+        if (Buffer.byteLength(text, "utf8") > MAX_PAYLOAD_BYTES) {
+            isTruncated = true;
+            while (lines.length > 1 &&
+                Buffer.byteLength(lines.join("\n"), "utf8") > MAX_PAYLOAD_BYTES) {
+                lines.pop();
+            }
+            // A single oversized row can still exceed the cap — hard-slice it.
+            text = `${this.truncateToBytes(lines.join("\n"), MAX_PAYLOAD_BYTES)}\n… [payload truncated]`;
+        }
+        const rowCount = totalRowCount !== null && totalRowCount !== void 0 ? totalRowCount : rows.length;
+        if (rows.length === 0) {
+            text = "(no rows found)";
+        }
+        /*
+         * Tell the model when it is only seeing a slice. Without this marker a
+         * capped result looks complete, and the model reports partial data as if it
+         * were the whole picture.
+         */
+        if (rows.length > MAX_ROWS) {
+            text = `${text}\n… [showing the first ${MAX_ROWS} of ${rowCount} rows; narrow the query — a shorter time range or more filters — to see the rest]`;
+        }
+        return {
+            text,
+            rowCount,
+            redactionCount,
+            isTruncated,
+            bytes: Buffer.byteLength(text, "utf8"),
+        };
+    }
+    // Serialize free-form text (e.g. a rendered trace tree).
+    static serializeText(text, rowCount) {
+        const redacted = this.redact(text);
+        let output = redacted.text;
+        let isTruncated = false;
+        if (Buffer.byteLength(output, "utf8") > MAX_PAYLOAD_BYTES) {
+            output = `${this.truncateToBytes(output, MAX_PAYLOAD_BYTES)}… [payload truncated]`;
+            isTruncated = true;
+        }
+        if (!output) {
+            output = "(no data found)";
+        }
+        return {
+            text: output,
+            rowCount,
+            redactionCount: redacted.count,
+            isTruncated,
+            bytes: Buffer.byteLength(output, "utf8"),
+        };
+    }
+}
+//# sourceMappingURL=Serializer.js.map

package/build/dist/Server/Utils/AI/Toolbox/Serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","sourceRoot":"","sources":["../../../../../../Server/Utils/AI/Toolbox/Serializer.ts"],"names":[],"mappings":"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"}

package/build/dist/Server/Utils/AI/Toolbox/ToolTypes.js

@@ -0,0 +1,142 @@
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import ObjectID from "../../../../Types/ObjectID";
+import OneUptimeDate from "../../../../Types/Date";
+/*
+ * Defensive argument readers. Tool arguments come from the LLM and are
+ * untrusted: everything is type-checked, defaulted and clamped.
+ */
+export class ToolArgs {
+    static getString(args, key) {
+        const value = args[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+        return undefined;
+    }
+    static getStringArray(args, key) {
+        const value = args[key];
+        if (Array.isArray(value)) {
+            const strings = value.filter((item) => {
+                return typeof item === "string" && item.trim().length > 0;
+            });
+            if (strings.length > 0) {
+                return strings;
+            }
+        }
+        return undefined;
+    }
+    static getNumber(args, key, options) {
+        const value = args[key];
+        let parsed = options.defaultValue;
+        if (typeof value === "number" && Number.isFinite(value)) {
+            parsed = value;
+        }
+        else if (typeof value === "string" && value.trim().length > 0) {
+            const fromString = Number(value);
+            if (Number.isFinite(fromString)) {
+                parsed = fromString;
+            }
+        }
+        return Math.min(options.max, Math.max(options.min, Math.floor(parsed)));
+    }
+    static getBoolean(args, key) {
+        const value = args[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (value === "true") {
+            return true;
+        }
+        if (value === "false") {
+            return false;
+        }
+        return undefined;
+    }
+    static getObjectID(args, key) {
+        const value = this.getString(args, key);
+        if (!value) {
+            return undefined;
+        }
+        return new ObjectID(value);
+    }
+    /*
+     * Combines the caller's optional serviceId filter with the user's owned-scope
+     * access (from ModelPermission.getAccessibleServiceIdsForAnalyticsModel) into
+     * the `serviceIds` filter to hand an aggregation service.
+     *
+     * `allowed === null` means the user has project-wide access: pass only the
+     * caller's own filter (or undefined for no filter). Otherwise the user is
+     * label/owned-restricted: intersect with any requested service and NEVER
+     * return undefined or an empty array — an empty result is forced to a
+     * no-match sentinel, because the aggregation services treat a missing/empty
+     * serviceIds as "no filter" (which would leak the whole project).
+     */
+    static scopeServiceIds(allowed, requested) {
+        if (allowed === null) {
+            return requested ? [requested] : undefined;
+        }
+        let effective = allowed;
+        if (requested) {
+            effective = allowed.filter((id) => {
+                return id.toString() === requested.toString();
+            });
+        }
+        if (effective.length === 0) {
+            return [ObjectID.getZeroObjectID()];
+        }
+        return effective;
+    }
+    /*
+     * Time range for a tool call: explicit ISO startTime/endTime arguments,
+     * clamped to a maximum window, defaulting to the last hour.
+     */
+    static getTimeRange(args, options) {
+        var _a, _b;
+        const defaultHours = (_a = options === null || options === void 0 ? void 0 : options.defaultHours) !== null && _a !== void 0 ? _a : 1;
+        const maxDays = (_b = options === null || options === void 0 ? void 0 : options.maxDays) !== null && _b !== void 0 ? _b : 30;
+        const endTimeString = this.getString(args, "endTime");
+        const startTimeString = this.getString(args, "startTime");
+        /*
+         * Reject unparseable timestamps instead of silently falling back to the
+         * default window — a silent fallback answers a different question than the
+         * one asked. Throwing lets the model see the error and retry with a valid
+         * ISO 8601 value.
+         */
+        let endTime = OneUptimeDate.getCurrentDate();
+        if (endTimeString) {
+            const parsed = new Date(endTimeString);
+            if (isNaN(parsed.getTime())) {
+                throw new BadDataException(`endTime "${endTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T14:00:00Z).`);
+            }
+            endTime = parsed;
+        }
+        let startTime = OneUptimeDate.addRemoveHours(endTime, -1 * defaultHours);
+        if (startTimeString) {
+            const parsed = new Date(startTimeString);
+            if (isNaN(parsed.getTime())) {
+                throw new BadDataException(`startTime "${startTimeString}" is not a valid ISO 8601 timestamp (e.g. 2024-01-31T13:00:00Z).`);
+            }
+            startTime = parsed;
+        }
+        if (startTime.getTime() >= endTime.getTime()) {
+            throw new BadDataException("startTime must be before endTime.");
+        }
+        const maxWindowMs = maxDays * 24 * 60 * 60 * 1000;
+        if (endTime.getTime() - startTime.getTime() > maxWindowMs) {
+            startTime = new Date(endTime.getTime() - maxWindowMs);
+        }
+        return { startTime, endTime };
+    }
+}
+// Shared JSON-Schema fragments for tool input schemas.
+export const TimeRangeSchemaProperties = {
+    startTime: {
+        type: "string",
+        description: "Start of the time range as an ISO 8601 timestamp. Defaults to one hour before endTime.",
+    },
+    endTime: {
+        type: "string",
+        description: "End of the time range as an ISO 8601 timestamp. Defaults to now.",
+    },
+};
+//# sourceMappingURL=ToolTypes.js.map

package/build/dist/Server/Utils/AI/Toolbox/ToolTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolTypes.js","sourceRoot":"","sources":["../../../../../../Server/Utils/AI/Toolbox/ToolTypes.ts"],"names":[],"mappings":"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"}

package/build/dist/Server/Utils/AI/Toolbox/TraceTools.js

@@ -0,0 +1,309 @@
+import Span from "../../../../Models/AnalyticsModels/Span";
+import DatabaseRequestType from "../../../Types/BaseDatabase/DatabaseRequestType";
+import ModelPermission from "../../../Types/AnalyticsDatabase/ModelPermission";
+import SortOrder from "../../../../Types/BaseDatabase/SortOrder";
+import BadDataException from "../../../../Types/Exception/BadDataException";
+import Permission from "../../../../Types/Permission";
+import { AIChatCitationTargetType, } from "../../../../Types/AI/AIChatTypes";
+import SpanService from "../../../Services/SpanService";
+import TraceAggregationService from "../../../Services/TraceAggregationService";
+import ToolResultSerializer from "./Serializer";
+import WidgetBuilder from "./WidgetBuilder";
+import { TimeRangeSchemaProperties, ToolArgs, } from "./ToolTypes";
+const TRACE_READ_PERMISSIONS = [
+    Permission.ProjectOwner,
+    Permission.ProjectAdmin,
+    Permission.ProjectMember,
+    Permission.Viewer,
+    Permission.TelemetryAdmin,
+    Permission.TelemetryMember,
+    Permission.TelemetryViewer,
+    Permission.ReadTelemetryServiceTraces,
+];
+const VALID_METRICS = [
+    "count",
+    "errorCount",
+    "avgDuration",
+    "minDuration",
+    "maxDuration",
+    "p50Duration",
+    "p90Duration",
+    "p95Duration",
+    "p99Duration",
+];
+const VALID_GROUP_BY = [
+    "name",
+    "primaryEntityId",
+    "kind",
+    "statusCode",
+    "isRootSpan",
+];
+/*
+ * Upper bound on spans fetched for a single trace waterfall. High enough for
+ * almost every real trace; when a trace exceeds it we say so explicitly rather
+ * than silently dropping spans (which also orphans their children into fake
+ * roots).
+ */
+const MAX_TRACE_SPANS = 500;
+export const QueryTracesTool = {
+    name: "query_traces",
+    description: "Analyze spans/traces: latency profile (count, errorCount, avg and p50/p90/p95/p99 durations in ms) grouped by one dimension such as span name or service. Use this to answer 'why is X slow', 'error rate by operation' or 'slowest endpoints'. Then drill into a single trace with get_trace.",
+    inputSchema: {
+        type: "object",
+        properties: Object.assign(Object.assign({}, TimeRangeSchemaProperties), { groupBy: {
+                type: "string",
+                enum: ["name", "primaryEntityId", "kind", "statusCode", "isRootSpan"],
+                description: "Dimension to group by (default name = span/operation name; primaryEntityId = service).",
+            }, metric: {
+                type: "string",
+                enum: [
+                    "count",
+                    "errorCount",
+                    "avgDuration",
+                    "minDuration",
+                    "maxDuration",
+                    "p50Duration",
+                    "p90Duration",
+                    "p95Duration",
+                    "p99Duration",
+                ],
+                description: "Metric used to rank the groups (default p95Duration). The full latency profile is always returned per group.",
+            }, nameSearchText: {
+                type: "string",
+                description: "Only spans whose name contains this text.",
+            }, serviceId: {
+                type: "string",
+                description: "Only spans from this telemetry service.",
+            }, hasException: {
+                type: "boolean",
+                description: "Only spans that recorded an exception.",
+            }, rootOnly: {
+                type: "boolean",
+                description: "Only root spans (whole-request latency).",
+            }, limit: {
+                type: "number",
+                description: "Maximum groups to return (default 10, max 25).",
+            } }),
+    },
+    requiredPermissions: TRACE_READ_PERMISSIONS,
+    execute: async (args, ctx) => {
+        const { startTime, endTime } = ToolArgs.getTimeRange(args, {
+            defaultHours: 24,
+            maxDays: 30,
+        });
+        const metric = ToolArgs.getString(args, "metric") || "p95Duration";
+        if (!VALID_METRICS.includes(metric)) {
+            throw new BadDataException(`Invalid metric: ${metric}`);
+        }
+        const groupBy = ToolArgs.getString(args, "groupBy") || "name";
+        if (!VALID_GROUP_BY.includes(groupBy)) {
+            throw new BadDataException(`Invalid groupBy: ${groupBy}`);
+        }
+        const limit = ToolArgs.getNumber(args, "limit", {
+            defaultValue: 10,
+            min: 1,
+            max: 25,
+        });
+        const serviceId = ToolArgs.getObjectID(args, "serviceId");
+        const windowMinutes = (endTime.getTime() - startTime.getTime()) / (60 * 1000);
+        /*
+         * getAnalyticsTable builds raw aggregation SQL and skips the model layer's
+         * owned-scope filter, so a label-restricted user would otherwise see
+         * project-wide trace analytics. Constrain to the services this user may
+         * read (spans are owned through Service, same as logs).
+         */
+        const accessibleServiceIds = await ModelPermission.getAccessibleServiceIdsForAnalyticsModel(Span, ctx.props, DatabaseRequestType.Read);
+        const tableRows = await TraceAggregationService.getAnalyticsTable({
+            projectId: ctx.projectId,
+            startTime: startTime,
+            endTime: endTime,
+            bucketSizeInMinutes: Math.max(1, Math.round(windowMinutes / 60)),
+            chartType: "table",
+            metric: metric,
+            groupBy: [groupBy],
+            limit: limit,
+            nameSearchText: ToolArgs.getString(args, "nameSearchText"),
+            serviceIds: ToolArgs.scopeServiceIds(accessibleServiceIds, serviceId),
+            hasException: ToolArgs.getBoolean(args, "hasException"),
+            rootOnly: ToolArgs.getBoolean(args, "rootOnly"),
+        });
+        const rows = tableRows.map((row) => {
+            return {
+                [groupBy]: Object.values(row.groupValues).join(" / "),
+                count: row.count,
+                errorCount: row.errorCount,
+                avgMs: Math.round(row.avgDurationMs * 100) / 100,
+                p50Ms: Math.round(row.p50DurationMs * 100) / 100,
+                p90Ms: Math.round(row.p90DurationMs * 100) / 100,
+                p95Ms: Math.round(row.p95DurationMs * 100) / 100,
+                p99Ms: Math.round(row.p99DurationMs * 100) / 100,
+            };
+        });
+        const serialized = ToolResultSerializer.serializeRows(rows);
+        return {
+            dataForLlm: serialized.text,
+            rowCount: serialized.rowCount,
+            citationLabel: `Trace analytics by ${groupBy} (${metric}), ${startTime.toISOString()} – ${endTime.toISOString()}`,
+            citationTarget: {
+                type: AIChatCitationTargetType.Traces,
+            },
+            redactionCount: serialized.redactionCount,
+            isTruncated: serialized.isTruncated,
+            widget: rows.length > 0
+                ? WidgetBuilder.table({
+                    title: `Trace analytics by ${groupBy}`,
+                    description: `Ranked by ${metric} · ${startTime.toISOString()} – ${endTime.toISOString()}`,
+                    columns: [
+                        { key: groupBy, title: groupBy, type: "text" },
+                        { key: "count", title: "Count", type: "number" },
+                        { key: "errorCount", title: "Errors", type: "number" },
+                        { key: "avgMs", title: "Avg (ms)", type: "number" },
+                        { key: "p90Ms", title: "p90 (ms)", type: "number" },
+                        { key: "p95Ms", title: "p95 (ms)", type: "number" },
+                        { key: "p99Ms", title: "p99 (ms)", type: "number" },
+                    ],
+                    rows: rows,
+                    link: { type: AIChatCitationTargetType.Traces },
+                })
+                : undefined,
+        };
+    },
+};
+export const GetTraceTool = {
+    name: "get_trace",
+    description: "Get the span tree (waterfall) of one trace by traceId: every span with its duration, status and whether it recorded an exception. Use after query_traces or search_logs surfaces an interesting traceId.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            traceId: {
+                type: "string",
+                description: "The trace ID (required).",
+            },
+        },
+        required: ["traceId"],
+    },
+    requiredPermissions: TRACE_READ_PERMISSIONS,
+    execute: async (args, ctx) => {
+        var _a, _b;
+        const traceId = ToolArgs.getString(args, "traceId");
+        if (!traceId) {
+            throw new BadDataException("traceId is required.");
+        }
+        const spans = await SpanService.findBy({
+            query: {
+                traceId: traceId,
+            },
+            select: {
+                spanId: true,
+                parentSpanId: true,
+                name: true,
+                startTimeUnixNano: true,
+                durationUnixNano: true,
+                statusCode: true,
+                kind: true,
+            },
+            sort: {
+                startTimeUnixNano: SortOrder.Ascending,
+            },
+            limit: MAX_TRACE_SPANS,
+            skip: 0,
+            props: ctx.props,
+        });
+        const isSpanLimitHit = spans.length >= MAX_TRACE_SPANS;
+        // Build the tree.
+        const nodesBySpanId = new Map();
+        const roots = [];
+        for (const span of spans) {
+            nodesBySpanId.set(((_a = span.spanId) === null || _a === void 0 ? void 0 : _a.toString()) || "", {
+                span,
+                children: [],
+            });
+        }
+        for (const node of nodesBySpanId.values()) {
+            const parentId = ((_b = node.span.parentSpanId) === null || _b === void 0 ? void 0 : _b.toString()) || "";
+            const parent = nodesBySpanId.get(parentId);
+            if (parent && parent !== node) {
+                parent.children.push(node);
+            }
+            else {
+                roots.push(node);
+            }
+        }
+        const lines = [];
+        const renderNode = (node, depth) => {
+            const durationMs = Math.round((Number(node.span.durationUnixNano) / 1000000) * 100) /
+                100;
+            const status = Number(node.span.statusCode) === 2 ? " [ERROR]" : "";
+            lines.push(`${"  ".repeat(depth)}- ${node.span.name} (${durationMs}ms)${status}`);
+            for (const child of node.children) {
+                renderNode(child, depth + 1);
+            }
+        };
+        for (const root of roots) {
+            renderNode(root, 0);
+        }
+        if (isSpanLimitHit) {
+            lines.push(`… trace truncated at ${MAX_TRACE_SPANS} spans; deeper spans are omitted and some shown here may appear as roots because their parent was cut off.`);
+        }
+        const serialized = ToolResultSerializer.serializeText(lines.join("\n"), spans.length);
+        /*
+         * Build the waterfall widget: each span's start is expressed as an offset in
+         * ms from the earliest span start (the trace start), so the renderer can lay
+         * out proportional bars without any wall-clock math.
+         */
+        let traceStartNano = undefined;
+        let traceEndNano = 0;
+        for (const span of spans) {
+            const start = Number(span.startTimeUnixNano);
+            const end = start + Number(span.durationUnixNano);
+            if (traceStartNano === undefined || start < traceStartNano) {
+                traceStartNano = start;
+            }
+            if (end > traceEndNano) {
+                traceEndNano = end;
+            }
+        }
+        const nanoToMs = (nano) => {
+            return Math.round((nano / 1000000) * 100) / 100;
+        };
+        const widgetSpans = spans.map((span) => {
+            var _a, _b;
+            const start = Number(span.startTimeUnixNano);
+            return {
+                spanId: ((_a = span.spanId) === null || _a === void 0 ? void 0 : _a.toString()) || "",
+                parentSpanId: ((_b = span.parentSpanId) === null || _b === void 0 ? void 0 : _b.toString()) || undefined,
+                name: span.name || "(unnamed span)",
+                startOffsetMs: nanoToMs(start - (traceStartNano !== null && traceStartNano !== void 0 ? traceStartNano : start)),
+                durationMs: nanoToMs(Number(span.durationUnixNano)),
+                isError: Number(span.statusCode) === 2,
+            };
+        });
+        const totalDurationMs = traceStartNano !== undefined
+            ? nanoToMs(traceEndNano - traceStartNano)
+            : 0;
+        return {
+            dataForLlm: serialized.text,
+            rowCount: serialized.rowCount,
+            citationLabel: `Trace ${traceId} (${spans.length}${isSpanLimitHit ? "+" : ""} spans)`,
+            citationTarget: {
+                type: AIChatCitationTargetType.TraceView,
+                params: { traceId: traceId },
+            },
+            redactionCount: serialized.redactionCount,
+            isTruncated: serialized.isTruncated || isSpanLimitHit,
+            widget: widgetSpans.length > 0
+                ? WidgetBuilder.traceWaterfall({
+                    title: `Trace waterfall (${spans.length}${isSpanLimitHit ? "+" : ""} spans)`,
+                    description: `${totalDurationMs} ms total`,
+                    spans: widgetSpans,
+                    totalDurationMs: totalDurationMs,
+                    link: {
+                        type: AIChatCitationTargetType.TraceView,
+                        params: { traceId: traceId },
+                    },
+                })
+                : undefined,
+        };
+    },
+};
+//# sourceMappingURL=TraceTools.js.map