@neutrome/open-ai-router 0.6.4 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/router/error-codec.ts

@@ -23,7 +23,13 @@ export async function toProviderError(
   const summary =
     firstError(program)?.message ||
     `Provider ${provider.name} returned ${response.status}`;
-  return new ProviderHttpError(summary, response.status, program);
+  return new ProviderHttpError(
+    summary,
+    response.status,
+    program,
+    errorBody(body),
+    body.byteLength,
+  );
 }
 
 export function errorResponse(
@@ -168,3 +174,15 @@ export function toBody(bytes: Uint8Array): ArrayBuffer {
     bytes.byteOffset + bytes.byteLength,
   ) as ArrayBuffer;
 }
+
+function errorBody(body: Uint8Array): Record<string, unknown> {
+  const text = new TextDecoder().decode(body);
+  try {
+    const value: unknown = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? { json: value }
+      : { text };
+  } catch {
+    return { text };
+  }
+}

package/src/router/errors.ts

@@ -28,6 +28,14 @@ export type ExecutionErrorDetails = {
   transform?: string;
   target?: string;
   source?: "provider" | "executor";
+  upstream?: {
+    status: number;
+    source?: string;
+    kind?: string;
+    code?: unknown;
+    responseBytes?: number;
+    body?: Record<string, unknown>;
+  };
 };
 
 export class ExecutionError extends Error {
@@ -74,6 +82,8 @@ export class ProviderHttpError extends Error {
     message: string,
     readonly status: number,
     readonly program: import("@neutrome/lil-engine").Program,
+    readonly body: Record<string, unknown>,
+    readonly responseBytes: number,
   ) {
     super(message);
   }

package/src/router/execution-resolution.ts

@@ -1,5 +1,9 @@
-import type { Program } from "@neutrome/lil-engine";
-import { ExecutionError, isExecutionError } from "./errors.ts";
+import { firstError, type Program } from "@neutrome/lil-engine";
+import {
+  ExecutionError,
+  isExecutionError,
+  ProviderHttpError,
+} from "./errors.ts";
 import { executionTargetId } from "./targets.ts";
 import type {
   ExecutionRuntimeOptions,
@@ -95,6 +99,28 @@ export function normalizeExecutionError(
   maxDepth: number,
 ): ExecutionError {
   if (isExecutionError(error)) return error;
+  if (error instanceof ProviderHttpError) {
+    const upstream = firstError(error.program);
+    return new ExecutionError("provider", error.message, {
+      stage: fallbackStage,
+      details: {
+        depth,
+        maxDepth,
+        target: executionTargetId(target),
+        upstream: {
+          status: error.status,
+          ...(upstream?.source ? { source: upstream.source } : {}),
+          ...(upstream?.kind ? { kind: upstream.kind } : {}),
+          ...(upstream?.data.code === undefined
+            ? {}
+            : { code: upstream.data.code }),
+          responseBytes: error.responseBytes,
+          body: error.body,
+        },
+      },
+      cause: error,
+    });
+  }
   if (isAbortLike(error)) {
     return new ExecutionError("cancellation", "Execution aborted", {
       stage: fallbackStage,

package/src/router/provider-invoker.ts

@@ -17,6 +17,7 @@ import type { RequestContext } from "../upstream-auth/types.ts";
 import { streamProvider } from "./provider-stream.ts";
 import type { RouterRuntime } from "./runtime.ts";
 import { observeTimedExecution } from "./execution-events.ts";
+import { normalizeChatRequest } from "../telemetry/chat-normalization.ts";
 
 const DEFAULT_UPSTREAM_TIMEOUT_MS = 120_000;
 
@@ -54,6 +55,8 @@ export function createFetchProviderInvoker(
             provider: provider.name,
             model: providerCtx.target.model,
             bytes: reqBody.byteLength,
+            requestBytes: reqBody.byteLength,
+            input: normalizeChatRequest(resolvedRequest),
           },
         });
         const reqBytes = reqBody.byteLength;

package/src/router/provider-stream.ts

@@ -21,6 +21,7 @@ import { isSse } from "../util/headers.ts";
 import { eventDataLines, splitSseEvents } from "../util/sse.ts";
 import type { RouterRuntime } from "./runtime.ts";
 import { observeTimedExecution } from "./execution-events.ts";
+import { normalizeChatRequest } from "../telemetry/chat-normalization.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -58,6 +59,8 @@ export async function* streamProvider(
         provider: provider.name,
         model: providerCtx.target.model,
         bytes: reqBody.byteLength,
+        requestBytes: reqBody.byteLength,
+        input: normalizeChatRequest(resolvedRequest),
       },
     });
     const reqBytes = reqBody.byteLength;

package/src/telemetry/posthog.ts

@@ -33,6 +33,14 @@ export class PosthogTraceTelemetry implements TraceTelemetryDriver {
       ...(generation.model ? { model: generation.model } : {}),
       input: generation.input ?? null,
       output: generation.output ?? null,
+      ...(generation.httpStatus === undefined
+        ? {}
+        : { httpStatus: generation.httpStatus }),
+      ...(generation.error
+        ? {
+            error: namedError(generation.error.name, generation.error.message),
+          }
+        : {}),
       latency: elapsedSeconds(generation.startedAt, generation.finishedAt),
       ...(generation.timeToFirstTokenMs === undefined
         ? {}
@@ -48,6 +56,12 @@ export class PosthogTraceTelemetry implements TraceTelemetryDriver {
         "lil.cached_input_tokens": generation.cachedTokensInput || undefined,
         "lil.request_bytes": generation.requestBytes || undefined,
         "lil.response_bytes": generation.responseBytes || undefined,
+        "lil.error_kind": generation.error?.kind,
+        "lil.error_stage": generation.error?.stage,
+        "lil.error_status": generation.error?.status,
+        "lil.error_code": generation.error?.code,
+        "lil.error_details": generation.error?.details,
+        "lil.upstream_error_body": generation.error?.details?.body,
       }),
       captureImmediate: true,
     });
@@ -62,12 +76,18 @@ export class PosthogErrorTelemetry implements ErrorTelemetryDriver {
 
   async recordError(error: TelemetryError): Promise<void> {
     await this.client.captureExceptionImmediate(
-      new Error(error.message),
+      namedError(error.name ?? "RouterError", error.message),
       this.distinctId,
       {
         "lil.trace_id": error.traceId,
         "lil.request_id": error.requestId,
         "lil.execution_id": error.executionId,
+        "lil.error_kind": error.kind,
+        "lil.error_stage": error.stage,
+        "lil.error_status": error.status,
+        "lil.error_code": error.code,
+        "lil.error_details": error.details,
+        "lil.upstream_error_body": error.details?.body,
       },
     );
   }
@@ -101,8 +121,14 @@ 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>) {
+function compact(values: Record<string, unknown>) {
   return Object.fromEntries(
     Object.entries(values).filter(([, value]) => value !== undefined),
   );
 }
+
+function namedError(name: string, message: string): Error {
+  const error = new Error(message);
+  error.name = name;
+  return error;
+}

package/src/telemetry/router.ts

@@ -70,6 +70,7 @@ export function createRouterTelemetry(
       spans.push(summary);
       active.set(event.executionId, span);
       appendEvent(summary, event, data);
+      mergeSpan(summary, data);
       return;
     }
     const span = active.get(event.executionId);
@@ -84,10 +85,11 @@ export function createRouterTelemetry(
         event.timestamp,
       );
     if (event.kind === "execution.failed") {
-      const message = data.message ?? "Execution failed";
-      failSpan(span.summary, message, event.timestamp);
+      const error = telemetryError(event, data);
+      failSpan(span.summary, error.message, event.timestamp);
+      applyFailure(span.summary, error);
       recordError({
-        message,
+        ...error,
         requestId: event.requestId,
         executionId: event.executionId,
       });
@@ -104,7 +106,7 @@ export function createRouterTelemetry(
   ): void {
     if (event.kind === "execution.failed") {
       recordError({
-        message: data.message ?? "Execution failed",
+        ...telemetryError(event, data),
         requestId: event.requestId,
         executionId: event.executionId,
       });
@@ -185,6 +187,22 @@ export function createRouterTelemetry(
       responseBytes: span.responseBytes,
       ...(span.request ? { input: span.request } : {}),
       ...(span.response ? { output: span.response } : {}),
+      ...(span.error
+        ? {
+            httpStatus: span.errorStatus,
+            error: {
+              name: span.errorName ?? "ExecutionError",
+              message: span.error,
+              ...(span.errorKind ? { kind: span.errorKind } : {}),
+              ...(span.errorStage ? { stage: span.errorStage } : {}),
+              ...(span.errorStatus === undefined
+                ? {}
+                : { status: span.errorStatus }),
+              ...(span.errorCode === undefined ? {} : { code: span.errorCode }),
+              ...(span.errorDetails ? { details: span.errorDetails } : {}),
+            },
+          }
+        : {}),
       ...(activeSpan.timeToFirstTokenMs === undefined
         ? {}
         : { timeToFirstTokenMs: activeSpan.timeToFirstTokenMs }),
@@ -192,6 +210,60 @@ export function createRouterTelemetry(
   }
 }
 
+function applyFailure(
+  span: ExecutionSummarySpan,
+  error: Omit<TelemetryError, "traceId" | "requestId" | "executionId">,
+): void {
+  if (error.name) span.errorName = error.name;
+  if (error.kind) span.errorKind = error.kind;
+  if (error.stage) span.errorStage = error.stage;
+  if (error.status !== undefined) span.errorStatus = error.status;
+  if (error.code !== undefined) span.errorCode = error.code;
+  if (error.details) {
+    span.errorDetails = error.details;
+    const responseBytes = finiteNumber(error.details.responseBytes);
+    if (responseBytes !== undefined) span.responseBytes = responseBytes;
+  }
+}
+
+function telemetryError(
+  event: ExecutionEvent,
+  data: ReturnType<typeof eventData>,
+): Omit<TelemetryError, "traceId" | "requestId" | "executionId"> {
+  const upstream = object(data.upstream);
+  const status = finiteNumber(upstream?.status);
+  const kind = text(upstream?.kind) ?? event.errorKind;
+  const code = upstream?.code;
+  const stage = text(data.stage);
+  return {
+    message: data.message ?? "Execution failed",
+    name: ["Router", event.errorKind ?? "error", kind, status]
+      .filter((part) => part !== undefined)
+      .join("."),
+    ...(event.errorKind ? { kind: event.errorKind } : {}),
+    ...(stage ? { stage } : {}),
+    ...(status === undefined ? {} : { status }),
+    ...(code === undefined ? {} : { code }),
+    ...(upstream ? { details: upstream } : {}),
+  };
+}
+
+function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
 async function reportAll(
   reports: Array<Promise<void> | undefined>,
 ): Promise<void> {

package/src/telemetry/timeline.ts

@@ -32,6 +32,12 @@ export type ExecutionSummarySpan = {
   request?: Record<string, unknown>;
   response?: Record<string, unknown>;
   error?: string;
+  errorName?: string;
+  errorKind?: string;
+  errorStage?: string;
+  errorStatus?: number;
+  errorCode?: unknown;
+  errorDetails?: Record<string, unknown>;
   timeline: ExecutionTimelineEvent[];
 };
 

package/src/telemetry/types.ts

@@ -15,6 +15,18 @@ export type TraceGeneration = {
   input?: unknown;
   output?: unknown;
   timeToFirstTokenMs?: number;
+  httpStatus?: number;
+  error?: TelemetryFailure;
+};
+
+export type TelemetryFailure = {
+  name: string;
+  message: string;
+  kind?: string;
+  stage?: string;
+  status?: number;
+  code?: unknown;
+  details?: Record<string, unknown>;
 };
 
 export type TelemetryError = {
@@ -22,6 +34,12 @@ export type TelemetryError = {
   requestId: string;
   executionId: string;
   message: string;
+  name?: string;
+  kind?: string;
+  stage?: string;
+  status?: number;
+  code?: unknown;
+  details?: Record<string, unknown>;
 };
 
 export interface TraceTelemetryDriver {

package/src/telemetry.test.ts

@@ -123,6 +123,62 @@ describe("createRouterTelemetry", () => {
       status: "ok",
     });
   });
+
+  it("keeps failed provider calls in the trace with typed upstream details", 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: "cloudflare",
+          model: "@cf/model",
+          input: { messages: [{ role: "user", content: "hello" }] },
+        },
+      }),
+    );
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "execution.failed",
+        requestId: "request-1",
+        executionId: "provider-1",
+        errorKind: "provider",
+        data: {
+          message: "Provider returned error",
+          stage: "provider_invoke",
+          upstream: {
+            status: 400,
+            kind: "invalid_request_error",
+            code: "bad_request",
+            body: { error: "invalid model" },
+          },
+        },
+      }),
+    );
+
+    await telemetry.flush();
+
+    expect(traceDriver.recordGeneration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpStatus: 400,
+        input: { messages: [{ role: "user", content: "hello" }] },
+        error: expect.objectContaining({
+          name: "Router.provider.invalid_request_error.400",
+          code: "bad_request",
+        }),
+      }),
+    );
+    expect(errorDriver.recordError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: "Router.provider.invalid_request_error.400",
+        status: 400,
+      }),
+    );
+  });
 });
 
 describe("trace chat normalization", () => {