@radaros/observability 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @radaros/observability
+
+Opt-in tracing, metrics, and structured logging for RadarOS agents.
+
+## Install
+
+```bash
+npm install @radaros/observability
+```
+
+## Quick Start
+
+```typescript
+import { Agent, openai } from "@radaros/core";
+import { instrument } from "@radaros/observability";
+
+const agent = new Agent({ name: "assistant", model: openai("gpt-4o") });
+
+const obs = instrument(agent, {
+  exporters: ["console"],       // or "langfuse", "otel", "json-file"
+});
+
+await agent.run("Hello!");
+await obs.tracer.flush();
+```
+
+## Exporters
+
+| Shorthand | Env Vars | Description |
+|-----------|----------|-------------|
+| `"console"` | — | Pretty-print trace tree |
+| `"langfuse"` | `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` | Langfuse cloud |
+| `"otel"` | `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector |
+| `"json-file"` | — | Local JSON file |
+
+## Documentation
+
+Full docs at [radaros.mintlify.dev](https://radaros.mintlify.dev)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,223 @@
+import { EventBus, Agent } from '@radaros/core';
+
+type SpanKind = "agent" | "llm" | "tool" | "guardrail" | "memory" | "cache" | "handoff" | "team" | "workflow" | "internal";
+type SpanStatus = "ok" | "error" | "running";
+interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, unknown>;
+}
+interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+}
+interface Trace {
+    traceId: string;
+    spans: Span[];
+    rootSpanId: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    metadata: Record<string, unknown>;
+}
+interface TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    flush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+interface MetricsSnapshot {
+    counters: {
+        runs_total: number;
+        runs_success: number;
+        runs_error: number;
+        tool_calls_total: number;
+        handoffs_total: number;
+        cache_hits: number;
+        cache_misses: number;
+    };
+    histograms: {
+        run_duration_ms: number[];
+        tool_latency_ms: number[];
+    };
+    gauges: {
+        total_cost_usd: number;
+        total_tokens: number;
+    };
+    rates: {
+        cache_hit_ratio: number;
+        error_rate: number;
+    };
+    timestamp: number;
+}
+type ExporterShorthand = "console" | "langfuse" | "json-file" | "otel";
+interface ObservabilityConfig {
+    /** Exporter instances or shorthand strings like "console", "langfuse". */
+    exporters?: (TraceExporter | ExporterShorthand)[];
+    metrics?: boolean;
+    structuredLogs?: boolean | LogDrain;
+}
+type LogDrain = "console" | "json" | ((entry: LogEntry) => void);
+interface LogEntry {
+    timestamp: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    traceId?: string;
+    spanId?: string;
+    agentName?: string;
+    attributes?: Record<string, unknown>;
+}
+
+declare class CallbackExporter implements TraceExporter {
+    name: string;
+    private callback;
+    constructor(callback: (trace: Trace) => void | Promise<void>);
+    export(trace: Trace): Promise<void>;
+}
+
+declare class ConsoleExporter implements TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    private printSpan;
+}
+
+interface JsonFileExporterConfig {
+    path?: string;
+    mode?: "overwrite" | "append";
+    pretty?: boolean;
+}
+declare class JsonFileExporter implements TraceExporter {
+    name: string;
+    private path;
+    private mode;
+    private pretty;
+    constructor(config?: JsonFileExporterConfig);
+    export(trace: Trace): Promise<void>;
+}
+
+interface LangfuseExporterConfig {
+    /** Defaults to LANGFUSE_PUBLIC_KEY env var. */
+    publicKey?: string;
+    /** Defaults to LANGFUSE_SECRET_KEY env var. */
+    secretKey?: string;
+    /** Defaults to LANGFUSE_BASE_URL env var or https://cloud.langfuse.com. */
+    baseUrl?: string;
+}
+declare class LangfuseExporter implements TraceExporter {
+    name: string;
+    private publicKey;
+    private secretKey;
+    private baseUrl;
+    constructor(config?: LangfuseExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+}
+
+interface OTelExporterConfig {
+    /** Defaults to OTEL_EXPORTER_OTLP_ENDPOINT env var. */
+    endpoint?: string;
+    /** Defaults to OTEL_EXPORTER_OTLP_HEADERS env var (comma-separated key=value pairs). */
+    headers?: Record<string, string>;
+    protocol?: "http/json" | "http/protobuf";
+    /** Defaults to OTEL_SERVICE_NAME env var or "radaros". */
+    serviceName?: string;
+}
+declare class OTelExporter implements TraceExporter {
+    name: string;
+    private endpoint;
+    private headers;
+    private serviceName;
+    constructor(config?: OTelExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+    private padHex;
+    private mapKind;
+    private toOtlpValue;
+}
+
+declare class MetricsCollector {
+    private counters;
+    private histograms;
+    private gauges;
+    private readonly MAX_HISTOGRAM_SIZE;
+    private toolStartTimes;
+    private runStartTimes;
+    private listeners;
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getMetrics(): MetricsSnapshot;
+    reset(): void;
+}
+
+declare class Tracer {
+    private traces;
+    private runToTrace;
+    private runToRootSpan;
+    private activeSpans;
+    private exporters;
+    private listeners;
+    private pendingExports;
+    private maxTraces;
+    constructor(exporters?: TraceExporter[]);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getTrace(traceId: string): Trace | undefined;
+    getTraceByRunId(runId: string): Trace | undefined;
+    getAllTraces(): Trace[];
+    clear(): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private startSpan;
+    private endSpan;
+    private addEventToLatestSpan;
+    private finalizeTrace;
+    private runExporters;
+}
+
+declare class StructuredLogger {
+    private drain;
+    private tracer;
+    private listeners;
+    constructor(drain?: LogDrain, tracer?: Tracer);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    private log;
+}
+
+interface InstrumentResult {
+    tracer: Tracer;
+    metrics: MetricsCollector | null;
+    logger: StructuredLogger | null;
+    detach: () => void;
+}
+/**
+ * Attach observability to an agent in one call.
+ *
+ * ```ts
+ * import { instrument } from "@radaros/observability";
+ *
+ * // Minimal — just pass string shorthands:
+ * const obs = instrument(agent, { exporters: ["langfuse", "console"] });
+ *
+ * // Or bring your own exporter instances for custom config:
+ * const obs = instrument(agent, {
+ *   exporters: [new LangfuseExporter({ baseUrl: "..." }), "console"],
+ * });
+ * ```
+ */
+declare function instrument(agent: Agent, config?: ObservabilityConfig): InstrumentResult;
+/**
+ * Attach observability to a raw EventBus (for teams, workflows, or custom setups).
+ */
+declare function instrumentBus(eventBus: EventBus, config?: ObservabilityConfig): InstrumentResult;
+
+export { CallbackExporter, ConsoleExporter, type ExporterShorthand, type InstrumentResult, JsonFileExporter, type JsonFileExporterConfig, LangfuseExporter, type LangfuseExporterConfig, type LogDrain, type LogEntry, MetricsCollector, type MetricsSnapshot, OTelExporter, type OTelExporterConfig, type ObservabilityConfig, type Span, type SpanEvent, type SpanKind, type SpanStatus, StructuredLogger, type Trace, type TraceExporter, Tracer, instrument, instrumentBus };

package/dist/index.js

@@ -0,0 +1,1017 @@
+// 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 + "\n");
+      } else {
+        await writeFile(this.path, json);
+      }
+    } catch (err) {
+      console.warn(
+        `[radaros/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
+          }
+        });
+      } 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 ?? "radaros";
+  }
+  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: "@radaros/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
+  };
+  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?.totalTokens) {
+        this.gauges.total_tokens += data.output.usage.totalTokens;
+      }
+      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) => {
+      if (data.usage?.totalTokens) {
+        this.gauges.total_tokens += data.usage.totalTokens;
+      }
+      if (data.usage?.cost) {
+        this.gauges.total_cost_usd += data.usage.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
+    };
+    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,
+          durationMs: data.output?.durationMs
+        },
+        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
+        },
+        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;
+        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;
+  }
+  addEventToLatestSpan(runId, name, attributes) {
+    const span = this.activeSpans.get(`${runId}:root`);
+    if (span) {
+      span.events.push({ name, timestamp: Date.now(), attributes });
+    }
+  }
+  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(
+          `[radaros/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);
+}
+export {
+  CallbackExporter,
+  ConsoleExporter,
+  JsonFileExporter,
+  LangfuseExporter,
+  MetricsCollector,
+  OTelExporter,
+  StructuredLogger,
+  Tracer,
+  instrument,
+  instrumentBus
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@radaros/observability",
+  "version": "0.1.0",
+  "description": "Tracing, metrics, and structured logging for RadarOS agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xhipment/agentOs.git",
+    "directory": "packages/observability"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "observability",
+    "tracing",
+    "metrics",
+    "langfuse",
+    "opentelemetry"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@radaros/core": "^0.3.10"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  }
+}