@neutrome/open-ai-router 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -11,8 +11,8 @@
     "hono": "^4.12.18",
     "posthog-node": "^5.41.0",
     "zod": "^4.2.1",
-    "@neutrome/lil-engine": "0.4.1",
-    "@neutrome/lilsdk": "0.4.2"
+    "@neutrome/lil-engine": "0.4.2",
+    "@neutrome/lilsdk": "0.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/app/factory.test.ts

@@ -217,8 +217,8 @@ describe("createRouterApp trace finalization", () => {
     expect(waited).toHaveLength(1);
     await waited[0];
     expect(onExecutionSummary).toHaveBeenCalledTimes(1);
-    const events = onExecutionSummary.mock.calls[0]?.[0].spans.map(
-      (span) => span.event,
+    const events = onExecutionSummary.mock.calls[0]?.[0].spans.flatMap((span) =>
+      span.timeline.map((entry) => entry.event),
     );
     expect(events).toContain("admission.authenticate");
     expect(events).toContain("upstream_auth.resolve_target");

package/src/index.ts

@@ -13,6 +13,7 @@ export type {
   ErrorTelemetryDriver,
   ExecutionSummary,
   ExecutionSummarySpan,
+  ExecutionTimelineEvent,
   RouterTelemetry,
   TraceTelemetryDriver,
 } from "./telemetry/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;
@@ -108,12 +111,11 @@ export function createFetchProviderInvoker(
         const response = parseProviderResponse(provider.style, bytes);
         emitProviderUsage(
           providerCtx,
+          resolvedRequest,
           response,
           provider.name,
           reqBytes,
           bytes.byteLength,
-          jsonBody(reqBody),
-          jsonBody(bytes),
         );
         return response;
       } catch (error) {
@@ -134,11 +136,3 @@ 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

@@ -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;
@@ -102,7 +105,7 @@ export async function* streamProvider(
     let firstByteObserved = false;
     const streamReadStartedMs = Date.now();
     let lastChunkWithUsage: Program | null = null;
-    const responseChunks: unknown[] = [];
+    const responseChunks: Program[] = [];
     let respBytes = 0;
     while (true) {
       const { done, value } = await reader.read();
@@ -137,21 +140,21 @@ export async function* streamProvider(
           if (data === "[DONE]") {
             emitProviderUsage(
               providerCtx,
+              resolvedRequest,
               lastChunkWithUsage,
               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),
           );
+          responseChunks.push(chunk);
           if (usageObject(chunk) !== undefined) lastChunkWithUsage = chunk;
           yield chunk;
         }
@@ -163,32 +166,32 @@ export async function* streamProvider(
         if (data === "[DONE]") {
           emitProviderUsage(
             providerCtx,
+            resolvedRequest,
             lastChunkWithUsage,
             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),
         );
+        responseChunks.push(chunk);
         if (usageObject(chunk) !== undefined) lastChunkWithUsage = chunk;
         yield chunk;
       }
     }
     emitProviderUsage(
       providerCtx,
+      resolvedRequest,
       lastChunkWithUsage,
       provider.name,
       reqBytes,
       respBytes,
-      jsonBody(reqBody),
       responseChunks,
     );
   } catch (error) {
@@ -199,11 +202,3 @@ 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,6 +1,11 @@
 import { usageObject, type Program } from "@neutrome/lil-engine";
 import { createExecutionEvent } from "@neutrome/lilsdk";
 import { z } from "zod";
+import {
+  normalizeChatRequest,
+  normalizeChatResponse,
+  normalizeChatStream,
+} from "../telemetry/chat-normalization.ts";
 import type { ProviderInvocationContext } from "./execution-types.ts";
 
 const encoder = new TextEncoder();
@@ -9,12 +14,12 @@ const TokenCountSchema = z.number().finite().nonnegative();
 
 export function emitProviderUsage(
   providerCtx: ProviderInvocationContext,
+  request: Program,
   response: Program | null,
   provider: string,
   requestBytes: number,
   responseBytes: number,
-  input?: unknown,
-  output?: unknown,
+  streamChunks?: readonly Program[],
 ): void {
   const usage = response ? usageObject(response) : undefined;
   const u = (usage && typeof usage === "object" ? usage : {}) as Record<
@@ -43,8 +48,12 @@ export function emitProviderUsage(
         cachedTokensInput,
         requestBytes,
         responseBytes,
-        ...(input === undefined ? {} : { input }),
-        ...(output === undefined ? {} : { output }),
+        input: normalizeChatRequest(request),
+        output: streamChunks
+          ? normalizeChatStream(streamChunks)
+          : response
+            ? normalizeChatResponse(response)
+            : undefined,
       },
     }),
   );

package/src/telemetry/chat-normalization.ts

@@ -0,0 +1,108 @@
+import {
+  decodeStreamToolDelta,
+  emitChatCompletionsRequest,
+  emitChatCompletionsResponse,
+  type Program,
+  Opcode,
+  usageObject,
+} from "@neutrome/lil-engine";
+
+const decoder = new TextDecoder();
+
+/** The trace wire format is always a non-streaming Chat Completions payload. */
+export function normalizeChatRequest(
+  program: Program,
+): Record<string, unknown> {
+  const request = json(emitChatCompletionsRequest(program));
+  delete request.stream;
+  return request;
+}
+
+export function normalizeChatResponse(
+  program: Program,
+): Record<string, unknown> {
+  return json(emitChatCompletionsResponse(program));
+}
+
+export function normalizeChatStream(
+  chunks: readonly Program[],
+): Record<string, unknown> {
+  const content: string[] = [];
+  const reasoning: string[] = [];
+  const tools = new Map<
+    number,
+    { id?: string; name?: string; arguments: string }
+  >();
+  let id: string | undefined;
+  let model: string | undefined;
+  let finishReason = "stop";
+  let usage: unknown;
+
+  for (const chunk of chunks) {
+    const chunkUsage = usageObject(chunk);
+    if (chunkUsage !== undefined) usage = chunkUsage;
+    for (const instruction of chunk.code) {
+      if (
+        instruction.opcode === Opcode.RESP_ID &&
+        instruction.value.kind === "string"
+      )
+        id = instruction.value.value;
+      if (
+        instruction.opcode === Opcode.RESP_MODEL &&
+        instruction.value.kind === "string"
+      )
+        model = instruction.value.value;
+      if (
+        instruction.opcode === Opcode.RESP_DONE &&
+        instruction.value.kind === "string"
+      )
+        finishReason = instruction.value.value;
+      if (
+        instruction.opcode === Opcode.STREAM_DELTA &&
+        instruction.value.kind === "string"
+      )
+        content.push(instruction.value.value);
+      if (
+        instruction.opcode === Opcode.STREAM_THINK_DELTA &&
+        instruction.value.kind === "string"
+      )
+        reasoning.push(instruction.value.value);
+      if (instruction.opcode !== Opcode.STREAM_TOOL_DELTA) continue;
+      const delta = decodeStreamToolDelta(instruction);
+      if (!delta) continue;
+      const tool = tools.get(delta.index) ?? { arguments: "" };
+      if (delta.id !== undefined) tool.id = delta.id;
+      if (delta.name !== undefined) tool.name = delta.name;
+      if (delta.arguments !== undefined) tool.arguments += delta.arguments;
+      tools.set(delta.index, tool);
+    }
+  }
+
+  const message: Record<string, unknown> = {
+    role: "assistant",
+    content: content.join("") || null,
+  };
+  if (reasoning.length > 0) message.reasoning_content = reasoning.join("");
+  if (tools.size > 0) {
+    message.tool_calls = [...tools.entries()].map(([index, tool]) => ({
+      index,
+      ...(tool.id ? { id: tool.id } : {}),
+      type: "function",
+      function: {
+        ...(tool.name ? { name: tool.name } : {}),
+        arguments: tool.arguments,
+      },
+    }));
+  }
+  return {
+    object: "chat.completion",
+    ...(id ? { id } : {}),
+    ...(model ? { model } : {}),
+    choices: [{ index: 0, message, finish_reason: finishReason }],
+    ...(usage === undefined ? {} : { usage }),
+  };
+}
+
+function json(bytes: Uint8Array): Record<string, unknown> {
+  return JSON.parse(decoder.decode(bytes)) as Record<string, unknown>;
+}

package/src/telemetry/index.ts

@@ -11,3 +11,4 @@ export type {
   ExecutionSummarySpan,
   RouterTelemetry,
 } from "./router.ts";
+export type { ExecutionTimelineEvent } from "./timeline.ts";

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;
+}