@iris-eval/mcp-server 0.3.0 → 0.4.0-rc.1

package/dist/index.js

@@ -8,6 +8,12 @@ import { createStdioTransport } from './transport/stdio.js';
 import { createHttpTransport } from './transport/http.js';
 import { createDashboardServer } from './dashboard/server.js';
 import { createLogger } from './utils/logger.js';
+import { loadOrInitPreferences, shouldAutoLaunchDashboard, createPreferenceStore } from './preferences.js';
+import { openBrowser } from './utils/open-browser.js';
+import { createCustomRuleStore } from './custom-rule-store.js';
+import { createCustomRule } from './eval/rules/custom.js';
+import { LOCAL_TENANT } from './types/tenant.js';
+import { validatePortConfig } from './utils/validate-port-config.js';
 const PortSchema = z
     .string()
     .regex(/^\d+$/, 'must be a positive integer')
@@ -71,16 +77,29 @@ Options:
   -h, --help               Show this help message
 
 Environment variables (CLI flags take precedence):
-  IRIS_TRANSPORT           stdio | http
-  IRIS_HOST                Bind address for HTTP transport (default: 127.0.0.1)
-  IRIS_PORT                HTTP transport port (1-65535)
-  IRIS_DB_PATH             SQLite database path
-  IRIS_LOG_LEVEL           debug | info | warn | error
-  IRIS_DASHBOARD           true to enable web dashboard
-  IRIS_DASHBOARD_PORT      Dashboard port (1-65535, default: 6920)
-  IRIS_API_KEY             API key for HTTP authentication
-  IRIS_ALLOWED_ORIGINS     Comma-separated CORS origin allowlist
-  RATE_LIMIT_SALT          (waitlist API only — required when website is deployed)
+  IRIS_TRANSPORT                       stdio | http
+  IRIS_HOST                            Bind address for HTTP transport (default: 127.0.0.1)
+  IRIS_PORT                            HTTP transport port (1-65535)
+  IRIS_DB_PATH                         SQLite database path
+  IRIS_LOG_LEVEL                       debug | info | warn | error
+  IRIS_DASHBOARD                       true to enable web dashboard
+  IRIS_DASHBOARD_PORT                  Dashboard port (1-65535, default: 6920)
+  IRIS_API_KEY                         API key for HTTP authentication
+  IRIS_ALLOWED_ORIGINS                 Comma-separated CORS origin allowlist
+  IRIS_NO_AUTO_LAUNCH                  Set to 1 to disable first-run dashboard auto-launch
+  IRIS_ANTHROPIC_API_KEY               Required by evaluate_with_llm_judge + verify_citations (provider=anthropic)
+  IRIS_OPENAI_API_KEY                  Required by evaluate_with_llm_judge + verify_citations (provider=openai)
+  IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL Hard cost cap per LLM judge call (default: 0.25)
+  IRIS_CITATION_ALLOW_FETCH            Set to 1 to permit outbound HTTP in verify_citations (off by default)
+  IRIS_CITATION_DOMAINS                Comma-separated hostname allowlist for verify_citations (suffix match)
+  IRIS_OTEL_ENDPOINT                   Enable best-effort OTLP/HTTP JSON trace export to this collector URL
+  IRIS_OTEL_SERVICE_NAME               service.name resource attribute for OTel export (default: iris-mcp)
+  IRIS_OTEL_HEADERS                    Comma-separated k=v headers for OTel export (e.g. "authorization=Bearer abc")
+  IRIS_OTEL_TIMEOUT_MS                 Per-export timeout (default: 15000)
+  RATE_LIMIT_SALT                      (waitlist API only — required when website is deployed)
+
+Dashboard preferences (~/.iris/preferences.json):
+  Edit autoLaunch: false to permanently disable first-run dashboard auto-launch.
 `);
     process.exit(0);
 }
@@ -96,15 +115,38 @@ const config = loadConfig({
 const logger = createLogger(config);
 async function main() {
     logger.info(`Starting Iris MCP server v${config.server.version}`);
+    // F-006: fail fast on HTTP+dashboard port collision. See validatePortConfig.
+    validatePortConfig(config);
     const storage = createStorage(config);
     await storage.initialize();
     logger.info(`Storage initialized (${config.storage.type}: ${config.storage.path})`);
-    const { mcpServer } = createIrisServer(config, storage);
+    // Load the custom rule store first so it can be shared between the
+    // MCP server (for deploy_rule / delete_rule / list_rules tools) and
+    // the HTTP dashboard (Make-This-A-Rule composer). A rule deployed
+    // via either surface is immediately visible from the other.
+    const customRuleStore = createCustomRuleStore();
+    const { mcpServer, evalEngine } = createIrisServer(config, storage, customRuleStore);
+    // Load deployed custom rules from ~/.iris/custom-rules.json (B3 — workflow inversion).
+    // Each enabled rule is registered with the engine under its evalType so it fires on
+    // every evaluate_output call of that category. Persistence via custom-rule-store.
+    const enabled = customRuleStore.enabledRules();
+    for (const rule of enabled) {
+        evalEngine.registerRule(rule.evalType, createCustomRule(rule.definition));
+    }
+    if (enabled.length > 0) {
+        logger.info(`Loaded ${enabled.length} deployed custom rule(s) from ${customRuleStore.filePath}`);
+    }
     const httpServers = [];
-    // Run data retention cleanup on startup
+    // Run data retention cleanup on startup.
+    //
+    // For OSS single-tenant installs we explicitly scope cleanup to
+    // LOCAL_TENANT. Cloud will enumerate all tenants (TenantRegistry) and
+    // call this per-tenant so retention applies uniformly; the adapter
+    // method already scopes DELETEs by tenant, so the behavior scales
+    // cleanly.
     if (config.retention.days > 0) {
         try {
-            const deleted = await storage.deleteTracesOlderThan(config.retention.days);
+            const deleted = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
             if (deleted > 0) {
                 logger.info(`Retention cleanup: deleted ${deleted} trace(s) older than ${config.retention.days} days`);
             }
@@ -130,9 +172,30 @@ async function main() {
         }
     }
     if (config.dashboard.enabled || config.transport.type === 'http') {
-        const dashboardServer = createDashboardServer(storage, config, logger);
+        const preferenceStore = createPreferenceStore();
+        const dashboardServer = createDashboardServer(storage, config, logger, {
+            customRuleStore,
+            evalEngine,
+            preferenceStore,
+        });
         const server = dashboardServer.start();
         httpServers.push(server);
+        // First-run auto-launch (B7): on first dashboard launch, open the
+        // dashboard in the user's default browser. Skipped in CI, when the
+        // user has previously set autoLaunch=false in ~/.iris/preferences.json,
+        // or when IRIS_NO_AUTO_LAUNCH=1 is set.
+        if (config.dashboard.enabled) {
+            const prefState = loadOrInitPreferences();
+            if (prefState.isFirstRun && shouldAutoLaunchDashboard(prefState)) {
+                const url = `http://localhost:${config.dashboard.port}`;
+                logger.info(`First run detected — opening dashboard at ${url}`);
+                logger.info(`(To disable auto-launch: set IRIS_NO_AUTO_LAUNCH=1 or edit ${prefState.path})`);
+                openBrowser(url);
+            }
+            else if (prefState.isFirstRun) {
+                logger.info(`First run detected — skipping auto-launch (CI/IRIS_NO_AUTO_LAUNCH set). Dashboard at http://localhost:${config.dashboard.port}`);
+            }
+        }
     }
     if (config.security.apiKey) {
         logger.info('API key authentication enabled');

package/dist/middleware/index.d.ts

@@ -2,3 +2,4 @@ export { createAuthMiddleware } from './auth.js';
 export { createCorsMiddleware } from './cors.js';
 export { createErrorHandler } from './error-handler.js';
 export { createApiRateLimiter, createMcpRateLimiter } from './rate-limit.js';
+export { createTenantMiddleware, requireTenant } from './tenant.js';

package/dist/middleware/index.js

@@ -2,3 +2,4 @@ export { createAuthMiddleware } from './auth.js';
 export { createCorsMiddleware } from './cors.js';
 export { createErrorHandler } from './error-handler.js';
 export { createApiRateLimiter, createMcpRateLimiter } from './rate-limit.js';
+export { createTenantMiddleware, requireTenant } from './tenant.js';

package/dist/middleware/tenant.d.ts

@@ -0,0 +1,17 @@
+import type { RequestHandler, Request } from 'express';
+import type { TenantId } from '../types/tenant.js';
+declare module 'express-serve-static-core' {
+    interface Request {
+        tenantId?: TenantId;
+    }
+}
+/** Read `req.tenantId` with a fail-safe guarantee for downstream code. */
+export declare function requireTenant(req: Request): TenantId;
+/**
+ * OSS tenant resolver. Every request is the single local user.
+ *
+ * Cloud deployments swap this for an auth-aware resolver that reads the
+ * session. The route handlers don't change — they all just call
+ * requireTenant(req).
+ */
+export declare function createTenantMiddleware(): RequestHandler;

package/dist/middleware/tenant.js

@@ -0,0 +1,26 @@
+import { LOCAL_TENANT } from '../types/tenant.js';
+/** Read `req.tenantId` with a fail-safe guarantee for downstream code. */
+export function requireTenant(req) {
+    const t = req.tenantId;
+    if (!t) {
+        /* Defense in depth. Should never happen if tenant middleware is
+         * mounted before routes, but we fail safe rather than fall back to
+         * LOCAL_TENANT because a missing tenant id is a code path bug, not
+         * a fallback case. */
+        throw new Error('req.tenantId missing; tenant middleware not mounted?');
+    }
+    return t;
+}
+/**
+ * OSS tenant resolver. Every request is the single local user.
+ *
+ * Cloud deployments swap this for an auth-aware resolver that reads the
+ * session. The route handlers don't change — they all just call
+ * requireTenant(req).
+ */
+export function createTenantMiddleware() {
+    return (req, _res, next) => {
+        req.tenantId = LOCAL_TENANT;
+        next();
+    };
+}

package/dist/otel/exporter.d.ts

@@ -0,0 +1,24 @@
+import type { Trace } from '../types/trace.js';
+export interface OtelExporterConfig {
+    endpoint: string;
+    serviceName: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    pathPrefix?: string;
+}
+export interface OtelExportResult {
+    ok: boolean;
+    status: number;
+    bytesSent: number;
+    latencyMs: number;
+    error?: string;
+}
+export declare class OtelExporter {
+    private readonly endpoint;
+    private readonly serviceName;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor(config: OtelExporterConfig);
+    exportTraces(traces: readonly Trace[]): Promise<OtelExportResult>;
+}
+export declare function exporterFromEnv(): OtelExporter | null;

package/dist/otel/exporter.js

@@ -0,0 +1,116 @@
+// OTLP/HTTP JSON exporter — posts ExportTraceServiceRequest payloads to
+// an OpenTelemetry collector, Jaeger, Grafana Tempo, or Datadog OTLP
+// ingest endpoint. Works against any receiver that speaks OTLP/HTTP
+// JSON at /v1/traces (the OTLP spec canonical path).
+//
+// Hand-rolled against the OTLP spec rather than pulling in @opentelemetry/*
+// — consistent with the LLM client + citation resolver approach (keep
+// supply-chain surface small, the wire format is simple). gRPC transport
+// is not included in v0.4.0; callers with gRPC-only receivers should
+// front it with an HTTP-accepting collector (Jaeger/Tempo/OTEL Collector
+// accept HTTP natively).
+//
+// Batch behavior: callers (typically log_trace handler) accumulate Trace
+// rows and call exportTraces([...]) at convenient points. The exporter
+// does NOT own a timer — keeping it stateless keeps it testable and
+// avoids accidentally leaking a process-wide interval in tests.
+import { buildExportPayload } from './mapper.js';
+export class OtelExporter {
+    endpoint;
+    serviceName;
+    headers;
+    timeoutMs;
+    constructor(config) {
+        // Normalize endpoint — strip trailing slash; append /v1/traces if
+        // the caller gave a collector root. This matches the behavior of
+        // the official OTLP/HTTP clients.
+        const base = config.endpoint.replace(/\/+$/, '');
+        const path = config.pathPrefix ?? '/v1/traces';
+        this.endpoint = base.endsWith(path) ? base : base + path;
+        this.serviceName = config.serviceName;
+        this.headers = { ...(config.headers ?? {}) };
+        this.timeoutMs = config.timeoutMs ?? 15_000;
+    }
+    async exportTraces(traces) {
+        if (traces.length === 0) {
+            return { ok: true, status: 204, bytesSent: 0, latencyMs: 0 };
+        }
+        const payload = buildExportPayload(traces, this.serviceName);
+        const body = JSON.stringify(payload);
+        const started = Date.now();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(this.endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    ...this.headers,
+                },
+                body,
+            });
+            const latencyMs = Date.now() - started;
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                return {
+                    ok: false,
+                    status: res.status,
+                    bytesSent: body.length,
+                    latencyMs,
+                    error: `OTLP exporter got ${res.status}: ${text.slice(0, 200)}`,
+                };
+            }
+            return {
+                ok: true,
+                status: res.status,
+                bytesSent: body.length,
+                latencyMs,
+            };
+        }
+        catch (err) {
+            const latencyMs = Date.now() - started;
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                status: 0,
+                bytesSent: body.length,
+                latencyMs,
+                error: msg,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export function exporterFromEnv() {
+    const endpoint = process.env.IRIS_OTEL_ENDPOINT;
+    if (!endpoint)
+        return null;
+    const serviceName = process.env.IRIS_OTEL_SERVICE_NAME ?? 'iris-mcp';
+    // IRIS_OTEL_HEADERS is a comma-separated list of key=value pairs —
+    // the OTel Collector convention. e.g. "authorization=Bearer xyz,x-tenant=foo".
+    let headers;
+    const rawHeaders = process.env.IRIS_OTEL_HEADERS;
+    if (rawHeaders) {
+        headers = {};
+        for (const pair of rawHeaders.split(',')) {
+            const eq = pair.indexOf('=');
+            if (eq < 1)
+                continue;
+            const k = pair.slice(0, eq).trim();
+            const v = pair.slice(eq + 1).trim();
+            if (k && v)
+                headers[k] = v;
+        }
+    }
+    const timeoutRaw = process.env.IRIS_OTEL_TIMEOUT_MS;
+    const timeoutMs = timeoutRaw ? Number(timeoutRaw) : undefined;
+    return new OtelExporter({
+        endpoint,
+        serviceName,
+        headers,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined,
+    });
+}

package/dist/otel/lazy.d.ts

@@ -0,0 +1,5 @@
+import { OtelExporter } from './exporter.js';
+import type { Trace } from '../types/trace.js';
+export declare function getLazyExporter(): OtelExporter | null;
+export declare function __resetExporterForTests(override?: OtelExporter | null): void;
+export declare function bestEffortExport(trace: Trace, onError?: (err: Error) => void): void;

package/dist/otel/lazy.js

@@ -0,0 +1,31 @@
+// Process-wide lazy exporter — initialized on first use, then reused.
+// Tests may reset it via __resetExporterForTests.
+import { exporterFromEnv } from './exporter.js';
+let cachedExporter; // undefined = not yet resolved
+export function getLazyExporter() {
+    if (cachedExporter === undefined) {
+        cachedExporter = exporterFromEnv();
+    }
+    return cachedExporter;
+}
+export function __resetExporterForTests(override) {
+    cachedExporter = override === undefined ? undefined : override;
+}
+// Fire-and-forget wrapper with inline error swallow. Runs in the
+// background; the caller does NOT await. We log on failure so operators
+// aren't surprised by silent drop, but never let an exporter problem
+// bubble into user-visible tool errors.
+export function bestEffortExport(trace, onError) {
+    const exporter = getLazyExporter();
+    if (!exporter)
+        return;
+    exporter
+        .exportTraces([trace])
+        .then((result) => {
+        if (!result.ok) {
+            const msg = `OTel export failed: status=${result.status} ${result.error ?? ''}`.trim();
+            onError?.(new Error(msg));
+        }
+    })
+        .catch((err) => onError?.(err));
+}

package/dist/otel/mapper.d.ts

@@ -0,0 +1,24 @@
+import type { Span, Trace } from '../types/trace.js';
+export interface OtlpKeyValue {
+    key: string;
+    value: OtlpAnyValue;
+}
+export type OtlpAnyValue = {
+    stringValue: string;
+} | {
+    boolValue: boolean;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    arrayValue: {
+        values: OtlpAnyValue[];
+    };
+} | {
+    kvlistValue: {
+        values: OtlpKeyValue[];
+    };
+};
+export declare function mapSpan(span: Span, traceIdOverride?: string): unknown;
+export declare function buildExportPayload(traces: readonly Trace[], serviceName: string): unknown;

package/dist/otel/mapper.js

@@ -0,0 +1,208 @@
+// Map Iris trace/span types to OTLP JSON shape for export.
+//
+// Reference: https://opentelemetry.io/docs/specs/otlp/#otlphttp-json-encoding
+// and the ExportTraceServiceRequest proto. OTLP JSON encodes uint64 IDs
+// as lowercase hex strings; trace_id is 16 bytes (32 hex chars), span_id
+// is 8 bytes (16 hex chars). Timestamps are nanoseconds since epoch as
+// strings (uint64 range exceeds JS Number.MAX_SAFE_INTEGER so we emit as
+// decimal string).
+//
+// We intentionally do not depend on @opentelemetry/* — the exporter
+// serializes these plain objects, and the payload shape is the OTLP spec.
+// OTel SpanKind enum values (from opentelemetry-proto/trace/v1/trace.proto).
+const KIND_MAP = {
+    INTERNAL: 1,
+    SERVER: 2,
+    CLIENT: 3,
+    PRODUCER: 4,
+    CONSUMER: 5,
+    // Iris-specific kinds — map to INTERNAL for OTel. The actual LLM /
+    // tool semantics are preserved in attributes (llm.provider, tool.name).
+    LLM: 1,
+    TOOL: 1,
+};
+const STATUS_MAP = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+// Convert "abcdef0123..." (any length hex) to exactly 32 hex chars, or
+// if non-hex, hash it. Iris sometimes generates IDs like "mcp-<uuid>"
+// that aren't pure hex.
+function toTraceIdHex(raw) {
+    const hex = raw.replace(/-/g, '').toLowerCase();
+    if (/^[0-9a-f]{32}$/.test(hex))
+        return hex;
+    if (/^[0-9a-f]{16,}$/.test(hex))
+        return hex.slice(0, 32).padEnd(32, '0');
+    // Fallback: hash to 32 hex chars deterministically.
+    return djb2Hex(raw, 32);
+}
+function toSpanIdHex(raw) {
+    const hex = raw.replace(/-/g, '').toLowerCase();
+    if (/^[0-9a-f]{16}$/.test(hex))
+        return hex;
+    if (/^[0-9a-f]{8,}$/.test(hex))
+        return hex.slice(0, 16).padEnd(16, '0');
+    return djb2Hex(raw, 16);
+}
+// Tiny deterministic string → hex hash. Not cryptographic — just to give
+// OTel consumers a stable id when Iris produced a non-hex identifier.
+function djb2Hex(s, hexLen) {
+    let h = 5381n;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5n) + h + BigInt(s.charCodeAt(i))) & ((1n << 64n) - 1n);
+    }
+    // Use BigInt to avoid JS Number collisions on long strings.
+    let hex = h.toString(16);
+    while (hex.length < hexLen)
+        hex = hex + djb2Step(s + hex).toString(16);
+    return hex.slice(0, hexLen).padEnd(hexLen, '0');
+}
+function djb2Step(s) {
+    let h = 5381n;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5n) + h + BigInt(s.charCodeAt(i))) & ((1n << 64n) - 1n);
+    }
+    return h;
+}
+function toNanoString(iso) {
+    if (!iso)
+        return '0';
+    const ms = new Date(iso).getTime();
+    if (!Number.isFinite(ms))
+        return '0';
+    // ms → ns as string (BigInt-safe).
+    return (BigInt(ms) * 1000000n).toString();
+}
+function toAnyValue(v) {
+    if (typeof v === 'string')
+        return { stringValue: v };
+    if (typeof v === 'boolean')
+        return { boolValue: v };
+    if (typeof v === 'number') {
+        if (Number.isInteger(v))
+            return { intValue: String(v) };
+        return { doubleValue: v };
+    }
+    if (Array.isArray(v)) {
+        return { arrayValue: { values: v.map(toAnyValue) } };
+    }
+    if (v && typeof v === 'object') {
+        return {
+            kvlistValue: {
+                values: Object.entries(v).map(([k, val]) => ({
+                    key: k,
+                    value: toAnyValue(val),
+                })),
+            },
+        };
+    }
+    // null / undefined / bigint / fn / symbol — fall back to string
+    return { stringValue: String(v) };
+}
+function flattenAttrs(attrs) {
+    if (!attrs)
+        return [];
+    return Object.entries(attrs).map(([k, v]) => ({ key: k, value: toAnyValue(v) }));
+}
+// Iris Span → OTLP Span JSON shape.
+export function mapSpan(span, traceIdOverride) {
+    const attributes = flattenAttrs(span.attributes);
+    // Surface Iris-specific kinds via attributes so OTel consumers can
+    // filter on iris.span_kind even though we mapped everything non-OTel to INTERNAL.
+    if (span.kind === 'LLM' || span.kind === 'TOOL') {
+        attributes.push({ key: 'iris.span_kind', value: { stringValue: span.kind } });
+    }
+    const events = (span.events ?? []).map((e) => ({
+        timeUnixNano: toNanoString(e.timestamp),
+        name: e.name,
+        attributes: flattenAttrs(e.attributes),
+    }));
+    return {
+        traceId: toTraceIdHex(traceIdOverride ?? span.trace_id),
+        spanId: toSpanIdHex(span.span_id),
+        parentSpanId: span.parent_span_id ? toSpanIdHex(span.parent_span_id) : undefined,
+        name: span.name,
+        kind: KIND_MAP[span.kind] ?? 1,
+        startTimeUnixNano: toNanoString(span.start_time),
+        endTimeUnixNano: toNanoString(span.end_time ?? span.start_time),
+        attributes,
+        events,
+        status: {
+            code: STATUS_MAP[span.status_code] ?? 0,
+            message: span.status_message,
+        },
+    };
+}
+// Build a full OTLP ExportTraceServiceRequest payload from an Iris trace.
+// If the trace has no explicit spans, we synthesize one root span from
+// the trace-level fields (agent_name + latency + cost + token_usage as
+// attributes) so exports aren't empty for simple trace rows.
+export function buildExportPayload(traces, serviceName) {
+    const resource = {
+        attributes: [
+            { key: 'service.name', value: { stringValue: serviceName } },
+            { key: 'telemetry.sdk.name', value: { stringValue: 'iris-mcp' } },
+            { key: 'telemetry.sdk.language', value: { stringValue: 'nodejs' } },
+            { key: 'telemetry.sdk.version', value: { stringValue: '0.4.0' } },
+        ],
+    };
+    const spans = [];
+    for (const trace of traces) {
+        if (trace.spans && trace.spans.length > 0) {
+            for (const s of trace.spans)
+                spans.push(mapSpan(s, trace.trace_id));
+        }
+        else {
+            // Synthesize root span from trace-level info.
+            const attrs = {
+                'iris.agent_name': trace.agent_name,
+                'iris.framework': trace.framework,
+            };
+            if (trace.input)
+                attrs['iris.input'] = truncate(trace.input);
+            if (trace.output)
+                attrs['iris.output'] = truncate(trace.output);
+            if (trace.cost_usd !== undefined)
+                attrs['iris.cost_usd'] = trace.cost_usd;
+            if (trace.token_usage?.total_tokens !== undefined)
+                attrs['iris.total_tokens'] = trace.token_usage.total_tokens;
+            if (trace.token_usage?.prompt_tokens !== undefined)
+                attrs['iris.prompt_tokens'] = trace.token_usage.prompt_tokens;
+            if (trace.token_usage?.completion_tokens !== undefined)
+                attrs['iris.completion_tokens'] = trace.token_usage.completion_tokens;
+            const end = trace.latency_ms
+                ? new Date(new Date(trace.timestamp).getTime() + trace.latency_ms).toISOString()
+                : trace.timestamp;
+            spans.push({
+                traceId: toTraceIdHex(trace.trace_id),
+                spanId: toSpanIdHex(trace.trace_id + ':root'),
+                parentSpanId: undefined,
+                name: trace.agent_name || 'agent_execution',
+                kind: 1,
+                startTimeUnixNano: toNanoString(trace.timestamp),
+                endTimeUnixNano: toNanoString(end),
+                attributes: flattenAttrs(attrs),
+                events: [],
+                status: { code: 0 },
+            });
+        }
+    }
+    return {
+        resourceSpans: [
+            {
+                resource,
+                scopeSpans: [
+                    {
+                        scope: { name: 'iris.trace.v1' },
+                        spans,
+                    },
+                ],
+            },
+        ],
+    };
+}
+function truncate(s, max = 4096) {
+    return s.length > max ? s.slice(0, max) + '…' : s;
+}