@agentium/observability 1.0.0

package/dist/index.js

@@ -0,0 +1,1333 @@
+// src/exporters/callback.ts
+var CallbackExporter = class {
+  name = "callback";
+  callback;
+  constructor(callback) {
+    this.callback = callback;
+  }
+  async export(trace) {
+    await this.callback(trace);
+  }
+};
+
+// src/exporters/console.ts
+var C = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  magenta: "\x1B[35m",
+  gray: "\x1B[90m",
+  brightCyan: "\x1B[96m",
+  brightGreen: "\x1B[92m"
+};
+function c(code, text) {
+  return `${code}${text}${C.reset}`;
+}
+function statusIcon(status) {
+  if (status === "ok") return c(C.green, "\u2713");
+  if (status === "error") return c(C.red, "\u2717");
+  return c(C.yellow, "\u22EF");
+}
+function kindColor(kind) {
+  switch (kind) {
+    case "agent":
+      return C.brightCyan;
+    case "llm":
+      return C.yellow;
+    case "tool":
+      return C.magenta;
+    case "handoff":
+      return C.brightGreen;
+    case "team":
+      return C.cyan;
+    default:
+      return C.gray;
+  }
+}
+var ConsoleExporter = class {
+  name = "console";
+  async export(trace) {
+    const line = c(C.dim, "\u2500".repeat(80));
+    console.log(`
+${line}`);
+    console.log(
+      `  ${c(C.bold + C.brightCyan, "Trace")} ${c(C.dim, trace.traceId)} ${c(C.dim, "duration=")}${c(C.brightGreen, `${trace.durationMs ?? "?"}ms`)}`
+    );
+    if (trace.metadata.agentName) {
+      console.log(`  ${c(C.dim, "agent=")}${trace.metadata.agentName}`);
+    }
+    console.log(line);
+    const spanMap = /* @__PURE__ */ new Map();
+    for (const span of trace.spans) {
+      const parentId = span.parentSpanId ?? "__root__";
+      if (!spanMap.has(parentId)) spanMap.set(parentId, []);
+      spanMap.get(parentId).push(span);
+    }
+    const root = trace.spans.find((s) => s.spanId === trace.rootSpanId);
+    if (root) {
+      this.printSpan(root, spanMap, 0, trace.startTime);
+    }
+    console.log(line);
+    console.log("");
+  }
+  printSpan(span, childMap, depth, traceStart) {
+    const indent = `  ${"\u2502 ".repeat(depth)}`;
+    const connector = depth > 0 ? "\u251C\u2500 " : "";
+    const offset = span.startTime - traceStart;
+    const dur = span.durationMs ?? "?";
+    const kc = kindColor(span.kind);
+    const icon = statusIcon(span.status);
+    let line = `${indent}${connector}${icon} ${c(kc, span.name)}`;
+    line += ` ${c(C.dim, `[${offset}ms \u2192 +${dur}ms]`)}`;
+    if (span.attributes.tokens) {
+      line += ` ${c(C.brightGreen, `${span.attributes.tokens} tok`)}`;
+    }
+    if (span.attributes.toolName) {
+      line += ` ${c(C.dim, `(${span.attributes.toolName})`)}`;
+    }
+    if (span.attributes.cached) {
+      line += ` ${c(C.yellow, "[cached]")}`;
+    }
+    if (span.status === "error" && span.attributes.error) {
+      line += ` ${c(C.red, String(span.attributes.error))}`;
+    }
+    console.log(line);
+    for (const evt of span.events) {
+      console.log(
+        `${indent}\u2502 ${c(C.dim, `\u2937 ${evt.name}`)}${evt.attributes ? c(C.gray, ` ${JSON.stringify(evt.attributes)}`) : ""}`
+      );
+    }
+    const children = childMap.get(span.spanId) ?? [];
+    for (const child of children) {
+      this.printSpan(child, childMap, depth + 1, traceStart);
+    }
+  }
+};
+
+// src/exporters/json-file.ts
+import { appendFile, writeFile } from "fs/promises";
+var JsonFileExporter = class {
+  name = "json-file";
+  path;
+  mode;
+  pretty;
+  constructor(config) {
+    this.mode = config?.mode ?? "append";
+    this.path = config?.path ?? `traces-${Date.now()}.${this.mode === "append" ? "jsonl" : "json"}`;
+    this.pretty = config?.pretty ?? true;
+  }
+  async export(trace) {
+    const json = this.pretty ? JSON.stringify(trace, null, 2) : JSON.stringify(trace);
+    try {
+      if (this.mode === "append") {
+        await appendFile(this.path, `${json}
+`);
+      } else {
+        await writeFile(this.path, json);
+      }
+    } catch (err) {
+      console.warn(
+        `[agentium/observability] Failed to write trace to ${this.path}:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+};
+
+// src/exporters/langfuse.ts
+var eventCounter = 0;
+function eventId() {
+  return `evt_${Date.now().toString(36)}_${(eventCounter++).toString(36)}`;
+}
+function extractIO(span) {
+  const input = span.attributes.input ?? null;
+  const output = span.attributes.output ?? null;
+  return { input, output };
+}
+var LangfuseExporter = class {
+  name = "langfuse";
+  publicKey;
+  secretKey;
+  baseUrl;
+  constructor(config) {
+    this.publicKey = config?.publicKey ?? process.env.LANGFUSE_PUBLIC_KEY ?? "";
+    this.secretKey = config?.secretKey ?? process.env.LANGFUSE_SECRET_KEY ?? "";
+    this.baseUrl = (config?.baseUrl ?? process.env.LANGFUSE_BASE_URL ?? "https://cloud.langfuse.com").replace(
+      /\/$/,
+      ""
+    );
+    if (!this.publicKey || !this.secretKey) {
+      throw new Error(
+        "LangfuseExporter: missing credentials. Set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY env vars, or pass them in config."
+      );
+    }
+  }
+  async fetchWithRetry(url, init, retries = 2) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1e4);
+        const res = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeout);
+        if (res.status >= 500 && attempt < retries) {
+          await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
+          continue;
+        }
+        return res;
+      } catch (err) {
+        if (attempt === retries) throw err;
+        await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
+      }
+    }
+    throw new Error("Unreachable");
+  }
+  async export(trace) {
+    const events = [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const rootSpan = trace.spans.find((s) => s.spanId === trace.rootSpanId);
+    events.push({
+      id: eventId(),
+      type: "trace-create",
+      timestamp: now,
+      body: {
+        id: trace.traceId,
+        name: String(trace.metadata.agentName ?? "agent.run"),
+        input: trace.metadata.input ?? rootSpan?.attributes.input ?? null,
+        output: trace.metadata.output ?? rootSpan?.attributes.output ?? null,
+        metadata: { ...trace.metadata, input: void 0, output: void 0 },
+        timestamp: new Date(trace.startTime).toISOString()
+      }
+    });
+    for (const span of trace.spans) {
+      const { input, output } = extractIO(span);
+      const { input: _i, output: _o, ...restAttrs } = span.attributes;
+      if (span.kind === "llm" || span.name.startsWith("llm.")) {
+        events.push({
+          id: eventId(),
+          type: "generation-create",
+          timestamp: now,
+          body: {
+            id: span.spanId,
+            traceId: trace.traceId,
+            parentObservationId: span.parentSpanId,
+            name: span.name,
+            model: span.attributes.modelId ?? void 0,
+            input,
+            output,
+            startTime: new Date(span.startTime).toISOString(),
+            endTime: span.endTime ? new Date(span.endTime).toISOString() : void 0,
+            usage: {
+              promptTokens: span.attributes.promptTokens,
+              completionTokens: span.attributes.completionTokens,
+              totalTokens: span.attributes.tokens
+            },
+            metadata: {
+              ...restAttrs,
+              ...span.attributes.providerMetrics ? { providerMetrics: span.attributes.providerMetrics } : {}
+            }
+          }
+        });
+      } else {
+        events.push({
+          id: eventId(),
+          type: "span-create",
+          timestamp: now,
+          body: {
+            id: span.spanId,
+            traceId: trace.traceId,
+            parentObservationId: span.parentSpanId,
+            name: span.name,
+            input,
+            output,
+            startTime: new Date(span.startTime).toISOString(),
+            endTime: span.endTime ? new Date(span.endTime).toISOString() : void 0,
+            metadata: restAttrs,
+            level: span.status === "error" ? "ERROR" : "DEFAULT"
+          }
+        });
+      }
+    }
+    const auth = Buffer.from(`${this.publicKey}:${this.secretKey}`).toString("base64");
+    const res = await this.fetchWithRetry(`${this.baseUrl}/api/public/ingestion`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${auth}`
+      },
+      body: JSON.stringify({ batch: events })
+    });
+    if (!res.ok && res.status !== 207) {
+      throw new Error(`Langfuse export failed: ${res.status} ${res.statusText}`);
+    }
+    if (res.status === 207) {
+      const body = await res.json();
+      if (body.errors && body.errors.length > 0) {
+        const realErrors = body.errors.filter((e) => e.status >= 400);
+        if (realErrors.length > 0) {
+          throw new Error(`Langfuse partial failure: ${JSON.stringify(realErrors[0])}`);
+        }
+      }
+    }
+  }
+};
+
+// src/exporters/otel.ts
+function parseEnvHeaders(raw) {
+  if (!raw) return {};
+  const result = {};
+  for (const pair of raw.split(",")) {
+    const [k, ...v] = pair.split("=");
+    if (k) result[k.trim()] = v.join("=").trim();
+  }
+  return result;
+}
+var OTelExporter = class {
+  name = "otel";
+  endpoint;
+  headers;
+  serviceName;
+  constructor(config) {
+    const ep = config?.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "";
+    if (!ep) {
+      throw new Error("OTelExporter: missing endpoint. Set OTEL_EXPORTER_OTLP_ENDPOINT env var, or pass it in config.");
+    }
+    this.endpoint = ep.replace(/\/$/, "");
+    this.headers = config?.headers ?? parseEnvHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS);
+    this.serviceName = config?.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "agentium";
+  }
+  async fetchWithRetry(url, init, retries = 2) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 1e4);
+        const res = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeout);
+        if (res.status >= 500 && attempt < retries) {
+          await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
+          continue;
+        }
+        return res;
+      } catch (err) {
+        if (attempt === retries) throw err;
+        await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
+      }
+    }
+    throw new Error("Unreachable");
+  }
+  async export(trace) {
+    const otlpSpans = trace.spans.map((span) => ({
+      traceId: this.padHex(span.traceId, 32),
+      spanId: this.padHex(span.spanId, 16),
+      parentSpanId: span.parentSpanId ? this.padHex(span.parentSpanId, 16) : void 0,
+      name: span.name,
+      kind: this.mapKind(span.kind),
+      startTimeUnixNano: String(span.startTime * 1e6),
+      endTimeUnixNano: span.endTime ? String(span.endTime * 1e6) : void 0,
+      status: {
+        code: span.status === "error" ? 2 : 1,
+        message: span.status === "error" ? String(span.attributes.error ?? "") : void 0
+      },
+      attributes: Object.entries(span.attributes).map(([key, value]) => ({
+        key,
+        value: this.toOtlpValue(value)
+      })),
+      events: span.events.map((evt) => ({
+        name: evt.name,
+        timeUnixNano: String(evt.timestamp * 1e6),
+        attributes: evt.attributes ? Object.entries(evt.attributes).map(([k, v]) => ({ key: k, value: this.toOtlpValue(v) })) : []
+      }))
+    }));
+    const payload = {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [{ key: "service.name", value: { stringValue: this.serviceName } }]
+          },
+          scopeSpans: [
+            {
+              scope: { name: "@agentium/observability" },
+              spans: otlpSpans
+            }
+          ]
+        }
+      ]
+    };
+    const url = `${this.endpoint}/v1/traces`;
+    const res = await this.fetchWithRetry(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.headers
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!res.ok) {
+      throw new Error(`OTLP export failed: ${res.status} ${res.statusText}`);
+    }
+  }
+  padHex(id, length) {
+    let hex = "";
+    for (let i = 0; i < id.length; i++) {
+      hex += id.charCodeAt(i).toString(16).padStart(2, "0");
+    }
+    return hex.padStart(length, "0").slice(-length);
+  }
+  mapKind(kind) {
+    switch (kind) {
+      case "agent":
+        return 1;
+      case "llm":
+        return 3;
+      case "tool":
+        return 3;
+      default:
+        return 0;
+    }
+  }
+  toOtlpValue(value) {
+    if (typeof value === "string") return { stringValue: value };
+    if (typeof value === "number")
+      return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+    if (typeof value === "boolean") return { boolValue: value };
+    if (Array.isArray(value)) return { stringValue: JSON.stringify(value) };
+    return { stringValue: String(value) };
+  }
+};
+
+// src/metrics.ts
+var MetricsCollector = class {
+  counters = {
+    runs_total: 0,
+    runs_success: 0,
+    runs_error: 0,
+    tool_calls_total: 0,
+    handoffs_total: 0,
+    cache_hits: 0,
+    cache_misses: 0
+  };
+  histograms = {
+    run_duration_ms: [],
+    tool_latency_ms: []
+  };
+  gauges = {
+    total_cost_usd: 0,
+    total_tokens: 0,
+    prompt_tokens: 0,
+    completion_tokens: 0,
+    reasoning_tokens: 0,
+    cached_tokens: 0,
+    audio_input_tokens: 0,
+    audio_output_tokens: 0
+  };
+  MAX_HISTOGRAM_SIZE = 1e4;
+  toolStartTimes = /* @__PURE__ */ new Map();
+  runStartTimes = /* @__PURE__ */ new Map();
+  listeners = [];
+  attach(eventBus) {
+    const on = (event, handler) => {
+      eventBus.on(event, handler);
+      this.listeners.push({ event, handler });
+    };
+    on("run.start", (data) => {
+      this.counters.runs_total++;
+      this.runStartTimes.set(data.runId, Date.now());
+    });
+    on("run.complete", (data) => {
+      this.counters.runs_success++;
+      const startTime = this.runStartTimes.get(data.runId);
+      if (startTime) {
+        const duration = Date.now() - startTime;
+        this.histograms.run_duration_ms.push(duration);
+        if (this.histograms.run_duration_ms.length > this.MAX_HISTOGRAM_SIZE) {
+          this.histograms.run_duration_ms = this.histograms.run_duration_ms.slice(-this.MAX_HISTOGRAM_SIZE);
+        }
+        this.runStartTimes.delete(data.runId);
+      }
+      if (data.output?.usage) {
+        this.gauges.total_tokens += data.output.usage.totalTokens ?? 0;
+        this.gauges.prompt_tokens += data.output.usage.promptTokens ?? 0;
+        this.gauges.completion_tokens += data.output.usage.completionTokens ?? 0;
+        this.gauges.reasoning_tokens += data.output.usage.reasoningTokens ?? 0;
+        this.gauges.cached_tokens += data.output.usage.cachedTokens ?? 0;
+        this.gauges.audio_input_tokens += data.output.usage.audioInputTokens ?? 0;
+        this.gauges.audio_output_tokens += data.output.usage.audioOutputTokens ?? 0;
+      }
+      for (const key of this.toolStartTimes.keys()) {
+        if (key.startsWith(`${data.runId}:`)) this.toolStartTimes.delete(key);
+      }
+    });
+    on("run.error", (data) => {
+      this.counters.runs_error++;
+      const startTime = this.runStartTimes.get(data.runId);
+      if (startTime) {
+        const duration = Date.now() - startTime;
+        this.histograms.run_duration_ms.push(duration);
+        if (this.histograms.run_duration_ms.length > this.MAX_HISTOGRAM_SIZE) {
+          this.histograms.run_duration_ms = this.histograms.run_duration_ms.slice(-this.MAX_HISTOGRAM_SIZE);
+        }
+        this.runStartTimes.delete(data.runId);
+      }
+      for (const key of this.toolStartTimes.keys()) {
+        if (key.startsWith(`${data.runId}:`)) this.toolStartTimes.delete(key);
+      }
+    });
+    on("tool.call", (data) => {
+      this.counters.tool_calls_total++;
+      this.toolStartTimes.set(`${data.runId}:${data.toolName}`, Date.now());
+    });
+    on("tool.result", (data) => {
+      const key = `${data.runId}:${data.toolName}`;
+      const start = this.toolStartTimes.get(key);
+      if (start) {
+        this.histograms.tool_latency_ms.push(Date.now() - start);
+        if (this.histograms.tool_latency_ms.length > this.MAX_HISTOGRAM_SIZE) {
+          this.histograms.tool_latency_ms = this.histograms.tool_latency_ms.slice(-this.MAX_HISTOGRAM_SIZE);
+        }
+        this.toolStartTimes.delete(key);
+      }
+    });
+    on("handoff.transfer", () => {
+      this.counters.handoffs_total++;
+    });
+    on("cache.hit", () => {
+      this.counters.cache_hits++;
+    });
+    on("cache.miss", () => {
+      this.counters.cache_misses++;
+    });
+    on("cost.tracked", (data) => {
+      const cost = data.cost ?? data.usage?.cost ?? 0;
+      if (cost) {
+        this.gauges.total_cost_usd += cost;
+      }
+    });
+  }
+  detach(eventBus) {
+    for (const { event, handler } of this.listeners) {
+      eventBus.off(event, handler);
+    }
+    this.listeners = [];
+  }
+  getMetrics() {
+    const totalCacheAttempts = this.counters.cache_hits + this.counters.cache_misses;
+    return {
+      counters: { ...this.counters },
+      histograms: {
+        run_duration_ms: [...this.histograms.run_duration_ms],
+        tool_latency_ms: [...this.histograms.tool_latency_ms]
+      },
+      gauges: { ...this.gauges },
+      rates: {
+        cache_hit_ratio: totalCacheAttempts > 0 ? this.counters.cache_hits / totalCacheAttempts : 0,
+        error_rate: this.counters.runs_total > 0 ? this.counters.runs_error / this.counters.runs_total : 0
+      },
+      timestamp: Date.now()
+    };
+  }
+  reset() {
+    this.counters = {
+      runs_total: 0,
+      runs_success: 0,
+      runs_error: 0,
+      tool_calls_total: 0,
+      handoffs_total: 0,
+      cache_hits: 0,
+      cache_misses: 0
+    };
+    this.histograms = {
+      run_duration_ms: [],
+      tool_latency_ms: []
+    };
+    this.gauges = {
+      total_cost_usd: 0,
+      total_tokens: 0,
+      prompt_tokens: 0,
+      completion_tokens: 0,
+      reasoning_tokens: 0,
+      cached_tokens: 0,
+      audio_input_tokens: 0,
+      audio_output_tokens: 0
+    };
+    this.toolStartTimes.clear();
+    this.runStartTimes.clear();
+  }
+};
+
+// src/structured-logger.ts
+var StructuredLogger = class {
+  drain;
+  tracer;
+  listeners = [];
+  constructor(drain = "json", tracer) {
+    this.drain = drain;
+    this.tracer = tracer ?? null;
+  }
+  attach(eventBus) {
+    const on = (event, handler) => {
+      eventBus.on(event, handler);
+      this.listeners.push({ event, handler });
+    };
+    on("run.start", (data) => {
+      this.log(
+        "info",
+        "Run started",
+        data.agentName,
+        {
+          runId: data.runId,
+          input: data.input?.slice(0, 200) ?? ""
+        },
+        data.runId
+      );
+    });
+    on("run.complete", (data) => {
+      this.log(
+        "info",
+        "Run completed",
+        data.output?.agentName ?? void 0,
+        {
+          runId: data.runId,
+          tokens: data.output?.usage?.totalTokens,
+          promptTokens: data.output?.usage?.promptTokens,
+          completionTokens: data.output?.usage?.completionTokens,
+          reasoningTokens: data.output?.usage?.reasoningTokens,
+          durationMs: data.output?.durationMs,
+          providerMetrics: data.output?.usage?.providerMetrics
+        },
+        data.runId
+      );
+    });
+    on("run.error", (data) => {
+      this.log(
+        "error",
+        `Run failed: ${data.error?.message ?? "unknown error"}`,
+        void 0,
+        {
+          runId: data.runId,
+          error: data.error?.message ?? "unknown error",
+          stack: data.error?.stack?.split("\n").slice(0, 3).join("\n")
+        },
+        data.runId
+      );
+    });
+    on("tool.call", (data) => {
+      this.log(
+        "debug",
+        `Tool call: ${data.toolName}`,
+        void 0,
+        {
+          runId: data.runId,
+          toolName: data.toolName
+        },
+        data.runId
+      );
+    });
+    on("tool.result", (data) => {
+      this.log(
+        "debug",
+        `Tool result: ${data.toolName}`,
+        void 0,
+        {
+          runId: data.runId,
+          toolName: data.toolName
+        },
+        data.runId
+      );
+    });
+    on("handoff.transfer", (data) => {
+      this.log(
+        "info",
+        `Handoff: ${data.fromAgent} -> ${data.toAgent}`,
+        data.fromAgent,
+        {
+          runId: data.runId,
+          toAgent: data.toAgent,
+          reason: data.reason
+        },
+        data.runId
+      );
+    });
+    on("cache.hit", (data) => {
+      this.log("debug", "Cache hit", data.agentName, {
+        input: data.input?.slice(0, 100) ?? ""
+      });
+    });
+    on("cache.miss", (data) => {
+      this.log("debug", "Cache miss", data.agentName, {
+        input: data.input?.slice(0, 100) ?? ""
+      });
+    });
+    on("cost.tracked", (data) => {
+      this.log(
+        "info",
+        `Cost tracked: ${data.modelId}`,
+        data.agentName,
+        {
+          runId: data.runId,
+          modelId: data.modelId,
+          tokens: data.usage?.totalTokens,
+          promptTokens: data.usage?.promptTokens,
+          completionTokens: data.usage?.completionTokens,
+          reasoningTokens: data.usage?.reasoningTokens,
+          cachedTokens: data.usage?.cachedTokens,
+          audioInputTokens: data.usage?.audioInputTokens,
+          audioOutputTokens: data.usage?.audioOutputTokens
+        },
+        data.runId
+      );
+    });
+  }
+  detach(eventBus) {
+    for (const { event, handler } of this.listeners) {
+      eventBus.off(event, handler);
+    }
+    this.listeners = [];
+  }
+  log(level, message, agentName, attributes, runId) {
+    const traceId = runId && this.tracer ? this.tracer.getTraceByRunId(runId)?.traceId : void 0;
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      message,
+      traceId,
+      agentName,
+      attributes
+    };
+    if (typeof this.drain === "function") {
+      this.drain(entry);
+    } else if (this.drain === "json") {
+      console.log(JSON.stringify(entry));
+    } else {
+      console.log(`[${entry.timestamp}] ${level.toUpperCase()} ${message}${traceId ? ` trace=${traceId}` : ""}`);
+    }
+  }
+};
+
+// src/tracer.ts
+var idCounter = 0;
+function genId() {
+  return `${Date.now().toString(36)}_${(idCounter++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+var Tracer = class {
+  traces = /* @__PURE__ */ new Map();
+  runToTrace = /* @__PURE__ */ new Map();
+  runToRootSpan = /* @__PURE__ */ new Map();
+  activeSpans = /* @__PURE__ */ new Map();
+  exporters;
+  listeners = [];
+  pendingExports = [];
+  maxTraces = 1e3;
+  constructor(exporters = []) {
+    this.exporters = exporters;
+  }
+  attach(eventBus) {
+    const on = (event, handler) => {
+      eventBus.on(event, handler);
+      this.listeners.push({ event, handler });
+    };
+    on("run.start", (data) => {
+      const traceId = genId();
+      const inputText = data.input?.slice(0, 1e3) ?? "";
+      const span = this.startSpan(traceId, "agent.run", "agent", {
+        agentName: data.agentName,
+        input: inputText,
+        runId: data.runId
+      });
+      this.runToTrace.set(data.runId, traceId);
+      this.runToRootSpan.set(data.runId, span.spanId);
+      const trace = {
+        traceId,
+        spans: [span],
+        rootSpanId: span.spanId,
+        startTime: span.startTime,
+        metadata: { agentName: data.agentName, runId: data.runId, input: inputText }
+      };
+      this.traces.set(traceId, trace);
+      this.activeSpans.set(`${data.runId}:root`, span);
+    });
+    on("run.complete", (data) => {
+      const span = this.activeSpans.get(`${data.runId}:root`);
+      if (span) {
+        const outputText = data.output?.text?.slice(0, 2e3) ?? "";
+        span.attributes.output = outputText;
+        span.attributes.outputLength = data.output?.text?.length ?? 0;
+        span.attributes.tokens = data.output?.usage?.totalTokens ?? 0;
+        span.attributes.promptTokens = data.output?.usage?.promptTokens ?? 0;
+        span.attributes.completionTokens = data.output?.usage?.completionTokens ?? 0;
+        span.attributes.reasoningTokens = data.output?.usage?.reasoningTokens ?? 0;
+        span.attributes.cachedTokens = data.output?.usage?.cachedTokens ?? 0;
+        span.attributes.audioInputTokens = data.output?.usage?.audioInputTokens ?? 0;
+        span.attributes.audioOutputTokens = data.output?.usage?.audioOutputTokens ?? 0;
+        if (data.output?.usage?.providerMetrics) {
+          span.attributes.providerMetrics = data.output.usage.providerMetrics;
+        }
+        this.endSpan(span, "ok");
+        this.activeSpans.delete(`${data.runId}:root`);
+        const traceId = this.runToTrace.get(data.runId);
+        const trace = traceId ? this.traces.get(traceId) : void 0;
+        if (trace) {
+          trace.metadata.output = outputText;
+        }
+        this.finalizeTrace(data.runId);
+      }
+    });
+    on("run.error", (data) => {
+      const span = this.activeSpans.get(`${data.runId}:root`);
+      if (span) {
+        span.attributes.error = data.error.message;
+        this.endSpan(span, "error");
+        this.activeSpans.delete(`${data.runId}:root`);
+        this.finalizeTrace(data.runId);
+      }
+    });
+    on("tool.call", (data) => {
+      const traceId = this.runToTrace.get(data.runId);
+      const parentId = this.runToRootSpan.get(data.runId);
+      if (!traceId) return;
+      const argsStr = typeof data.args === "string" ? data.args : JSON.stringify(data.args ?? {});
+      const span = this.startSpan(
+        traceId,
+        `tool.${data.toolName}`,
+        "tool",
+        {
+          toolName: data.toolName,
+          runId: data.runId,
+          input: argsStr.slice(0, 1e3)
+        },
+        parentId
+      );
+      const trace = this.traces.get(traceId);
+      trace?.spans.push(span);
+      this.activeSpans.set(`${data.runId}:tool:${data.toolName}:${span.spanId}`, span);
+    });
+    on("tool.result", (data) => {
+      const prefix = `${data.runId}:tool:${data.toolName}:`;
+      let matchKey;
+      for (const key of this.activeSpans.keys()) {
+        if (key.startsWith(prefix)) {
+          matchKey = key;
+          break;
+        }
+      }
+      if (!matchKey) return;
+      const span = this.activeSpans.get(matchKey);
+      const resultStr = typeof data.result === "string" ? data.result : JSON.stringify(data.result ?? "");
+      span.attributes.output = resultStr.slice(0, 2e3);
+      span.attributes.resultLength = resultStr.length;
+      span.attributes.cached = resultStr.startsWith("[cached]");
+      this.endSpan(span, "ok");
+      this.activeSpans.delete(matchKey);
+    });
+    on("handoff.transfer", (data) => {
+      const traceId = this.runToTrace.get(data.runId);
+      const parentId = this.runToRootSpan.get(data.runId);
+      if (!traceId) return;
+      const span = this.startSpan(
+        traceId,
+        `handoff.${data.fromAgent}->${data.toAgent}`,
+        "handoff",
+        {
+          fromAgent: data.fromAgent,
+          toAgent: data.toAgent,
+          reason: data.reason
+        },
+        parentId
+      );
+      this.endSpan(span, "ok");
+      const trace = this.traces.get(traceId);
+      trace?.spans.push(span);
+    });
+    on("handoff.complete", (data) => {
+      const span = this.activeSpans.get(`${data.runId}:root`);
+      if (span) {
+        span.attributes.handoffChain = data.chain;
+        span.attributes.finalAgent = data.finalAgent;
+      }
+    });
+    on("team.delegate", (data) => {
+      const traceId = this.runToTrace.get(data.runId);
+      const parentId = this.runToRootSpan.get(data.runId);
+      if (!traceId) return;
+      const span = this.startSpan(
+        traceId,
+        `team.delegate.${data.memberId}`,
+        "team",
+        {
+          memberId: data.memberId,
+          task: data.task.slice(0, 200)
+        },
+        parentId
+      );
+      this.endSpan(span, "ok");
+      const trace = this.traces.get(traceId);
+      trace?.spans.push(span);
+    });
+    on("cache.hit", (data) => {
+      for (const [key, span] of this.activeSpans) {
+        if (key.endsWith(":root") && span.attributes.agentName === data.agentName) {
+          span.events.push({ name: "cache.hit", timestamp: Date.now(), attributes: { cachedId: data.cachedId } });
+          break;
+        }
+      }
+    });
+    on("cache.miss", (data) => {
+      for (const [key, span] of this.activeSpans) {
+        if (key.endsWith(":root") && span.attributes.agentName === data.agentName) {
+          span.events.push({ name: "cache.miss", timestamp: Date.now(), attributes: {} });
+          break;
+        }
+      }
+    });
+    on("cost.tracked", (data) => {
+      const span = this.activeSpans.get(`${data.runId}:root`);
+      if (span) {
+        span.attributes.modelId = data.modelId;
+      }
+    });
+    on("memory.extract", (data) => {
+      for (const [key, span] of this.activeSpans) {
+        if (key.endsWith(":root") && span.attributes.agentName === data.agentName) {
+          span.events.push({
+            name: "memory.extract",
+            timestamp: Date.now(),
+            attributes: { sessionId: data.sessionId, agentName: data.agentName }
+          });
+          break;
+        }
+      }
+    });
+  }
+  detach(eventBus) {
+    for (const { event, handler } of this.listeners) {
+      eventBus.off(event, handler);
+    }
+    this.listeners = [];
+  }
+  getTrace(traceId) {
+    return this.traces.get(traceId);
+  }
+  getTraceByRunId(runId) {
+    const traceId = this.runToTrace.get(runId);
+    return traceId ? this.traces.get(traceId) : void 0;
+  }
+  getAllTraces() {
+    return [...this.traces.values()];
+  }
+  clear() {
+    this.traces.clear();
+    this.runToTrace.clear();
+    this.runToRootSpan.clear();
+    this.activeSpans.clear();
+  }
+  async flush() {
+    await Promise.allSettled(this.pendingExports);
+    this.pendingExports = [];
+    for (const exporter of this.exporters) {
+      if (exporter.flush) await exporter.flush();
+    }
+  }
+  async shutdown() {
+    await this.flush();
+    for (const exporter of this.exporters) {
+      if (exporter.shutdown) await exporter.shutdown();
+    }
+  }
+  startSpan(traceId, name, kind, attributes, parentSpanId) {
+    return {
+      traceId,
+      spanId: genId(),
+      parentSpanId,
+      name,
+      kind,
+      startTime: Date.now(),
+      status: "running",
+      attributes,
+      events: []
+    };
+  }
+  endSpan(span, status) {
+    span.endTime = Date.now();
+    span.durationMs = span.endTime - span.startTime;
+    span.status = status;
+  }
+  finalizeTrace(runId) {
+    const traceId = this.runToTrace.get(runId);
+    if (!traceId) return;
+    const trace = this.traces.get(traceId);
+    if (!trace) return;
+    const root = trace.spans.find((s) => s.spanId === trace.rootSpanId);
+    if (root) {
+      trace.endTime = root.endTime;
+      trace.durationMs = root.durationMs;
+    }
+    const exportPromise = this.runExporters(trace);
+    this.pendingExports.push(exportPromise);
+    exportPromise.finally(() => {
+      const idx = this.pendingExports.indexOf(exportPromise);
+      if (idx >= 0) this.pendingExports.splice(idx, 1);
+    });
+    this.runToTrace.delete(runId);
+    this.runToRootSpan.delete(runId);
+    if (this.traces.size > this.maxTraces) {
+      const oldest = this.traces.keys().next().value;
+      if (oldest) this.traces.delete(oldest);
+    }
+  }
+  async runExporters(trace) {
+    for (const exporter of this.exporters) {
+      try {
+        await exporter.export(trace);
+      } catch (err) {
+        console.warn(
+          `[agentium/observability] Export failed (${exporter.name}):`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+  }
+};
+
+// src/instrument.ts
+function resolveExporters(raw) {
+  if (!raw || raw.length === 0) return [];
+  return raw.map((e) => {
+    if (typeof e !== "string") return e;
+    const shorthand = {
+      console: () => new ConsoleExporter(),
+      langfuse: () => new LangfuseExporter(),
+      "json-file": () => new JsonFileExporter(),
+      otel: () => new OTelExporter()
+    };
+    const factory = shorthand[e];
+    if (!factory) throw new Error(`Unknown exporter: "${e}". Use "console", "langfuse", "json-file", or "otel".`);
+    return factory();
+  });
+}
+function buildResult(eventBus, config) {
+  const exporters = resolveExporters(config?.exporters);
+  const tracer = new Tracer(exporters);
+  tracer.attach(eventBus);
+  let metrics = null;
+  if (config?.metrics !== false) {
+    metrics = new MetricsCollector();
+    metrics.attach(eventBus);
+  }
+  let logger = null;
+  if (config?.structuredLogs) {
+    const drain = config.structuredLogs === true ? "json" : config.structuredLogs;
+    logger = new StructuredLogger(drain, tracer);
+    logger.attach(eventBus);
+  }
+  const detach = () => {
+    tracer.detach(eventBus);
+    metrics?.detach(eventBus);
+    logger?.detach(eventBus);
+  };
+  return { tracer, metrics, logger, detach };
+}
+function instrument(agent, config) {
+  return buildResult(agent.eventBus, config);
+}
+function instrumentBus(eventBus, config) {
+  return buildResult(eventBus, config);
+}
+
+// src/metrics-exporter.ts
+var MetricsExporter = class {
+  runs = [];
+  toolUsage = {};
+  runStartTimes = /* @__PURE__ */ new Map();
+  runToolCounts = /* @__PURE__ */ new Map();
+  listeners = [];
+  subscribers = /* @__PURE__ */ new Set();
+  maxRecords = 5e4;
+  sessionCategories = {};
+  estimatedKvCacheGb;
+  attach(eventBus) {
+    const on = (event, handler) => {
+      eventBus.on(event, handler);
+      this.listeners.push({ event, handler });
+    };
+    on("run.start", (data) => {
+      this.runStartTimes.set(data.runId, { agentName: data.agentName, start: Date.now() });
+      this.runToolCounts.set(data.runId, 0);
+      this.emit({ type: "run.start", agentName: data.agentName, timestamp: Date.now(), data: { runId: data.runId } });
+    });
+    on("run.complete", (data) => {
+      const info = this.runStartTimes.get(data.runId);
+      if (!info) return;
+      const duration = Date.now() - info.start;
+      const usage = data.output?.usage;
+      const tokens = usage?.totalTokens ?? 0;
+      this.addRecord({
+        agentName: info.agentName,
+        durationMs: duration,
+        tokens,
+        promptTokens: usage?.promptTokens ?? 0,
+        completionTokens: usage?.completionTokens ?? 0,
+        reasoningTokens: usage?.reasoningTokens ?? 0,
+        cachedTokens: usage?.cachedTokens ?? 0,
+        audioInputTokens: usage?.audioInputTokens ?? 0,
+        audioOutputTokens: usage?.audioOutputTokens ?? 0,
+        providerMetrics: usage?.providerMetrics,
+        cost: 0,
+        toolCalls: this.runToolCounts.get(data.runId) ?? 0,
+        success: true,
+        timestamp: Date.now()
+      });
+      this.runStartTimes.delete(data.runId);
+      this.runToolCounts.delete(data.runId);
+      this.emit({
+        type: "run.complete",
+        agentName: info.agentName,
+        timestamp: Date.now(),
+        data: { durationMs: duration, tokens }
+      });
+    });
+    on("run.error", (data) => {
+      const info = this.runStartTimes.get(data.runId);
+      if (!info) return;
+      const duration = Date.now() - info.start;
+      this.addRecord({
+        agentName: info.agentName,
+        durationMs: duration,
+        tokens: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        reasoningTokens: 0,
+        cachedTokens: 0,
+        audioInputTokens: 0,
+        audioOutputTokens: 0,
+        cost: 0,
+        toolCalls: this.runToolCounts.get(data.runId) ?? 0,
+        success: false,
+        timestamp: Date.now()
+      });
+      this.runStartTimes.delete(data.runId);
+      this.runToolCounts.delete(data.runId);
+      this.emit({
+        type: "run.error",
+        agentName: info.agentName,
+        timestamp: Date.now(),
+        data: { durationMs: duration }
+      });
+    });
+    on("tool.call", (data) => {
+      const info = this.runStartTimes.get(data.runId);
+      const agentName = info?.agentName ?? "unknown";
+      this.runToolCounts.set(data.runId, (this.runToolCounts.get(data.runId) ?? 0) + 1);
+      if (!this.toolUsage[agentName]) this.toolUsage[agentName] = {};
+      this.toolUsage[agentName][data.toolName] = (this.toolUsage[agentName][data.toolName] ?? 0) + 1;
+    });
+    on("cost.tracked", (data) => {
+      for (let i = this.runs.length - 1; i >= 0; i--) {
+        if (this.runs[i].agentName === data.agentName) {
+          if (data.usage?.cost) this.runs[i].cost = data.usage.cost;
+          break;
+        }
+      }
+    });
+    on("capacity.session.classified", (data) => {
+      this.sessionCategories[data.category] = (this.sessionCategories[data.category] ?? 0) + 1;
+    });
+    on("capacity.warning", (data) => {
+      if (data.estimatedKvGb !== void 0) {
+        this.estimatedKvCacheGb = data.estimatedKvGb;
+      }
+    });
+  }
+  detach(eventBus) {
+    for (const { event, handler } of this.listeners) {
+      eventBus.off(event, handler);
+    }
+    this.listeners = [];
+  }
+  addRecord(record) {
+    this.runs.push(record);
+    if (this.runs.length > this.maxRecords) {
+      this.runs = this.runs.slice(-this.maxRecords);
+    }
+  }
+  emit(event) {
+    for (const sub of this.subscribers) {
+      try {
+        sub(event);
+      } catch {
+      }
+    }
+  }
+  getMetrics(agentName) {
+    const filtered = agentName ? this.runs.filter((r) => r.agentName === agentName) : this.runs;
+    const successful = filtered.filter((r) => r.success);
+    const durations = filtered.map((r) => r.durationMs).sort((a, b) => a - b);
+    const totalRuns = filtered.length;
+    const errors = filtered.filter((r) => !r.success).length;
+    const totalTokens = filtered.reduce((s, r) => s + r.tokens, 0);
+    const promptTokens = filtered.reduce((s, r) => s + r.promptTokens, 0);
+    const completionTokens = filtered.reduce((s, r) => s + r.completionTokens, 0);
+    const reasoningTokens = filtered.reduce((s, r) => s + r.reasoningTokens, 0);
+    const cachedTokens = filtered.reduce((s, r) => s + r.cachedTokens, 0);
+    const audioInputTokens = filtered.reduce((s, r) => s + r.audioInputTokens, 0);
+    const audioOutputTokens = filtered.reduce((s, r) => s + r.audioOutputTokens, 0);
+    const totalCost = filtered.reduce((s, r) => s + r.cost, 0);
+    const totalToolCalls = filtered.reduce((s, r) => s + r.toolCalls, 0);
+    const avgDuration = durations.length > 0 ? durations.reduce((s, d) => s + d, 0) / durations.length : 0;
+    const p95Idx = Math.floor(durations.length * 0.95);
+    const p95 = durations.length > 0 ? durations[Math.min(p95Idx, durations.length - 1)] : 0;
+    const toolFreq = {};
+    if (agentName && this.toolUsage[agentName]) {
+      Object.assign(toolFreq, this.toolUsage[agentName]);
+    } else {
+      for (const usage of Object.values(this.toolUsage)) {
+        for (const [tool, count] of Object.entries(usage)) {
+          toolFreq[tool] = (toolFreq[tool] ?? 0) + count;
+        }
+      }
+    }
+    const avgContextLength = successful.length > 0 ? Math.round(promptTokens / successful.length) : 0;
+    return {
+      runs: totalRuns,
+      errors,
+      avgDurationMs: Math.round(avgDuration),
+      p95DurationMs: Math.round(p95),
+      totalCost,
+      totalTokens,
+      promptTokens,
+      completionTokens,
+      reasoningTokens,
+      cachedTokens,
+      audioInputTokens,
+      audioOutputTokens,
+      toolCallCount: totalToolCalls,
+      toolUsageFrequency: toolFreq,
+      errorRate: totalRuns > 0 ? errors / totalRuns : 0,
+      tokensPerRun: successful.length > 0 ? Math.round(totalTokens / successful.length) : 0,
+      avgContextLength,
+      sessionCategories: this.sessionCategories,
+      estimatedKvCacheGb: this.estimatedKvCacheGb
+    };
+  }
+  toPrometheus() {
+    const lines = [];
+    const allAgents = new Set(this.runs.map((r) => r.agentName));
+    lines.push("# HELP agentium_agent_runs_total Total agent runs");
+    lines.push("# TYPE agentium_agent_runs_total counter");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_runs_total{agent="${agent}"} ${m.runs}`);
+    }
+    lines.push("# HELP agentium_agent_errors_total Total agent errors");
+    lines.push("# TYPE agentium_agent_errors_total counter");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_errors_total{agent="${agent}"} ${m.errors}`);
+    }
+    lines.push("# HELP agentium_agent_duration_ms_avg Average run duration in ms");
+    lines.push("# TYPE agentium_agent_duration_ms_avg gauge");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_duration_ms_avg{agent="${agent}"} ${m.avgDurationMs}`);
+    }
+    lines.push("# HELP agentium_agent_duration_ms_p95 P95 run duration in ms");
+    lines.push("# TYPE agentium_agent_duration_ms_p95 gauge");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_duration_ms_p95{agent="${agent}"} ${m.p95DurationMs}`);
+    }
+    lines.push("# HELP agentium_agent_tokens_total Total tokens consumed");
+    lines.push("# TYPE agentium_agent_tokens_total counter");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_tokens_total{agent="${agent}"} ${m.totalTokens}`);
+    }
+    lines.push("# HELP agentium_agent_cost_usd_total Total cost in USD");
+    lines.push("# TYPE agentium_agent_cost_usd_total counter");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_cost_usd_total{agent="${agent}"} ${m.totalCost}`);
+    }
+    lines.push("# HELP agentium_agent_tool_calls_total Total tool calls");
+    lines.push("# TYPE agentium_agent_tool_calls_total counter");
+    for (const agent of allAgents) {
+      const m = this.getMetrics(agent);
+      lines.push(`agentium_agent_tool_calls_total{agent="${agent}"} ${m.toolCallCount}`);
+    }
+    if (this.estimatedKvCacheGb !== void 0) {
+      lines.push("# HELP agentium_kv_cache_estimated_gb Estimated KV cache size in GB");
+      lines.push("# TYPE agentium_kv_cache_estimated_gb gauge");
+      lines.push(`agentium_kv_cache_estimated_gb ${this.estimatedKvCacheGb}`);
+    }
+    const categories = Object.entries(this.sessionCategories);
+    if (categories.length > 0) {
+      lines.push("# HELP agentium_session_category_total Sessions by category");
+      lines.push("# TYPE agentium_session_category_total counter");
+      for (const [category, count] of categories) {
+        lines.push(`agentium_session_category_total{category="${category}"} ${count}`);
+      }
+      const totalSessions = categories.reduce((s, [, c2]) => s + c2, 0);
+      lines.push("# HELP agentium_capacity_sessions_total Total tracked sessions");
+      lines.push("# TYPE agentium_capacity_sessions_total counter");
+      lines.push(`agentium_capacity_sessions_total ${totalSessions}`);
+    }
+    return `${lines.join("\n")}
+`;
+  }
+  toJSON() {
+    const allAgents = new Set(this.runs.map((r) => r.agentName));
+    const byAgent = {};
+    for (const agent of allAgents) {
+      byAgent[agent] = this.getMetrics(agent);
+    }
+    return {
+      global: this.getMetrics(),
+      byAgent,
+      timestamp: Date.now()
+    };
+  }
+  async *stream() {
+    const queue = [];
+    let resolve = null;
+    const handler = (event) => {
+      queue.push(event);
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    };
+    this.subscribers.add(handler);
+    try {
+      while (true) {
+        while (queue.length > 0) {
+          yield queue.shift();
+        }
+        await new Promise((r) => {
+          resolve = r;
+        });
+      }
+    } finally {
+      this.subscribers.delete(handler);
+    }
+  }
+  reset() {
+    this.runs = [];
+    this.toolUsage = {};
+    this.runStartTimes.clear();
+    this.runToolCounts.clear();
+  }
+};
+export {
+  CallbackExporter,
+  ConsoleExporter,
+  JsonFileExporter,
+  LangfuseExporter,
+  MetricsCollector,
+  MetricsExporter,
+  OTelExporter,
+  StructuredLogger,
+  Tracer,
+  instrument,
+  instrumentBus
+};