@neutrome/open-ai-router 0.4.2 → 0.5.0

package/src/router/upstream-client.ts

@@ -0,0 +1,137 @@
+import type { ProviderInvocationContext } from "./execution-types.ts";
+import { RouterError } from "./errors.ts";
+import { toBody } from "./error-codec.ts";
+import type { ProviderRuntime, RouterRuntime } from "./runtime.ts";
+import type {
+  RequestContext,
+  TargetAuthContext,
+} from "../upstream-auth/types.ts";
+import { cloneForwardHeaders } from "../util/headers.ts";
+import { observeTimedExecution } from "./execution-events.ts";
+
+export async function fetchProvider(
+  runtime: RouterRuntime,
+  ctx: RequestContext,
+  provider: ProviderRuntime,
+  body: Uint8Array,
+  signal: AbortSignal,
+  providerCtx: ProviderInvocationContext,
+): Promise<Response> {
+  const headers = cloneForwardHeaders(ctx.request.headers);
+  headers.set("content-type", "application/json");
+  for (const [key, value] of Object.entries(provider.headers)) {
+    headers.set(key, value);
+  }
+
+  for (const driver of runtime.upstreamAuthChain) {
+    const targetCtx: TargetAuthContext = {
+      ...ctx,
+      providerName: provider.name,
+    };
+    const authStartedMs = Date.now();
+    const auth = await driver.collectTarget(targetCtx);
+    observeTimedExecution({
+      observe: providerCtx.observe,
+      kind: "upstream_auth.resolve_target",
+      requestId: providerCtx.requestId,
+      executionId: providerCtx.executionId,
+      ...(providerCtx.parentExecutionId
+        ? { parentExecutionId: providerCtx.parentExecutionId }
+        : {}),
+      startedAtMs: authStartedMs,
+      finishedAtMs: Date.now(),
+      data: {
+        provider: provider.name,
+        model: providerCtx.target.model,
+        driver: driver.name,
+        source: auth?.source,
+        matched: !!auth,
+      },
+    });
+    if (!auth) {
+      continue;
+    }
+    new Headers(auth.headers).forEach((value, key) => headers.set(key, value));
+    break;
+  }
+
+  return runtime.fetchImpl(`${provider.apiBaseUrl}${provider.endpointPath}`, {
+    method: "POST",
+    headers,
+    body: toBody(body),
+    signal,
+  });
+}
+
+export function getProviderOrThrow(
+  runtime: RouterRuntime,
+  providerName: string | undefined,
+) {
+  if (!providerName) {
+    throw new RouterError(
+      "No provider specified on execution target",
+      500,
+      "provider_not_configured",
+    );
+  }
+  const provider = runtime.providers.get(providerName);
+  if (!provider) {
+    throw new RouterError(
+      `Provider ${providerName} is not configured`,
+      500,
+      "provider_not_configured",
+    );
+  }
+  return provider;
+}
+
+export function createUpstreamSignal(
+  signal: AbortSignal,
+  timeoutMs: number,
+): {
+  signal: AbortSignal;
+  cleanup(): void;
+} {
+  if (timeoutMs <= 0) {
+    return {
+      signal,
+      cleanup() {},
+    };
+  }
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(signal.reason);
+  if (signal.aborted) {
+    onAbort();
+  } else {
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  const timer = setTimeout(() => {
+    controller.abort(
+      new RouterError(
+        `Upstream provider timed out after ${timeoutMs}ms`,
+        504,
+        "upstream_timeout",
+      ),
+    );
+  }, timeoutMs);
+
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+export function normalizeUpstreamAbort(
+  error: unknown,
+  signal: AbortSignal,
+): unknown {
+  if (signal.aborted && signal.reason instanceof RouterError) {
+    return signal.reason;
+  }
+  return error;
+}

package/src/telemetry.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from "vitest";
+import { createExecutionEvent } from "@neutrome/lilsdk-ts";
+import { createRouterTelemetry } from "./telemetry.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",
+    });
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "provider.started",
+        requestId: "request-1",
+        executionId: "provider-1",
+        data: { startedAt: "2026-07-13T12:00:00.000Z", provider: "openai" },
+      }),
+    );
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "execution.failed",
+        requestId: "request-1",
+        executionId: "provider-1",
+        data: { message: "upstream unavailable" },
+      }),
+    );
+
+    await telemetry.flush();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe(
+      "https://traces.example/v1/traces",
+    );
+    expect(fetchMock.mock.calls[1]?.[0]).toBe(
+      "https://errors.example/v1/traces",
+    );
+    expect(fetchMock.mock.calls[0]?.[1]?.headers).toMatchObject({
+      authorization: "Bearer trace-token",
+    });
+    expect(fetchMock.mock.calls[1]?.[1]?.headers).toMatchObject({
+      authorization: "Bearer error-token",
+    });
+    fetchMock.mockRestore();
+  });
+});

package/src/telemetry.ts

@@ -0,0 +1,316 @@
+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>) : {};
+}

package/src/trace-labels.ts

@@ -0,0 +1,29 @@
+import type { ExecutionEvent as AuditEvent } from "@neutrome/lilsdk-ts";
+
+export function traceTimingKind(event: AuditEvent): string {
+  if (event.kind.startsWith("upstream_auth.")) return "upstream_auth";
+  if (event.kind.startsWith("admission.")) return "admission";
+  if (event.kind.startsWith("response.")) return "response";
+  if (event.kind.startsWith("provider.")) return "provider";
+  if (event.kind.startsWith("executor.")) return "executor";
+  if (event.kind.startsWith("remote_mcp.")) return "remote_mcp";
+  if (event.kind.startsWith("tool.")) return "tool";
+  return "request";
+}
+
+export function traceSegmentLabel(event: AuditEvent): string {
+  switch (event.kind) {
+    case "request.received":
+      return "request";
+    case "provider.request":
+      return "provider-request";
+    case "provider.response":
+      return "provider-response";
+    case "provider.response_chunk":
+      return "provider-response-chunk";
+    case "tool.executed":
+      return "tool";
+    default:
+      return event.kind.replace(/\./g, "-") || "trace";
+  }
+}

package/src/upstream-auth/env.ts

@@ -1,6 +1,13 @@
-import type { AuthResult, TargetAuthContext, UpstreamAuthDriver } from "./types.ts";
+import type {
+  AuthResult,
+  TargetAuthContext,
+  UpstreamAuthDriver,
+} from "./types.ts";
 
-export function envAuthDriver(suffix = "_API_KEY", prefix = ""): UpstreamAuthDriver {
+export function envAuthDriver(
+  suffix = "_API_KEY",
+  prefix = "",
+): UpstreamAuthDriver {
   const counters = new Map<string, number>();
 
   return {
@@ -25,7 +32,12 @@ function resolveKey(
 ): string | null {
   const nValue = env[`${base}${suffix}S_N`];
   if (nValue) {
-    const n = typeof nValue === "string" ? parseInt(nValue, 10) : typeof nValue === "number" ? nValue : 0;
+    const n =
+      typeof nValue === "string"
+        ? parseInt(nValue, 10)
+        : typeof nValue === "number"
+          ? nValue
+          : 0;
     if (n > 0) {
       const prev = counters.get(base) ?? 0;
       const index = (prev % n) + 1;

package/src/upstream-auth/proxy.ts

@@ -1,4 +1,9 @@
-import type { AuthResult, RequestContext, TargetAuthContext, UpstreamAuthDriver } from "./types.ts";
+import type {
+  AuthResult,
+  RequestContext,
+  TargetAuthContext,
+  UpstreamAuthDriver,
+} from "./types.ts";
 
 export function proxyAuthDriver(headers: string[]): UpstreamAuthDriver {
   return {

package/src/upstream-auth/registry.ts

@@ -3,7 +3,9 @@ import type { UpstreamAuthDriver } from "./types.ts";
 import { proxyAuthDriver } from "./proxy.ts";
 import { envAuthDriver } from "./env.ts";
 
-export function buildUpstreamAuthChain(config?: UpstreamAuthConfigShape): UpstreamAuthDriver[] {
+export function buildUpstreamAuthChain(
+  config?: UpstreamAuthConfigShape,
+): UpstreamAuthDriver[] {
   if (!config) return [proxyAuthDriver(["authorization"]), envAuthDriver()];
   const order = config.order ?? ["proxy", "env"];
   const drivers: UpstreamAuthDriver[] = [];

package/src/util/glob.ts

@@ -1,4 +1,4 @@
-export function matchesGlob(value: string, pattern: string): boolean {
+function matchesGlob(value: string, pattern: string): boolean {
   const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
   const regex = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
   return regex.test(value);

package/src/util/model-syntax.ts

@@ -4,20 +4,20 @@ export type ModelSuffixSpec = {
   raw: string;
 };
 
-export type ParsedModelSyntax = {
+type ParsedModelSyntax = {
   baseModel: string;
   suffixes: ModelSuffixSpec[];
 };
 
 export function parseModelSyntax(
   model: string,
-  knownSuffixes?: ReadonlySet<string>,
+  modelSuffixes?: ReadonlySet<string>,
 ): ParsedModelSyntax {
   const [baseModel = "", ...suffixParts] = model.split("+");
   const suffixes = suffixParts.filter(Boolean).map((part) => {
     const [namePart = "", ...args] = part.split(":");
     const name = decodeURIComponent(namePart).toLowerCase();
-    if (knownSuffixes && !knownSuffixes.has(name)) {
+    if (modelSuffixes && !modelSuffixes.has(name)) {
       throw new Error(`Unknown model suffix: ${name}`);
     }
     return { name, args: args.map(decodeURIComponent), raw: part };

package/src/worker.ts

@@ -1,10 +1,12 @@
-type ExecutionContext = { waitUntil(p: Promise<unknown>): void; passThroughOnException(): void };
+type ExecutionContext = {
+  waitUntil(p: Promise<unknown>): void;
+  passThroughOnException(): void;
+};
 
 import type { RouterConfig } from "./router/index.ts";
-import { createApp } from "./example.ts";
+import { createRouterApp } from "./app/factory.ts";
 
 const config: RouterConfig = {
-  trace: true,
   upstreamAuth: {
     order: ["proxy", "env"],
     proxy: {
@@ -13,7 +15,7 @@ const config: RouterConfig = {
   },
   providers: {
     openrouter: {
-      api_base_url: "https://openrouter.ai/api/v1",
+      apiBaseUrl: "https://openrouter.ai/api/v1",
       style: "chat-completions",
       exports: ["*:free"],
     },
@@ -21,10 +23,14 @@ const config: RouterConfig = {
   modelNamespaces: {},
 };
 
-let appPromise: Promise<ReturnType<typeof createApp>> | undefined;
+let appPromise: Promise<ReturnType<typeof createRouterApp>> | undefined;
 
 async function getApp() {
-  return createApp({ config });
+  return createRouterApp({
+    config,
+    executorImplementations: {},
+    auth: { authenticate: async () => null },
+  });
 }
 
 export default {