@neutrome/open-ai-router 0.5.3 → 0.5.5

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
+    "@posthog/ai": "^8.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "hono": "^4.12.18",
+    "posthog-node": "^5.41.0",
+    "zod": "^4.2.1",
     "@neutrome/lil-engine": "0.3.1",
     "@neutrome/lilsdk-ts": "0.3.1"
   },

package/src/app/factory.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import type { ExecutionSummary } from "../telemetry.ts";
+import type { ExecutionSummary } from "../telemetry/index.ts";
 import type { RouterConfig } from "../router/index.ts";
 import { createRouterApp } from "./factory.ts";
 

package/src/app/factory.ts

@@ -7,7 +7,7 @@ import {
 } from "@neutrome/lil-engine";
 import { cors } from "./cors.ts";
 import { healthHandler } from "./health.ts";
-import { createRouterTelemetry } from "../telemetry.ts";
+import { createRouterTelemetry } from "../telemetry/index.ts";
 import { canAccessPrincipalModel } from "../admission/access.ts";
 import {
   createRouterRuntime,
@@ -91,7 +91,12 @@ export function createRouterApp(options: RouterAppOptions) {
   ): Promise<Response> {
     const env = honoEnv(c);
     const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
-    const telemetry = createRouterTelemetry(env);
+    const telemetry = createRouterTelemetry({
+      env,
+      ...(options.telemetryDistinctId
+        ? { distinctId: options.telemetryDistinctId }
+        : {}),
+    });
     const onExecutionSummary = options.hooks?.onExecutionSummary;
     const observe = (
       event: Parameters<NonNullable<ExecutionRuntimeOptions["observe"]>>[0],

package/src/app/types.ts

@@ -3,7 +3,7 @@ import type {
   AuthPrincipal,
   RuntimeAuthenticator,
 } from "../admission/types.ts";
-import type { ExecutionSummary } from "../telemetry.ts";
+import type { ExecutionSummary } from "../telemetry/index.ts";
 import type { RouterConfig } from "../router/config.ts";
 import type { ExecutionRuntimeOptions } from "../router/execution-types.ts";
 import type { RemoteMcpClientFactory } from "../router/mcp.ts";
@@ -34,5 +34,6 @@ export type RouterAppOptions = {
   requestIdFactory?: ExecutionRuntimeOptions["requestIdFactory"];
   executionIdFactory?: ExecutionRuntimeOptions["executionIdFactory"];
   upstreamTimeoutMs?: number;
+  telemetryDistinctId?: string;
   remoteMcpClientFactory?: RemoteMcpClientFactory;
 };

package/src/index.ts

@@ -4,12 +4,18 @@ export type {
   RouterAppHooks,
   RouterAppOptions,
 } from "./app/types.ts";
-export { createRouterTelemetry } from "./telemetry.ts";
+export {
+  createRouterTelemetry,
+  PosthogErrorTelemetry,
+  PosthogTraceTelemetry,
+} from "./telemetry/index.ts";
 export type {
+  ErrorTelemetryDriver,
   ExecutionSummary,
   ExecutionSummarySpan,
   RouterTelemetry,
-} from "./telemetry.ts";
+  TraceTelemetryDriver,
+} from "./telemetry/index.ts";
 
 export {
   createFetchProviderInvoker,

package/src/router/provider-invoker.ts

@@ -112,6 +112,8 @@ export function createFetchProviderInvoker(
           provider.name,
           reqBytes,
           bytes.byteLength,
+          jsonBody(reqBody),
+          jsonBody(bytes),
         );
         return response;
       } catch (error) {
@@ -132,3 +134,11 @@ export function createFetchProviderInvoker(
     },
   };
 }
+
+function jsonBody(body: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return undefined;
+  }
+}

package/src/router/provider-stream.ts

@@ -102,6 +102,7 @@ export async function* streamProvider(
     let firstByteObserved = false;
     const streamReadStartedMs = Date.now();
     let lastChunkWithUsage: Program | null = null;
+    const responseChunks: unknown[] = [];
     let respBytes = 0;
     while (true) {
       const { done, value } = await reader.read();
@@ -140,10 +141,13 @@ export async function* streamProvider(
               provider.name,
               reqBytes,
               respBytes,
+              jsonBody(reqBody),
+              responseChunks,
             );
             return;
           }
           if (data[0] !== "{") continue;
+          responseChunks.push(jsonBody(encoder.encode(data)));
           const chunk = parseProviderStreamChunk(
             provider.style,
             encoder.encode(data),
@@ -163,10 +167,13 @@ export async function* streamProvider(
             provider.name,
             reqBytes,
             respBytes,
+            jsonBody(reqBody),
+            responseChunks,
           );
           return;
         }
         if (data[0] !== "{") continue;
+        responseChunks.push(jsonBody(encoder.encode(data)));
         const chunk = parseProviderStreamChunk(
           provider.style,
           encoder.encode(data),
@@ -181,6 +188,8 @@ export async function* streamProvider(
       provider.name,
       reqBytes,
       respBytes,
+      jsonBody(reqBody),
+      responseChunks,
     );
   } catch (error) {
     throw normalizeUpstreamAbort(error, timed.signal);
@@ -190,3 +199,11 @@ export async function* streamProvider(
     timed.cleanup();
   }
 }
+
+function jsonBody(body: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return undefined;
+  }
+}

package/src/router/provider-telemetry.ts

@@ -1,9 +1,11 @@
 import { usageObject, type Program } from "@neutrome/lil-engine";
 import { createExecutionEvent } from "@neutrome/lilsdk-ts";
+import { z } from "zod";
 import type { ProviderInvocationContext } from "./execution-types.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
+const TokenCountSchema = z.number().finite().nonnegative();
 
 export function emitProviderUsage(
   providerCtx: ProviderInvocationContext,
@@ -11,6 +13,8 @@ export function emitProviderUsage(
   provider: string,
   requestBytes: number,
   responseBytes: number,
+  input?: unknown,
+  output?: unknown,
 ): void {
   const usage = response ? usageObject(response) : undefined;
   const u = (usage && typeof usage === "object" ? usage : {}) as Record<
@@ -39,13 +43,15 @@ export function emitProviderUsage(
         cachedTokensInput,
         requestBytes,
         responseBytes,
+        ...(input === undefined ? {} : { input }),
+        ...(output === undefined ? {} : { output }),
       },
     }),
   );
 }
 
 function asNum(v: unknown): number {
-  return typeof v === "number" && v >= 0 ? v : 0;
+  return TokenCountSchema.safeParse(v).data ?? 0;
 }
 
 export function injectStreamUsage(body: Uint8Array): Uint8Array {

package/src/telemetry/index.ts

@@ -0,0 +1,13 @@
+export { createRouterTelemetry } from "./router.ts";
+export { PosthogErrorTelemetry, PosthogTraceTelemetry } from "./posthog.ts";
+export type {
+  ErrorTelemetryDriver,
+  TelemetryError,
+  TraceGeneration,
+  TraceTelemetryDriver,
+} from "./types.ts";
+export type {
+  ExecutionSummary,
+  ExecutionSummarySpan,
+  RouterTelemetry,
+} from "./router.ts";

package/src/telemetry/posthog.ts

@@ -0,0 +1,108 @@
+import { captureAiGeneration } from "@posthog/ai";
+import { PostHog } from "posthog-node/edge";
+import { z } from "zod";
+import type {
+  ErrorTelemetryDriver,
+  TelemetryError,
+  TraceGeneration,
+  TraceTelemetryDriver,
+} from "./types.ts";
+
+type PosthogClient = Pick<
+  PostHog,
+  "capture" | "captureImmediate" | "captureExceptionImmediate"
+>;
+
+const PosthogConfigSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  host: z.url().optional(),
+  distinctId: z.string().min(1).optional(),
+});
+
+export class PosthogTraceTelemetry implements TraceTelemetryDriver {
+  constructor(
+    private readonly client: PostHog,
+    private readonly distinctId: string,
+  ) {}
+
+  async recordGeneration(generation: TraceGeneration): Promise<void> {
+    await captureAiGeneration(this.client as never, {
+      distinctId: this.distinctId,
+      traceId: generation.traceId,
+      provider: generation.provider,
+      ...(generation.model ? { model: generation.model } : {}),
+      input: generation.input ?? null,
+      output: generation.output ?? null,
+      latency: elapsedSeconds(generation.startedAt, generation.finishedAt),
+      ...(generation.timeToFirstTokenMs === undefined
+        ? {}
+        : { timeToFirstToken: generation.timeToFirstTokenMs / 1_000 }),
+      usage: {
+        inputTokens: generation.tokensInput,
+        outputTokens: generation.tokensOutput,
+      },
+      properties: compact({
+        "lil.request_id": generation.requestId,
+        "lil.execution_id": generation.executionId,
+        "lil.parent_execution_id": generation.parentExecutionId,
+        "lil.cached_input_tokens": generation.cachedTokensInput || undefined,
+        "lil.request_bytes": generation.requestBytes || undefined,
+        "lil.response_bytes": generation.responseBytes || undefined,
+      }),
+      captureImmediate: true,
+    });
+  }
+}
+
+export class PosthogErrorTelemetry implements ErrorTelemetryDriver {
+  constructor(
+    private readonly client: PosthogClient,
+    private readonly distinctId: string,
+  ) {}
+
+  async recordError(error: TelemetryError): Promise<void> {
+    await this.client.captureExceptionImmediate(
+      new Error(error.message),
+      this.distinctId,
+      {
+        "lil.trace_id": error.traceId,
+        "lil.request_id": error.requestId,
+        "lil.execution_id": error.executionId,
+      },
+    );
+  }
+}
+
+export function createPosthogTelemetryDrivers(input: {
+  apiKey?: unknown;
+  host?: unknown;
+  distinctId?: string;
+}): {
+  traceDriver?: TraceTelemetryDriver;
+  errorDriver?: ErrorTelemetryDriver;
+} {
+  const config = PosthogConfigSchema.safeParse(input);
+  if (!config.success || !config.data.apiKey) return {};
+  const { apiKey, host, distinctId } = config.data;
+
+  const client = new PostHog(apiKey, {
+    host: host ?? "https://us.i.posthog.com",
+    flushAt: 1,
+    flushInterval: 0,
+  });
+  const resolvedDistinctId = distinctId ?? "anonymous";
+  return {
+    traceDriver: new PosthogTraceTelemetry(client, resolvedDistinctId),
+    errorDriver: new PosthogErrorTelemetry(client, resolvedDistinctId),
+  };
+}
+
+function elapsedSeconds(startedAt: string, finishedAt: string): number {
+  return Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)) / 1_000;
+}
+
+function compact(values: Record<string, string | number | undefined>) {
+  return Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== undefined),
+  );
+}

package/src/telemetry/router.ts

@@ -0,0 +1,291 @@
+import type { ExecutionEvent } from "@neutrome/lilsdk-ts";
+import { z } from "zod";
+import { createPosthogTelemetryDrivers } from "./posthog.ts";
+import type {
+  ErrorTelemetryDriver,
+  TelemetryError,
+  TraceGeneration,
+  TraceTelemetryDriver,
+} from "./types.ts";
+
+export type ExecutionSummary = {
+  spanId: string;
+  startedAt: string;
+  finishedAt: string;
+  spans: ExecutionSummarySpan[];
+  totalTokensInput: number;
+  totalTokensOutput: number;
+  totalCachedTokensInput: number;
+  error?: string;
+};
+
+export type ExecutionSummarySpan = {
+  kind: "request" | "provider" | "tool" | "executor";
+  event: string;
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string;
+  model?: string;
+  provider?: string;
+  toolName?: string;
+  executor?: string;
+  startedAt: string;
+  finishedAt?: string;
+  tokensInput: number;
+  tokensOutput: number;
+  cachedTokensInput: number;
+  requestBytes: number;
+  responseBytes: number;
+  error?: string;
+};
+
+export type RouterTelemetry = {
+  observe(event: ExecutionEvent): void;
+  recordError(input: Omit<TelemetryError, "traceId">): void;
+  flush(): Promise<void>;
+  summary(): ExecutionSummary;
+};
+
+type ActiveSpan = {
+  summary: ExecutionSummarySpan;
+  input?: unknown;
+  output?: unknown;
+  timeToFirstTokenMs?: number;
+};
+
+const EventDataSchema = z
+  .object({
+    startedAt: z.string().min(1).optional(),
+    finishedAt: z.string().min(1).optional(),
+    message: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    provider: z.string().min(1).optional(),
+    toolName: z.string().min(1).optional(),
+    executor: z.string().min(1).optional(),
+    executorId: z.string().min(1).optional(),
+    tokensInput: z.number().finite().nonnegative().optional(),
+    tokensOutput: z.number().finite().nonnegative().optional(),
+    cachedTokensInput: z.number().finite().nonnegative().optional(),
+    requestBytes: z.number().finite().nonnegative().optional(),
+    responseBytes: z.number().finite().nonnegative().optional(),
+  })
+  .passthrough();
+
+export function createRouterTelemetry(input: {
+  env?: Record<string, unknown>;
+  distinctId?: string;
+  traceDriver?: TraceTelemetryDriver;
+  errorDriver?: ErrorTelemetryDriver;
+} = {}): RouterTelemetry {
+  const drivers = createPosthogTelemetryDrivers({
+    apiKey: input.env?.POSTHOG_API_KEY,
+    host: input.env?.POSTHOG_HOST,
+    ...(input.distinctId ? { distinctId: input.distinctId } : {}),
+  });
+  const traceDriver = input.traceDriver ?? drivers.traceDriver;
+  const errorDriver = input.errorDriver ?? drivers.errorDriver;
+  const traceId = crypto.randomUUID().replaceAll("-", "");
+  const startedAt = new Date().toISOString();
+  const spans: ExecutionSummarySpan[] = [];
+  const activeSpans = new Map<string, ActiveSpan>();
+  const providerGenerations: ActiveSpan[] = [];
+  const errors = new Map<string, TelemetryError>();
+  let error: string | undefined;
+
+  return { observe, recordError, flush, summary };
+
+  function observe(event: ExecutionEvent): void {
+    const timing = eventTiming(event);
+    if (isInvocationStarted(event.kind)) {
+      const active = { summary: createSpan(event, timing.startedAt ?? event.timestamp) };
+      spans.push(active.summary);
+      activeSpans.set(event.executionId, active);
+      return;
+    }
+    if (isInvocationFinished(event.kind)) {
+      const active = activeSpans.get(event.executionId);
+      if (active) {
+        active.summary.finishedAt = timing.finishedAt ?? event.timestamp;
+        activeSpans.delete(event.executionId);
+        if (active.summary.kind === "provider") providerGenerations.push(active);
+      }
+      return;
+    }
+    if (event.kind === "provider.usage") {
+      const active = activeSpans.get(event.executionId);
+      if (active) applyUsage(active, event);
+      return;
+    }
+    if (event.kind === "provider.stream_first_byte") {
+      const active = activeSpans.get(event.executionId);
+      if (active) {
+        active.timeToFirstTokenMs = Math.max(
+          0,
+          Date.parse(timing.finishedAt ?? event.timestamp) -
+            Date.parse(active.summary.startedAt),
+        );
+      }
+      const span = createSpan(event, timing.startedAt ?? event.timestamp);
+      span.finishedAt = timing.finishedAt ?? event.timestamp;
+      spans.push(span);
+      return;
+    }
+    if (event.kind === "execution.failed") {
+      const message = eventData(event).message ?? "Execution failed";
+      error ??= message;
+      const active = activeSpans.get(event.executionId);
+      if (active) {
+        active.summary.error = message;
+        active.summary.finishedAt ??= event.timestamp;
+      }
+      recordError({ message, requestId: event.requestId, executionId: event.executionId });
+      return;
+    }
+    if (!timing.startedAt) return;
+    const span = createSpan(event, timing.startedAt);
+    span.finishedAt = timing.finishedAt ?? event.timestamp;
+    spans.push(span);
+  }
+
+  function recordError(input: Omit<TelemetryError, "traceId">): void {
+    error ??= input.message;
+    const telemetryError = { ...input, traceId };
+    errors.set(
+      `${telemetryError.requestId}:${telemetryError.executionId}:${telemetryError.message}`,
+      telemetryError,
+    );
+  }
+
+  async function flush(): Promise<void> {
+    const finishedAt = new Date().toISOString();
+    for (const active of activeSpans.values()) {
+      active.summary.finishedAt ??= finishedAt;
+    }
+    const generations = [
+      ...providerGenerations,
+      ...[...activeSpans.values()].filter(({ summary }) => summary.kind === "provider"),
+    ].map(toGeneration);
+    activeSpans.clear();
+    await reportAll([
+      ...generations.map((generation) => traceDriver?.recordGeneration(generation)),
+      ...[...errors.values()].map((telemetryError) =>
+        errorDriver?.recordError(telemetryError),
+      ),
+    ]);
+  }
+
+  function summary(): ExecutionSummary {
+    const finishedAt = new Date().toISOString();
+    return {
+      spanId: traceId,
+      startedAt,
+      finishedAt,
+      spans,
+      totalTokensInput: spans.reduce((total, span) => total + span.tokensInput, 0),
+      totalTokensOutput: spans.reduce((total, span) => total + span.tokensOutput, 0),
+      totalCachedTokensInput: spans.reduce(
+        (total, span) => total + span.cachedTokensInput,
+        0,
+      ),
+      ...(error ? { error } : {}),
+    };
+  }
+
+  function toGeneration(active: ActiveSpan): TraceGeneration {
+    const { summary } = active;
+    return {
+      traceId,
+      requestId: summary.requestId,
+      executionId: summary.executionId,
+      ...(summary.parentExecutionId
+        ? { parentExecutionId: summary.parentExecutionId }
+        : {}),
+      provider: summary.provider ?? "unknown",
+      ...(summary.model ? { model: summary.model } : {}),
+      startedAt: summary.startedAt,
+      finishedAt: summary.finishedAt ?? new Date().toISOString(),
+      tokensInput: summary.tokensInput,
+      tokensOutput: summary.tokensOutput,
+      cachedTokensInput: summary.cachedTokensInput,
+      requestBytes: summary.requestBytes,
+      responseBytes: summary.responseBytes,
+      ...(active.input === undefined ? {} : { input: active.input }),
+      ...(active.output === undefined ? {} : { output: active.output }),
+      ...(active.timeToFirstTokenMs === undefined
+        ? {}
+        : { timeToFirstTokenMs: active.timeToFirstTokenMs }),
+    };
+  }
+}
+
+function createSpan(event: ExecutionEvent, startedAt: string): ExecutionSummarySpan {
+  return {
+    kind: spanKind(event.kind),
+    event: event.kind,
+    requestId: event.requestId,
+    executionId: event.executionId,
+    ...(event.parentExecutionId ? { parentExecutionId: event.parentExecutionId } : {}),
+    ...eventDetails(event),
+    startedAt,
+    tokensInput: 0,
+    tokensOutput: 0,
+    cachedTokensInput: 0,
+    requestBytes: 0,
+    responseBytes: 0,
+  };
+}
+
+function applyUsage(active: ActiveSpan, event: ExecutionEvent): void {
+  const { summary } = active;
+  const data = eventData(event);
+  summary.tokensInput = data.tokensInput ?? 0;
+  summary.tokensOutput = data.tokensOutput ?? 0;
+  summary.cachedTokensInput = data.cachedTokensInput ?? 0;
+  summary.requestBytes = data.requestBytes ?? 0;
+  summary.responseBytes = data.responseBytes ?? 0;
+  active.input = event.data?.input;
+  active.output = event.data?.output;
+}
+
+function eventTiming(event: ExecutionEvent) {
+  return {
+    startedAt: eventData(event).startedAt,
+    finishedAt: eventData(event).finishedAt,
+  };
+}
+
+function isInvocationStarted(kind: string): boolean {
+  return kind.endsWith(".started") || kind.endsWith(".stream_started");
+}
+function isInvocationFinished(kind: string): boolean {
+  return kind.endsWith(".finished") || kind.endsWith(".stream_finished");
+}
+function spanKind(kind: string): ExecutionSummarySpan["kind"] {
+  if (kind.startsWith("provider.")) return "provider";
+  if (kind.startsWith("tool.")) return "tool";
+  if (kind.startsWith("executor.")) return "executor";
+  return "request";
+}
+function eventDetails(event: ExecutionEvent): Partial<ExecutionSummarySpan> {
+  return {
+    ...optional("model", eventData(event).model),
+    ...optional("provider", eventData(event).provider),
+    ...optional("toolName", eventData(event).toolName),
+    ...optional("executor", eventData(event).executor ?? eventData(event).executorId),
+  };
+}
+async function reportAll(reports: Array<Promise<void> | undefined>): Promise<void> {
+  const results = await Promise.allSettled(reports.filter(Boolean));
+  for (const result of results) {
+    if (result.status === "rejected") {
+      console.error("[telemetry] PostHog capture failed", result.reason);
+    }
+  }
+}
+function eventData(event: ExecutionEvent): z.infer<typeof EventDataSchema> {
+  const parsed = EventDataSchema.safeParse(event.data ?? {});
+  return parsed.success ? parsed.data : {};
+}
+function optional<K extends string>(key: K, value: string | undefined): Partial<Record<K, string>> {
+  return value ? ({ [key]: value } as Record<K, string>) : {};
+}

package/src/telemetry/types.ts

@@ -0,0 +1,33 @@
+export type TraceGeneration = {
+  traceId: string;
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string;
+  provider: string;
+  model?: string;
+  startedAt: string;
+  finishedAt: string;
+  tokensInput: number;
+  tokensOutput: number;
+  cachedTokensInput: number;
+  requestBytes: number;
+  responseBytes: number;
+  input?: unknown;
+  output?: unknown;
+  timeToFirstTokenMs?: number;
+};
+
+export type TelemetryError = {
+  traceId: string;
+  requestId: string;
+  executionId: string;
+  message: string;
+};
+
+export interface TraceTelemetryDriver {
+  recordGeneration(generation: TraceGeneration): Promise<void>;
+}
+
+export interface ErrorTelemetryDriver {
+  recordError(error: TelemetryError): Promise<void>;
+}

package/src/telemetry.test.ts

@@ -1,77 +1,125 @@
-import { describe, expect, it, vi } from "vitest";
 import { createExecutionEvent } from "@neutrome/lilsdk-ts";
-import { createRouterTelemetry } from "./telemetry.ts";
+import { describe, expect, it, vi } from "vitest";
+import {
+  createRouterTelemetry,
+  PosthogErrorTelemetry,
+  PosthogTraceTelemetry,
+} from "./telemetry/index.ts";
 
 describe("createRouterTelemetry", () => {
-  it("exports OTLP spans and errors to their separate endpoints", async () => {
-    const fetchMock = vi
-      .spyOn(globalThis, "fetch")
-      .mockResolvedValue(new Response(null, { status: 200 }));
-    const telemetry = createRouterTelemetry({
-      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://traces.example/v1/traces",
-      OTEL_EXPORTER_OTLP_TRACES_HEADERS: "authorization=Bearer%20trace-token",
-      OTEL_EXPORTER_OTLP_ERRORS_ENDPOINT: "https://errors.example/v1/traces",
-      OTEL_EXPORTER_OTLP_ERRORS_HEADERS: "authorization=Bearer%20error-token",
-    });
+  it("reports provider generations and exceptions through separate drivers", async () => {
+    const traceDriver = { recordGeneration: vi.fn(async () => {}) };
+    const errorDriver = { recordError: vi.fn(async () => {}) };
+    const telemetry = createRouterTelemetry({ traceDriver, errorDriver });
+
     telemetry.observe(
       createExecutionEvent({
         kind: "provider.started",
         requestId: "request-1",
         executionId: "provider-1",
-        data: { startedAt: "2026-07-13T12:00:00.000Z", provider: "openai" },
+        data: {
+          startedAt: "2026-07-13T12:00:00.000Z",
+          provider: "openrouter",
+          model: "gpt-5-chat",
+        },
+      }),
+    );
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "provider.usage",
+        requestId: "request-1",
+        executionId: "provider-1",
+        data: {
+          tokensInput: 12,
+          tokensOutput: 8,
+          input: { messages: [{ role: "user", content: "hello" }] },
+          output: { choices: [{ message: { content: "hi" } }] },
+        },
       }),
     );
     telemetry.observe(
       createExecutionEvent({
-        kind: "execution.failed",
+        kind: "provider.finished",
         requestId: "request-1",
         executionId: "provider-1",
-        data: { message: "upstream unavailable" },
+        data: { finishedAt: "2026-07-13T12:00:01.000Z" },
       }),
     );
+    telemetry.recordError({
+      message: "tool unavailable",
+      requestId: "request-1",
+      executionId: "tool-1",
+    });
 
     await telemetry.flush();
 
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(fetchMock.mock.calls[0]?.[0]).toBe(
-      "https://traces.example/v1/traces",
+    expect(traceDriver.recordGeneration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: "openrouter",
+        model: "gpt-5-chat",
+        tokensInput: 12,
+        tokensOutput: 8,
+        input: { messages: [{ role: "user", content: "hello" }] },
+      }),
     );
-    expect(fetchMock.mock.calls[1]?.[0]).toBe(
-      "https://errors.example/v1/traces",
+    expect(errorDriver.recordError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "tool unavailable" }),
     );
-    expect(fetchMock.mock.calls[0]?.[1]?.headers).toMatchObject({
-      authorization: "Bearer trace-token",
-    });
-    expect(fetchMock.mock.calls[1]?.[1]?.headers).toMatchObject({
-      authorization: "Bearer error-token",
-    });
-    expect(fetchMock.mock.calls[1]?.[1]?.body).toContain("resourceLogs");
-    fetchMock.mockRestore();
   });
+});
+
+describe("PostHog telemetry drivers", () => {
+  it("uses the native AI event and exception APIs independently", async () => {
+    const captureImmediate = vi.fn(async () => {});
+    const captureExceptionImmediate = vi.fn(async () => {});
+    const client = {
+      capture: vi.fn(),
+      captureImmediate,
+      captureExceptionImmediate,
+    };
+    const traces = new PosthogTraceTelemetry(client as never, "workspace-1");
+    const errors = new PosthogErrorTelemetry(client as never, "workspace-1");
 
-  it("logs a rejected exporter response without exposing credentials", async () => {
-    const fetchMock = vi
-      .spyOn(globalThis, "fetch")
-      .mockResolvedValue(
-        new Response(null, { status: 401, statusText: "Unauthorized" }),
-      );
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const telemetry = createRouterTelemetry({
-      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://traces.example/v1/traces",
-      OTEL_EXPORTER_OTLP_TRACES_HEADERS: "authorization=Bearer%20trace-token",
+    await traces.recordGeneration({
+      traceId: "trace-1",
+      requestId: "request-1",
+      executionId: "provider-1",
+      provider: "openrouter",
+      model: "gpt-5-chat",
+      startedAt: "2026-07-13T12:00:00.000Z",
+      finishedAt: "2026-07-13T12:00:01.000Z",
+      tokensInput: 3,
+      tokensOutput: 5,
+      cachedTokensInput: 1,
+      requestBytes: 40,
+      responseBytes: 80,
+      input: { prompt: "hello" },
+      output: { text: "hi" },
     });
-    telemetry.recordError({
-      message: "request failed",
+    await errors.recordError({
+      traceId: "trace-1",
       requestId: "request-1",
-      executionId: "execution-1",
+      executionId: "provider-1",
+      message: "upstream unavailable",
     });
 
-    await telemetry.flush();
-
-    expect(errorSpy).toHaveBeenCalledWith(
-      "[telemetry] OTLP traces export rejected: 401 Unauthorized",
+    expect(captureImmediate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        distinctId: "workspace-1",
+        event: "$ai_generation",
+        properties: expect.objectContaining({
+          $ai_trace_id: "trace-1",
+          $ai_provider: "openrouter",
+          $ai_model: "gpt-5-chat",
+          $ai_input_tokens: 3,
+          $ai_output_tokens: 5,
+        }),
+      }),
+    );
+    expect(captureExceptionImmediate).toHaveBeenCalledWith(
+      expect.any(Error),
+      "workspace-1",
+      expect.objectContaining({ "lil.trace_id": "trace-1" }),
     );
-    fetchMock.mockRestore();
-    errorSpy.mockRestore();
   });
 });

package/src/otlp.ts

@@ -1,189 +0,0 @@
-export type OtlpSpan = {
-  traceId: string;
-  spanId: string;
-  parentSpanId?: string;
-  name: string;
-  startTimeUnixNano: string;
-  endTimeUnixNano: string;
-  attributes: OtlpAttribute[];
-  status?: { code: number; message?: string };
-};
-
-type Environment = Record<string, unknown>;
-type OtlpAttribute = {
-  key: string;
-  value: { stringValue?: string; intValue?: string; boolValue?: boolean };
-};
-type OtlpLogRecord = {
-  timeUnixNano: string;
-  severityText: "ERROR";
-  body: { stringValue: string };
-  attributes: OtlpAttribute[];
-};
-
-export async function exportOtlp(
-  env: Environment,
-  signal: "traces" | "errors",
-  spans: OtlpSpan[],
-): Promise<void> {
-  if (spans.length === 0) return;
-  const endpoint = endpointFor(env, signal);
-  if (!endpoint) return;
-  try {
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...headersFor(env, signal),
-      },
-      body: JSON.stringify(otlpPayload(env, signal, spans)),
-    });
-    if (!response.ok) {
-      console.error(
-        `[telemetry] OTLP ${signal} export rejected: ${response.status} ${response.statusText}`,
-      );
-    }
-  } catch (error) {
-    console.error("[telemetry] OTLP export failed", error);
-  }
-}
-
-function otlpPayload(
-  env: Environment,
-  signal: "traces" | "errors",
-  spans: OtlpSpan[],
-): Record<string, unknown> {
-  const resource = {
-    attributes: attributes({
-      "service.name": stringEnv(env, "OTEL_SERVICE_NAME") ?? "neutrome-router",
-    }),
-  };
-  if (signal === "traces") {
-    return {
-      resourceSpans: [
-        {
-          resource,
-          scopeSpans: [{ scope: { name: "@neutrome/open-ai-router" }, spans }],
-        },
-      ],
-    };
-  }
-  return {
-    resourceLogs: [
-      {
-        resource,
-        scopeLogs: [
-          {
-            scope: { name: "@neutrome/open-ai-router" },
-            logRecords: spans.map(errorLogRecord),
-          },
-        ],
-      },
-    ],
-  };
-}
-
-function errorLogRecord(span: OtlpSpan): OtlpLogRecord {
-  return {
-    timeUnixNano: span.endTimeUnixNano,
-    severityText: "ERROR",
-    body: { stringValue: span.status?.message ?? span.name },
-    attributes: span.attributes,
-  };
-}
-
-export function rootOtlpSpan(input: {
-  traceId: string;
-  spanId: string;
-  startedAt: string;
-  finishedAt: string;
-  error?: string;
-}): OtlpSpan {
-  return {
-    traceId: input.traceId,
-    spanId: input.spanId,
-    name: "router.request",
-    startTimeUnixNano: unixNanos(input.startedAt),
-    endTimeUnixNano: unixNanos(input.finishedAt),
-    attributes: [],
-    ...(input.error ? { status: { code: 2, message: input.error } } : {}),
-  };
-}
-
-export function attributes(values: Record<string, unknown>): OtlpAttribute[] {
-  const result: OtlpAttribute[] = [];
-  for (const [key, value] of Object.entries(values)) {
-    if (typeof value === "string")
-      result.push({ key, value: { stringValue: value } });
-    else if (typeof value === "boolean")
-      result.push({ key, value: { boolValue: value } });
-    else if (typeof value === "number" && Number.isFinite(value))
-      result.push({ key, value: { intValue: String(Math.trunc(value)) } });
-  }
-  return result;
-}
-
-export function unixNanos(timestamp: string): string {
-  return `${Date.parse(timestamp)}000000`;
-}
-export function randomHex(bytes: number): string {
-  return [...crypto.getRandomValues(new Uint8Array(bytes))]
-    .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("");
-}
-
-function endpointFor(
-  env: Environment,
-  signal: "traces" | "errors",
-): string | undefined {
-  const endpoint = stringEnv(
-    env,
-    signal === "traces"
-      ? "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
-      : "OTEL_EXPORTER_OTLP_ERRORS_ENDPOINT",
-  );
-  if (endpoint) return endpoint;
-  const base = stringEnv(env, "OTEL_EXPORTER_OTLP_ENDPOINT");
-  return base
-    ? new URL(
-        "v1/traces",
-        `${base.endsWith("/") ? base : `${base}/`}`,
-      ).toString()
-    : undefined;
-}
-
-function headersFor(
-  env: Environment,
-  signal: "traces" | "errors",
-): Record<string, string> {
-  return parseHeaders(
-    stringEnv(
-      env,
-      signal === "traces"
-        ? "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
-        : "OTEL_EXPORTER_OTLP_ERRORS_HEADERS",
-    ) ?? stringEnv(env, "OTEL_EXPORTER_OTLP_HEADERS"),
-  );
-}
-
-function parseHeaders(value: string | undefined): Record<string, string> {
-  if (!value) return {};
-  return Object.fromEntries(
-    value.split(",").flatMap((entry) => {
-      const index = entry.indexOf("=");
-      return index < 1
-        ? []
-        : [
-            [
-              entry.slice(0, index).trim(),
-              decodeURIComponent(entry.slice(index + 1).trim()),
-            ],
-          ];
-    }),
-  );
-}
-
-function stringEnv(env: Environment, key: string): string | undefined {
-  const value = env[key];
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}

package/src/telemetry.ts

@@ -1,316 +0,0 @@
-import type { ExecutionEvent } from "@neutrome/lilsdk-ts";
-import {
-  attributes,
-  exportOtlp,
-  randomHex,
-  rootOtlpSpan,
-  unixNanos,
-  type OtlpSpan,
-} from "./otlp.ts";
-
-type TelemetryEnvironment = Record<string, unknown>;
-
-export type ExecutionSummary = {
-  spanId: string;
-  startedAt: string;
-  finishedAt: string;
-  spans: ExecutionSummarySpan[];
-  totalTokensInput: number;
-  totalTokensOutput: number;
-  totalCachedTokensInput: number;
-  error?: string;
-};
-
-export type ExecutionSummarySpan = {
-  kind: "request" | "provider" | "tool" | "executor";
-  event: string;
-  requestId: string;
-  executionId: string;
-  parentExecutionId?: string;
-  model?: string;
-  provider?: string;
-  toolName?: string;
-  executor?: string;
-  startedAt: string;
-  finishedAt?: string;
-  tokensInput: number;
-  tokensOutput: number;
-  cachedTokensInput: number;
-  requestBytes: number;
-  responseBytes: number;
-  error?: string;
-};
-
-export type RouterTelemetry = {
-  observe(event: ExecutionEvent): void;
-  recordError(input: {
-    message: string;
-    requestId: string;
-    executionId: string;
-  }): void;
-  flush(): Promise<void>;
-  summary(): ExecutionSummary;
-};
-
-export function createRouterTelemetry(
-  env: TelemetryEnvironment,
-): RouterTelemetry {
-  const traceId = randomHex(16);
-  const rootSpanId = randomHex(8);
-  const startedAt = new Date().toISOString();
-  const spans: ExecutionSummarySpan[] = [];
-  const otlpSpans: OtlpSpan[] = [];
-  const activeSpans = new Map<
-    string,
-    { summary: ExecutionSummarySpan; otlp: OtlpSpan }
-  >();
-  const executionSpanIds = new Map<string, string>();
-  const errors: OtlpSpan[] = [];
-  let error: string | undefined;
-
-  return { observe, recordError, flush, summary };
-
-  function observe(event: ExecutionEvent): void {
-    const timing = eventTiming(event);
-    if (isInvocationStarted(event.kind)) {
-      const pair = createSpan(
-        event,
-        timing.startedAt ?? event.timestamp,
-        undefined,
-      );
-      spans.push(pair.summary);
-      activeSpans.set(event.executionId, pair);
-      executionSpanIds.set(event.executionId, pair.otlp.spanId);
-      return;
-    }
-    if (isInvocationFinished(event.kind)) {
-      const active = activeSpans.get(event.executionId);
-      if (active) {
-        const finishedAt = timing.finishedAt ?? event.timestamp;
-        active.summary.finishedAt = finishedAt;
-        active.otlp.endTimeUnixNano = unixNanos(finishedAt);
-        activeSpans.delete(event.executionId);
-      }
-      return;
-    }
-    if (event.kind === "provider.usage") {
-      const active = activeSpans.get(event.executionId);
-      if (active) applyUsage(active.summary, active.otlp, event);
-      return;
-    }
-    if (event.kind === "execution.failed") {
-      const message = stringValue(event.data?.message) ?? "Execution failed";
-      error ??= message;
-      const active = activeSpans.get(event.executionId);
-      if (active)
-        markSpanError(active.summary, active.otlp, message, event.timestamp);
-      recordError({
-        message,
-        requestId: event.requestId,
-        executionId: event.executionId,
-      });
-      return;
-    }
-    if (!timing.startedAt) return;
-    const pair = createSpan(
-      event,
-      timing.startedAt,
-      timing.finishedAt ?? event.timestamp,
-    );
-    spans.push(pair.summary);
-  }
-
-  function recordError(input: {
-    message: string;
-    requestId: string;
-    executionId: string;
-  }): void {
-    error ??= input.message;
-    const now = new Date().toISOString();
-    errors.push({
-      traceId,
-      spanId: randomHex(8),
-      parentSpanId: executionSpanIds.get(input.executionId) ?? rootSpanId,
-      name: "router.error",
-      startTimeUnixNano: unixNanos(now),
-      endTimeUnixNano: unixNanos(now),
-      attributes: attributes({
-        "error.message": input.message,
-        "lil.request.id": input.requestId,
-        "lil.execution.id": input.executionId,
-      }),
-      status: { code: 2, message: input.message },
-    });
-  }
-
-  async function flush(): Promise<void> {
-    const finishedAt = new Date().toISOString();
-    for (const active of activeSpans.values()) {
-      active.summary.finishedAt ??= finishedAt;
-      active.otlp.endTimeUnixNano = unixNanos(active.summary.finishedAt);
-    }
-    activeSpans.clear();
-    const root = rootOtlpSpan({
-      traceId,
-      spanId: rootSpanId,
-      startedAt,
-      finishedAt,
-      ...(error ? { error } : {}),
-    });
-    await Promise.all([
-      exportOtlp(env, "traces", [root, ...otlpSpans]),
-      exportOtlp(env, "errors", errors),
-    ]);
-  }
-
-  function summary(): ExecutionSummary {
-    const finishedAt = new Date().toISOString();
-    return {
-      spanId: traceId,
-      startedAt,
-      finishedAt,
-      spans,
-      totalTokensInput: spans.reduce(
-        (total, span) => total + span.tokensInput,
-        0,
-      ),
-      totalTokensOutput: spans.reduce(
-        (total, span) => total + span.tokensOutput,
-        0,
-      ),
-      totalCachedTokensInput: spans.reduce(
-        (total, span) => total + span.cachedTokensInput,
-        0,
-      ),
-      ...(error ? { error } : {}),
-    };
-  }
-
-  function createSpan(
-    event: ExecutionEvent,
-    startedAt: string,
-    finishedAt: string | undefined,
-  ) {
-    const kind = spanKind(event.kind);
-    const summary: ExecutionSummarySpan = {
-      kind,
-      event: event.kind,
-      requestId: event.requestId,
-      executionId: event.executionId,
-      ...(event.parentExecutionId
-        ? { parentExecutionId: event.parentExecutionId }
-        : {}),
-      ...eventDetails(event),
-      startedAt,
-      ...(finishedAt ? { finishedAt } : {}),
-      tokensInput: 0,
-      tokensOutput: 0,
-      cachedTokensInput: 0,
-      requestBytes: 0,
-      responseBytes: 0,
-    };
-    const parentSpanId = event.parentExecutionId
-      ? executionSpanIds.get(event.parentExecutionId)
-      : rootSpanId;
-    const otlp: OtlpSpan = {
-      traceId,
-      spanId: randomHex(8),
-      ...(parentSpanId ? { parentSpanId } : {}),
-      name: event.kind,
-      startTimeUnixNano: unixNanos(startedAt),
-      endTimeUnixNano: unixNanos(finishedAt ?? startedAt),
-      attributes: attributes({
-        "lil.request.id": event.requestId,
-        "lil.execution.id": event.executionId,
-        ...event.data,
-      }),
-    };
-    otlpSpans.push(otlp);
-    return { summary, otlp };
-  }
-}
-
-function eventTiming(event: ExecutionEvent): {
-  startedAt: string | undefined;
-  finishedAt: string | undefined;
-} {
-  return {
-    startedAt: stringValue(event.data?.startedAt),
-    finishedAt: stringValue(event.data?.finishedAt),
-  };
-}
-
-function isInvocationStarted(kind: string): boolean {
-  return kind.endsWith(".started") || kind.endsWith(".stream_started");
-}
-
-function isInvocationFinished(kind: string): boolean {
-  return kind.endsWith(".finished") || kind.endsWith(".stream_finished");
-}
-
-function spanKind(kind: string): ExecutionSummarySpan["kind"] {
-  if (kind.startsWith("provider.")) return "provider";
-  if (kind.startsWith("tool.")) return "tool";
-  if (kind.startsWith("executor.")) return "executor";
-  return "request";
-}
-
-function eventDetails(event: ExecutionEvent): Partial<ExecutionSummarySpan> {
-  return {
-    ...optional("model", stringValue(event.data?.model)),
-    ...optional("provider", stringValue(event.data?.provider)),
-    ...optional("toolName", stringValue(event.data?.toolName)),
-    ...optional(
-      "executor",
-      stringValue(event.data?.executor) ?? stringValue(event.data?.executorId),
-    ),
-  };
-}
-
-function applyUsage(
-  summary: ExecutionSummarySpan,
-  span: OtlpSpan,
-  event: ExecutionEvent,
-): void {
-  summary.tokensInput = numberValue(event.data?.tokensInput);
-  summary.tokensOutput = numberValue(event.data?.tokensOutput);
-  summary.cachedTokensInput = numberValue(event.data?.cachedTokensInput);
-  summary.requestBytes = numberValue(event.data?.requestBytes);
-  summary.responseBytes = numberValue(event.data?.responseBytes);
-  span.attributes.push(
-    ...attributes({
-      "gen_ai.usage.input_tokens": summary.tokensInput,
-      "gen_ai.usage.output_tokens": summary.tokensOutput,
-      "lil.usage.cached_input_tokens": summary.cachedTokensInput,
-      "http.request.body.size": summary.requestBytes,
-      "http.response.body.size": summary.responseBytes,
-    }),
-  );
-}
-
-function markSpanError(
-  summary: ExecutionSummarySpan,
-  span: OtlpSpan,
-  message: string,
-  finishedAt: string,
-): void {
-  summary.error = message;
-  summary.finishedAt ??= finishedAt;
-  span.endTimeUnixNano = unixNanos(summary.finishedAt);
-  span.status = { code: 2, message };
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-function numberValue(value: unknown): number {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0
-    ? value
-    : 0;
-}
-function optional<K extends string>(
-  key: K,
-  value: string | undefined,
-): Partial<Record<K, string>> {
-  return value ? ({ [key]: value } as Record<K, string>) : {};
-}