@neutrome/open-ai-router 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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.1"
+    "@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/provider-invoker.ts

@@ -108,12 +108,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 +133,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

@@ -102,7 +102,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 +137,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 +163,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 +199,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/router.ts

@@ -1,6 +1,19 @@
 import type { ExecutionEvent } from "@neutrome/lilsdk";
-import { z } from "zod";
 import { createPosthogTelemetryDrivers } from "./posthog.ts";
+import {
+  appendEvent,
+  createSpan,
+  elapsed,
+  eventData,
+  failSpan,
+  finishSpan,
+  isInvocationFinished,
+  isInvocationStarted,
+  mergeSpan,
+  setUsage,
+  type ExecutionSummary,
+  type ExecutionSummarySpan,
+} from "./timeline.ts";
 import type {
   ErrorTelemetryDriver,
   TelemetryError,
@@ -8,36 +21,7 @@ import type {
   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 { ExecutionSummary, ExecutionSummarySpan } from "./timeline.ts";
 
 export type RouterTelemetry = {
   observe(event: ExecutionEvent): void;
@@ -48,29 +32,9 @@ export type RouterTelemetry = {
 
 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>;
@@ -86,238 +50,153 @@ export function createRouterTelemetry(
   });
   const traceDriver = input.traceDriver ?? drivers.traceDriver;
   const errorDriver = input.errorDriver ?? drivers.errorDriver;
-  const traceId = crypto.randomUUID().replaceAll("-", "");
+  const spanId = crypto.randomUUID().replaceAll("-", "");
   const startedAt = new Date().toISOString();
   const spans: ExecutionSummarySpan[] = [];
-  const activeSpans = new Map<string, ActiveSpan>();
-  const providerGenerations: ActiveSpan[] = [];
+  const active = new Map<string, ActiveSpan>();
+  const generations: ActiveSpan[] = [];
   const errors = new Map<string, TelemetryError>();
-  let error: string | undefined;
+  let traceError: string | undefined;
+  let finalizedAt: string | undefined;
+  let flushed = false;
 
   return { observe, recordError, flush, summary };
 
   function observe(event: ExecutionEvent): void {
-    const timing = eventTiming(event);
+    const data = eventData(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);
+      const summary = createSpan(event, data.startedAt ?? event.timestamp);
+      const span = { summary };
+      spans.push(summary);
+      active.set(event.executionId, span);
+      appendEvent(summary, event, data);
       return;
     }
+    const span = active.get(event.executionId);
+    if (!span) return observeDetached(event, data);
+
+    appendEvent(span.summary, event, data);
+    mergeSpan(span.summary, data);
+    if (event.kind === "provider.usage") setUsage(span.summary, data);
+    if (event.kind === "provider.stream_first_byte")
+      span.timeToFirstTokenMs = elapsed(
+        span.summary.startedAt,
+        event.timestamp,
+      );
     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;
-      }
+      const message = data.message ?? "Execution failed";
+      failSpan(span.summary, message, event.timestamp);
       recordError({
         message,
         requestId: event.requestId,
         executionId: event.executionId,
       });
+    }
+    if (!isInvocationFinished(event.kind)) return;
+    finishSpan(span.summary, data.finishedAt ?? event.timestamp);
+    active.delete(event.executionId);
+    if (span.summary.kind === "provider") generations.push(span);
+  }
+
+  function observeDetached(
+    event: ExecutionEvent,
+    data: ReturnType<typeof eventData>,
+  ): void {
+    if (event.kind === "execution.failed") {
+      recordError({
+        message: data.message ?? "Execution failed",
+        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);
+    if (event.kind !== "tool.executed" && !data.startedAt) return;
+    const summary = createSpan(event, data.startedAt ?? event.timestamp);
+    finishSpan(summary, data.finishedAt ?? event.timestamp);
+    appendEvent(summary, event, data);
+    spans.push(summary);
   }
 
   function recordError(input: Omit<TelemetryError, "traceId">): void {
-    error ??= input.message;
-    const telemetryError = { ...input, traceId };
+    traceError ??= input.message;
+    const error = { ...input, traceId: spanId };
     errors.set(
-      `${telemetryError.requestId}:${telemetryError.executionId}:${telemetryError.message}`,
-      telemetryError,
+      `${error.requestId}:${error.executionId}:${error.message}`,
+      error,
     );
   }
 
   async function flush(): Promise<void> {
-    const finishedAt = new Date().toISOString();
-    for (const active of activeSpans.values()) {
-      active.summary.finishedAt ??= finishedAt;
+    if (flushed) return;
+    flushed = true;
+    const finishedAt = finalizedAt ?? new Date().toISOString();
+    finalizedAt = finishedAt;
+    for (const span of active.values()) {
+      finishSpan(span.summary, finishedAt, "incomplete");
+      if (span.summary.kind === "provider") generations.push(span);
     }
-    const generations = [
-      ...providerGenerations,
-      ...[...activeSpans.values()].filter(
-        ({ summary }) => summary.kind === "provider",
-      ),
-    ].map(toGeneration);
-    activeSpans.clear();
+    active.clear();
     await reportAll([
-      ...generations.map((generation) =>
-        traceDriver?.recordGeneration(generation),
-      ),
-      ...[...errors.values()].map((telemetryError) =>
-        errorDriver?.recordError(telemetryError),
+      ...generations.map((span) =>
+        traceDriver?.recordGeneration(toGeneration(span)),
       ),
+      ...[...errors.values()].map((error) => errorDriver?.recordError(error)),
     ]);
   }
 
   function summary(): ExecutionSummary {
-    const finishedAt = new Date().toISOString();
+    const finishedAt = finalizedAt ?? new Date().toISOString();
     return {
-      spanId: traceId,
+      spanId,
       startedAt,
       finishedAt,
+      durationMs: elapsed(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 } : {}),
+      totalTokensInput: sum("tokensInput"),
+      totalTokensOutput: sum("tokensOutput"),
+      totalCachedTokensInput: sum("cachedTokensInput"),
+      ...(traceError ? { error: traceError } : {}),
     };
   }
 
-  function toGeneration(active: ActiveSpan): TraceGeneration {
-    const { summary } = active;
+  function sum(
+    field: "tokensInput" | "tokensOutput" | "cachedTokensInput",
+  ): number {
+    return spans.reduce((total, span) => total + span[field], 0);
+  }
+
+  function toGeneration(activeSpan: ActiveSpan): TraceGeneration {
+    const span = activeSpan.summary;
     return {
-      traceId,
-      requestId: summary.requestId,
-      executionId: summary.executionId,
-      ...(summary.parentExecutionId
-        ? { parentExecutionId: summary.parentExecutionId }
+      traceId: spanId,
+      requestId: span.requestId,
+      executionId: span.executionId,
+      ...(span.parentExecutionId
+        ? { parentExecutionId: span.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
+      provider: span.provider ?? "unknown",
+      ...(span.model ? { model: span.model } : {}),
+      startedAt: span.startedAt,
+      finishedAt: span.finishedAt ?? finalizedAt ?? new Date().toISOString(),
+      tokensInput: span.tokensInput,
+      tokensOutput: span.tokensOutput,
+      cachedTokensInput: span.cachedTokensInput,
+      requestBytes: span.requestBytes,
+      responseBytes: span.responseBytes,
+      ...(span.request ? { input: span.request } : {}),
+      ...(span.response ? { output: span.response } : {}),
+      ...(activeSpan.timeToFirstTokenMs === undefined
         ? {}
-        : { timeToFirstTokenMs: active.timeToFirstTokenMs }),
+        : { timeToFirstTokenMs: activeSpan.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);
-    }
+  for (const result of await Promise.allSettled(reports.filter(Boolean))) {
+    if (result.status === "rejected")
+      console.error("[telemetry] report 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/timeline.ts

@@ -0,0 +1,198 @@
+import type { ExecutionEvent } from "@neutrome/lilsdk";
+import { z } from "zod";
+
+export type ExecutionTimelineEvent = {
+  event: string;
+  at: string;
+  startedAt?: string;
+  finishedAt?: string;
+  durationMs?: number;
+  data?: Record<string, unknown>;
+};
+
+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;
+  durationMs?: number;
+  status: "ok" | "error" | "incomplete";
+  tokensInput: number;
+  tokensOutput: number;
+  cachedTokensInput: number;
+  requestBytes: number;
+  responseBytes: number;
+  request?: Record<string, unknown>;
+  response?: Record<string, unknown>;
+  error?: string;
+  timeline: ExecutionTimelineEvent[];
+};
+
+export type ExecutionSummary = {
+  spanId: string;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  spans: ExecutionSummarySpan[];
+  totalTokensInput: number;
+  totalTokensOutput: number;
+  totalCachedTokensInput: number;
+  error?: string;
+};
+
+export const EventDataSchema = z
+  .object({
+    startedAt: z.string().min(1).optional(),
+    finishedAt: z.string().min(1).optional(),
+    durationMs: z.number().finite().nonnegative().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(),
+    input: z.record(z.string(), z.unknown()).optional(),
+    output: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+export type EventData = z.infer<typeof EventDataSchema>;
+
+export function eventData(event: ExecutionEvent): EventData {
+  const parsed = EventDataSchema.safeParse(event.data ?? {});
+  return parsed.success ? parsed.data : {};
+}
+
+export 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 }
+      : {}),
+    ...details(eventData(event)),
+    startedAt,
+    status: "incomplete",
+    tokensInput: 0,
+    tokensOutput: 0,
+    cachedTokensInput: 0,
+    requestBytes: 0,
+    responseBytes: 0,
+    timeline: [],
+  };
+}
+
+export function appendEvent(
+  span: ExecutionSummarySpan,
+  event: ExecutionEvent,
+  data: EventData,
+): void {
+  span.timeline.push({
+    event: event.kind,
+    at: event.timestamp,
+    ...(data.startedAt ? { startedAt: data.startedAt } : {}),
+    ...(data.finishedAt ? { finishedAt: data.finishedAt } : {}),
+    ...(data.durationMs === undefined ? {} : { durationMs: data.durationMs }),
+    ...(Object.keys(data).length ? { data: scrub(data) } : {}),
+  });
+}
+
+export function mergeSpan(span: ExecutionSummarySpan, data: EventData): void {
+  Object.assign(span, details(data));
+  if (data.tokensInput !== undefined) span.tokensInput = data.tokensInput;
+  if (data.tokensOutput !== undefined) span.tokensOutput = data.tokensOutput;
+  if (data.cachedTokensInput !== undefined)
+    span.cachedTokensInput = data.cachedTokensInput;
+  if (data.requestBytes !== undefined) span.requestBytes = data.requestBytes;
+  if (data.responseBytes !== undefined) span.responseBytes = data.responseBytes;
+  if (data.input) span.request = data.input;
+  if (data.output) span.response = data.output;
+}
+
+export function setUsage(span: ExecutionSummarySpan, data: EventData): void {
+  span.tokensInput = data.tokensInput ?? 0;
+  span.tokensOutput = data.tokensOutput ?? 0;
+  span.cachedTokensInput = data.cachedTokensInput ?? 0;
+  span.requestBytes = data.requestBytes ?? 0;
+  span.responseBytes = data.responseBytes ?? 0;
+  if (data.input) span.request = data.input;
+  if (data.output) span.response = data.output;
+}
+
+export function finishSpan(
+  span: ExecutionSummarySpan,
+  finishedAt: string,
+  status: ExecutionSummarySpan["status"] = "ok",
+): void {
+  span.finishedAt = finishedAt;
+  span.durationMs = elapsed(span.startedAt, finishedAt);
+  if (span.status !== "error") span.status = status;
+}
+
+export function failSpan(
+  span: ExecutionSummarySpan,
+  message: string,
+  at: string,
+): void {
+  span.error = message;
+  span.status = "error";
+  finishSpan(span, span.finishedAt ?? at, "error");
+}
+
+export function elapsed(startedAt: string, finishedAt: string): number {
+  return Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt));
+}
+
+export function isInvocationStarted(kind: string): boolean {
+  return kind.endsWith(".started") || kind.endsWith(".stream_started");
+}
+
+export function isInvocationFinished(kind: string): boolean {
+  return kind.endsWith(".finished") || kind.endsWith(".stream_finished");
+}
+
+function scrub(data: EventData): Record<string, unknown> {
+  const {
+    input: _input,
+    output: _output,
+    startedAt: _start,
+    finishedAt: _end,
+    durationMs: _duration,
+    ...rest
+  } = data;
+  return rest;
+}
+
+function details(data: EventData): Partial<ExecutionSummarySpan> {
+  const executor = data.executor ?? data.executorId;
+  return {
+    ...(data.model ? { model: data.model } : {}),
+    ...(data.provider ? { provider: data.provider } : {}),
+    ...(data.toolName ? { toolName: data.toolName } : {}),
+    ...(executor ? { executor } : {}),
+  };
+}
+
+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";
+}

package/src/telemetry.test.ts

@@ -1,10 +1,12 @@
 import { createExecutionEvent } from "@neutrome/lilsdk";
+import { streamEnd, streamStart, streamTextDelta } from "@neutrome/lil-engine";
 import { describe, expect, it, vi } from "vitest";
 import {
   createRouterTelemetry,
   PosthogErrorTelemetry,
   PosthogTraceTelemetry,
 } from "./telemetry/index.ts";
+import { normalizeChatStream } from "./telemetry/chat-normalization.ts";
 
 describe("createRouterTelemetry", () => {
   it("reports provider generations and exceptions through separate drivers", async () => {
@@ -65,6 +67,83 @@ describe("createRouterTelemetry", () => {
     expect(errorDriver.recordError).toHaveBeenCalledWith(
       expect.objectContaining({ message: "tool unavailable" }),
     );
+    expect(telemetry.summary().spans[0]).toMatchObject({
+      status: "ok",
+      durationMs: 1000,
+      request: { messages: [{ role: "user", content: "hello" }] },
+      timeline: expect.arrayContaining([
+        expect.objectContaining({ event: "provider.usage" }),
+      ]),
+    });
+  });
+
+  it("converts streamed programs into one non-streaming chat completion", async () => {
+    const telemetry = createRouterTelemetry();
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "provider.stream_started",
+        requestId: "request-1",
+        executionId: "provider-1",
+        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: {
+          input: {
+            model: "gpt-5-chat",
+            messages: [{ role: "user", content: "hello" }],
+          },
+          output: {
+            object: "chat.completion",
+            choices: [{ message: { role: "assistant", content: "hello" } }],
+          },
+        },
+      }),
+    );
+    telemetry.observe(
+      createExecutionEvent({
+        kind: "provider.stream_finished",
+        requestId: "request-1",
+        executionId: "provider-1",
+        data: { finishedAt: "2026-07-13T12:00:01.000Z" },
+      }),
+    );
+
+    expect(telemetry.summary().spans[0]).toMatchObject({
+      request: { model: "gpt-5-chat" },
+      response: { object: "chat.completion" },
+      status: "ok",
+    });
+  });
+});
+
+describe("trace chat normalization", () => {
+  it("concatenates stream chunks into a chat completion response", () => {
+    expect(
+      normalizeChatStream([
+        streamStart(),
+        streamTextDelta("hello "),
+        streamTextDelta("world"),
+        streamEnd("length"),
+      ]),
+    ).toEqual({
+      object: "chat.completion",
+      choices: [
+        {
+          index: 0,
+          message: { role: "assistant", content: "hello world" },
+          finish_reason: "length",
+        },
+      ],
+    });
   });
 });