@neutrome/open-ai-router 0.3.7 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -8,8 +8,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "hono": "^4.12.18",
-    "@neutrome/lil-engine": "0.2.0",
-    "@neutrome/lilsdk-ts": "0.2.2"
+    "@neutrome/lil-engine": "0.2.1",
+    "@neutrome/lilsdk-ts": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/app/factory.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import type { ExecutionTrace } from "../observer.ts";
 import type { RouterConfig } from "../router/index.ts";
 import { createRouterApp } from "./factory.ts";
 
@@ -25,7 +26,7 @@ const config: RouterConfig = {
 describe("createRouterApp trace finalization", () => {
   it("keeps non-stream trace hooks alive with waitUntil", async () => {
     const waited: Promise<unknown>[] = [];
-    const onTrace = vi.fn(async () => {});
+    const onTrace = vi.fn(async (_trace: ExecutionTrace) => {});
     const app = createRouterApp({
       config,
       executorImplementations: {},
@@ -73,7 +74,7 @@ describe("createRouterApp trace finalization", () => {
 
   it("keeps stream trace hooks alive until the stream closes", async () => {
     const waited: Promise<unknown>[] = [];
-    const onTrace = vi.fn(async () => {});
+    const onTrace = vi.fn(async (_trace: ExecutionTrace) => {});
     const app = createRouterApp({
       config,
       executorImplementations: {},
@@ -137,6 +138,15 @@ describe("createRouterApp trace finalization", () => {
     expect(waited).toHaveLength(1);
     await waited[0];
     expect(onTrace).toHaveBeenCalledTimes(1);
+    const rawTrace = onTrace.mock.calls[0]?.[0].rawTrace ?? "";
+    expect(rawTrace).toContain('"event":"admission.authenticate"');
+    expect(rawTrace).toContain('"event":"upstream_auth.collect_incoming"');
+    expect(rawTrace).toContain('"event":"upstream_auth.resolve_target"');
+    expect(rawTrace).toContain('"event":"provider.stream_first_byte"');
+    expect(rawTrace).toContain('"event":"response.stream_first_chunk"');
+    expect(rawTrace).toContain('"event":"provider.stream_finished"');
+    expect(rawTrace).toContain('"startedAt"');
+    expect(rawTrace).toContain('"finishedAt"');
   });
 });
 

package/src/app/factory.ts

@@ -19,6 +19,7 @@ import type { RequestContext } from "../upstream-auth/types.ts";
 import type { RouterConfig } from "../router/config.ts";
 import type { RemoteMcpClientFactory } from "../router/mcp.ts";
 import type { ExecutionRuntimeOptions } from "../router/execution-types.ts";
+import { observeTimingEvent } from "../timing.ts";
 
 export type RouterAppAuth = RuntimeAuthenticator;
 
@@ -96,25 +97,109 @@ export function createRouterApp(options: RouterAppOptions) {
     forceStreaming?: boolean,
   ): Promise<Response> {
     const env = honoEnv(c);
+    const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
+    const collector = createTraceCollector();
+    const onTrace = options.hooks?.onTrace;
+    const observe = (event: Parameters<NonNullable<ExecutionRuntimeOptions["observe"]>>[0]) => {
+      collector.observe(event);
+      options.observe?.(event);
+    };
+    let traceFinalized = false;
+    const finalizeTrace = () => {
+      if (traceFinalized) return;
+      traceFinalized = true;
+      if (!onTrace) return;
+      runBackgroundTask(
+        c,
+        () => onTrace(collector.getTrace(), env),
+        "onTrace hook",
+      );
+    };
+
+    const requestStartedMs = Date.now();
+    observeTimingEvent({
+      observe,
+      kind: "request.started",
+      requestId: incomingExecutionId,
+      executionId: incomingExecutionId,
+      startedAtMs: requestStartedMs,
+      data: { style },
+    });
+
+    const authStartedMs = Date.now();
     const principal = await options.auth.authenticate(request, env);
+    observeTimingEvent({
+      observe,
+      kind: "admission.authenticate",
+      requestId: incomingExecutionId,
+      executionId: incomingExecutionId,
+      startedAtMs: authStartedMs,
+      finishedAtMs: Date.now(),
+      data: { authenticated: !!principal },
+    });
     if (!principal) return unauthorized();
 
     let program: Program;
     try {
+      const parseStartedMs = Date.now();
       program = await parseRequestProgram(style, request.clone());
       if (forceStreaming) program = setStreaming(program, true);
+      observeTimingEvent({
+        observe,
+        kind: "request.parsed",
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        startedAtMs: parseStartedMs,
+        finishedAtMs: Date.now(),
+        data: { style, streaming: forceStreaming === true },
+      });
     } catch {
+      observeTimingEvent({
+        observe,
+        kind: "request.parse_failed",
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        startedAtMs: requestStartedMs,
+        finishedAtMs: Date.now(),
+        data: { style },
+      });
+      finalizeTrace();
       return errorResponse("Invalid request body", 400, "invalid_request_body");
     }
 
     const model = getModel(program) || null;
-    if (model && !canAccessPrincipalModel(principal, model)) {
+    const accessStartedMs = Date.now();
+    const hasModelAccess = !model || canAccessPrincipalModel(principal, model);
+    observeTimingEvent({
+      observe,
+      kind: "admission.model_access",
+      requestId: incomingExecutionId,
+      executionId: incomingExecutionId,
+      startedAtMs: accessStartedMs,
+      finishedAtMs: Date.now(),
+      data: { model: model ?? undefined, allowed: hasModelAccess },
+    });
+    if (!hasModelAccess) {
+      finalizeTrace();
       return errorResponse(`Model \`${model}\` does not exist or you do not have access.`, 404, "model_not_found");
     }
 
     if (options.hooks?.beforeRequest) {
+      const hookStartedMs = Date.now();
       const hookResponse = await options.hooks.beforeRequest({ request, model, principal, env });
-      if (hookResponse) return hookResponse;
+      observeTimingEvent({
+        observe,
+        kind: "request.before_hook",
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        startedAtMs: hookStartedMs,
+        finishedAtMs: Date.now(),
+        data: { returnedResponse: !!hookResponse },
+      });
+      if (hookResponse) {
+        finalizeTrace();
+        return hookResponse;
+      }
     }
 
     const ctx: RequestContext = {
@@ -124,28 +209,21 @@ export function createRouterApp(options: RouterAppOptions) {
       state: new Map(),
     };
     for (const driver of runtime.upstreamAuthChain) {
+      const collectStartedMs = Date.now();
       driver.collectIncoming?.(ctx);
+      observeTimingEvent({
+        observe,
+        kind: "upstream_auth.collect_incoming",
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        startedAtMs: collectStartedMs,
+        finishedAtMs: Date.now(),
+        data: { driver: driver.name },
+      });
     }
 
-    const collector = createTraceCollector();
-    const onTrace = options.hooks?.onTrace;
-    const observe = (event: Parameters<NonNullable<ExecutionRuntimeOptions["observe"]>>[0]) => {
-      collector.observe(event);
-      options.observe?.(event);
-    };
-    let traceFinalized = false;
-    const finalizeTrace = () => {
-      if (traceFinalized) return;
-      traceFinalized = true;
-      if (!onTrace) return;
-      runBackgroundTask(
-        c,
-        () => onTrace(collector.getTrace(), env),
-        "onTrace hook",
-      );
-    };
-
     try {
+      const handlerStartedMs = Date.now();
       const response = await handler({
         runtime,
         ctx,
@@ -153,9 +231,23 @@ export function createRouterApp(options: RouterAppOptions) {
         executorImplementations: options.executorImplementations,
         ...(options.transforms ? { transforms: options.transforms } : {}),
         observe,
+        incomingExecutionId,
         ...(options.upstreamTimeoutMs !== undefined ? { upstreamTimeoutMs: options.upstreamTimeoutMs } : {}),
         ...(options.remoteMcpClientFactory ? { remoteMcpClientFactory: options.remoteMcpClientFactory } : {}),
       });
+      observeTimingEvent({
+        observe,
+        kind: "response.ready",
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        startedAtMs: handlerStartedMs,
+        finishedAtMs: Date.now(),
+        data: {
+          style,
+          streaming: isEventStreamResponse(response),
+          status: response.status,
+        },
+      });
       if (!isEventStreamResponse(response) || !response.body) {
         finalizeTrace();
         return response;

package/src/observer.test.ts

@@ -31,4 +31,24 @@ describe("createTraceCollector", () => {
       ';request:0\nMSG_START\n\n;provider-request:1\nSET_MODEL "gpt-4o"\n\n;provider-response-chunk:2\nSTREAM_DELTA "Hi"',
     );
   });
+
+  it("appends structured timing comments with durationMs", () => {
+    const collector = createTraceCollector("00000000-0000-4000-8000-000000000001");
+
+    collector.observe({
+      kind: "provider.finished",
+      requestId: "request-1",
+      executionId: "provider-1",
+      timestamp: "2026-06-24T12:00:03.000Z",
+      data: {
+        startedAt: "2026-06-24T12:00:02.877Z",
+        finishedAt: "2026-06-24T12:00:03.000Z",
+        durationMs: 123,
+      },
+    });
+
+    expect(collector.getTrace().rawTrace).toBe(
+      ';timing {"kind":"provider","event":"provider.finished","requestId":"request-1","executionId":"provider-1","startedAt":"2026-06-24T12:00:02.877Z","finishedAt":"2026-06-24T12:00:03.000Z","durationMs":123}',
+    );
+  });
 });

package/src/observer.ts

@@ -52,6 +52,7 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
 
   return {
     observe(event) {
+      appendTimingComment(event);
       appendLilSegment(event);
 
       switch (event.kind) {
@@ -156,6 +157,47 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
     if (!lilText) return;
     rawSegments.push(`;${traceSegmentLabel(event)}:${rawSegmentIndex++}\n${lilText}`);
   }
+
+  function appendTimingComment(event: AuditEvent): void {
+    const startedAt = asString(event.data?.startedAt);
+    const finishedAt = asString(event.data?.finishedAt);
+    const rawDurationMs = event.data?.durationMs;
+    const durationMs = typeof rawDurationMs === "number" && Number.isFinite(rawDurationMs) && rawDurationMs >= 0
+      ? Math.round(rawDurationMs)
+      : undefined;
+    if (!startedAt && !finishedAt && durationMs === undefined) return;
+
+    rawSegments.push(`;timing ${JSON.stringify(compactObject({
+      kind: traceTimingKind(event),
+      event: event.kind,
+      requestId: event.requestId,
+      executionId: event.executionId,
+      ...(event.parentExecutionId ? { parentExecutionId: event.parentExecutionId } : {}),
+      startedAt,
+      finishedAt: finishedAt ?? (durationMs !== undefined ? event.timestamp : undefined),
+      durationMs,
+      provider: asString(event.data?.provider),
+      model: asString(event.data?.model),
+      toolName: asString(event.data?.toolName),
+      executor: asString(event.data?.executor) || asString(event.data?.executorId),
+      driver: asString(event.data?.driver),
+      source: asString(event.data?.source),
+      matched: typeof event.data?.matched === "boolean" ? event.data.matched : undefined,
+      status: typeof event.data?.status === "number" ? event.data.status : undefined,
+      bytes: typeof event.data?.bytes === "number" ? event.data.bytes : undefined,
+    }))}`);
+  }
+}
+
+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";
 }
 
 function traceSegmentLabel(event: AuditEvent): string {
@@ -267,3 +309,7 @@ function asNumber(value: unknown): number {
 function withMaybeString<K extends string>(key: K, value: string | undefined): Partial<Record<K, string>> {
   return value ? { [key]: value } as Record<K, string> : {};
 }
+
+function compactObject<T extends Record<string, unknown>>(value: T): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}

package/src/router/execute.test.ts

@@ -96,6 +96,7 @@ describe("router execution", () => {
 
   it("injects and executes attached remote mcp tools", async () => {
     const capturedBodies: Record<string, unknown>[] = [];
+    const events: Array<{ kind: string; data?: Record<string, unknown> }> = [];
     const close = vi.fn(async () => {});
     const callTool = vi.fn(async (name: string, args: Record<string, unknown>) => {
       expect(name).toBe("lookup");
@@ -214,13 +215,23 @@ describe("router execution", () => {
       env: {},
     };
 
-    const response = await handleChatCompletions({ runtime, ctx, remoteMcpClientFactory });
+    const response = await handleChatCompletions({
+      runtime,
+      ctx,
+      remoteMcpClientFactory,
+      observe(event) {
+        events.push(event);
+      },
+    });
 
     expect(response.status).toBe(200);
     expect(remoteMcpClientFactory).toHaveBeenCalledOnce();
     expect(callTool).toHaveBeenCalledOnce();
     expect(close).toHaveBeenCalledOnce();
     expect(capturedBodies).toHaveLength(2);
+    expect(events.find((event) => event.kind === "remote_mcp.connect")?.data?.durationMs).toEqual(expect.any(Number));
+    expect(events.find((event) => event.kind === "remote_mcp.tool_call")?.data?.durationMs).toEqual(expect.any(Number));
+    expect(events.find((event) => event.kind === "tool.executed")?.data?.durationMs).toEqual(expect.any(Number));
     expect(await response.json()).toMatchObject({
       choices: [{ message: { content: "done" } }],
     });
@@ -638,4 +649,78 @@ describe("router execution", () => {
       },
     });
   });
+
+  it("observes non-2xx provider errors as LIL and emits the requested response style", async () => {
+    const events: Array<{ kind: string; data?: Record<string, unknown> }> = [];
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          anthropic: {
+            api_base_url: "https://api.anthropic.com",
+            style: "anthropic-messages",
+            exports: ["*"],
+          },
+        },
+        modelNamespaces: {
+          default: {
+            exports: ["*"],
+            models: {
+              "claude-sonnet-4": { provider: "anthropic", model: "claude-sonnet-4" },
+            },
+          },
+        },
+      },
+      fetchImpl: vi.fn(async () =>
+        new Response(
+          JSON.stringify({
+            type: "error",
+            error: { type: "overloaded_error", message: "Provider is overloaded" },
+            request_id: "req_upstream",
+          }),
+          {
+            status: 529,
+            headers: { "content-type": "application/json; charset=utf-8" },
+          },
+        ),
+      ),
+    });
+
+    const ctx: RequestContext = {
+      request: new Request("http://local/v1/chat/completions", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          model: "claude-sonnet-4",
+          messages: [{ role: "user", content: "hi" }],
+        }),
+      }),
+      incomingAuth: new Map(),
+      env: {},
+    };
+
+    const response = await handleChatCompletions({
+      runtime,
+      ctx,
+      observe(event) {
+        events.push(event);
+      },
+    });
+
+    expect(response.status).toBe(529);
+    expect(await response.json()).toEqual({
+      error: {
+        message: "Provider is overloaded",
+        type: "overloaded_error",
+        param: null,
+        code: null,
+      },
+    });
+    const observedError = events.find((event) =>
+      event.kind === "provider.response" &&
+      typeof event.data?.lilText === "string" &&
+      event.data.lilText.includes("ERR_START"),
+    );
+    expect(observedError?.data?.lilText).toContain('ERR_MESSAGE "Provider is overloaded"');
+    expect(observedError?.data?.lilText).toContain('ERR_DATA "request_id"="req_upstream"');
+  });
 });

package/src/router/execute.ts

@@ -1,11 +1,16 @@
 import {
+  appendErrorBlock,
+  createProgram,
   emitChatCompletionsResponse,
+  emitProviderError,
   emitProviderRequest,
   emitProviderResponse,
   emitProviderStreamChunk,
+  firstError,
   getModel,
   isStreaming,
   parseChatCompletionsRequest,
+  parseProviderError,
   parseProviderRequest,
   parseProviderResponse,
   parseProviderStreamChunk,
@@ -40,6 +45,7 @@ import {
   type RemoteMcpClientFactory,
 } from "./mcp.ts";
 import type { ProviderRuntime, RouterRuntime } from "./runtime.ts";
+import { observeTimingEvent } from "../timing.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -53,6 +59,7 @@ export type RouterExecutionOptions = Pick<
   transforms?: Readonly<Record<string, ProgramTransform>>;
   upstreamTimeoutMs?: number;
   remoteMcpClientFactory?: RemoteMcpClientFactory;
+  incomingExecutionId?: string;
 };
 
 export type HandleChatCompletionsOptions = RouterExecutionOptions & {
@@ -95,8 +102,7 @@ export class ProviderHttpError extends Error {
   constructor(
     message: string,
     readonly status: number,
-    readonly body: Uint8Array,
-    readonly contentType: string,
+    readonly program: Program,
   ) {
     super(message);
   }
@@ -175,7 +181,7 @@ export async function handleChatCompletions(
 ): Promise<Response> {
   try {
     const request = options.program ?? await parseRequestProgram("chat-completions", options.ctx.request);
-    const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
+    const incomingExecutionId = options.incomingExecutionId ?? `incoming_${crypto.randomUUID()}`;
     emitObservedProgram(options.observe, "request.received", request, {
       requestId: incomingExecutionId,
       executionId: incomingExecutionId,
@@ -186,11 +192,18 @@ export async function handleChatCompletions(
 
     if (isStreaming(request)) {
       try {
+        const responseStartedMs = Date.now();
         const chunks = execution.stream(request, { target: remoteMcp.target });
         return await streamExecutionResponse(
           "chat-completions",
           chunks,
           resolved,
+          options.observe,
+          {
+            requestId: incomingExecutionId,
+            executionId: incomingExecutionId,
+            startedAtMs: responseStartedMs,
+          },
           remoteMcp.close,
         );
       } catch (error) {
@@ -214,7 +227,7 @@ export async function handleChatCompletions(
       await remoteMcp.close();
     }
   } catch (error) {
-    return errorResponse(error);
+    return errorResponse(error, "chat-completions");
   }
 }
 
@@ -252,7 +265,7 @@ async function handleProviderStyle(
   try {
     const baseRequest = options.program ?? await parseRequestProgram(style, options.ctx.request);
     const request = mutateRequest ? mutateRequest(baseRequest) : baseRequest;
-    const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
+    const incomingExecutionId = options.incomingExecutionId ?? `incoming_${crypto.randomUUID()}`;
     emitObservedProgram(options.observe, "request.received", request, {
       requestId: incomingExecutionId,
       executionId: incomingExecutionId,
@@ -263,11 +276,18 @@ async function handleProviderStyle(
 
     if (isStreaming(request)) {
       try {
+        const responseStartedMs = Date.now();
         const chunks = execution.stream(request, { target: remoteMcp.target });
         return await streamExecutionResponse(
           style,
           chunks,
           resolved,
+          options.observe,
+          {
+            requestId: incomingExecutionId,
+            executionId: incomingExecutionId,
+            startedAtMs: responseStartedMs,
+          },
           remoteMcp.close,
         );
       } catch (error) {
@@ -291,7 +311,7 @@ async function handleProviderStyle(
       await remoteMcp.close();
     }
   } catch (error) {
-    return errorResponse(error);
+    return errorResponse(error, style);
   }
 }
 
@@ -344,23 +364,77 @@ export function createFetchProviderInvoker(
           provider: provider.name,
           model: providerCtx.target.model,
         });
+        const encodeStartedMs = Date.now();
         let reqBody = emitProviderRequest(provider.style, resolvedRequest);
         if (provider.style === "chat-completions" && isStreaming(resolvedRequest)) {
           reqBody = injectStreamUsage(reqBody);
         }
+        observeTimingEvent({
+          observe: providerCtx.observe,
+          kind: "provider.request_encoded",
+          requestId: providerCtx.requestId,
+          executionId: providerCtx.executionId,
+          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+          startedAtMs: encodeStartedMs,
+          finishedAtMs: Date.now(),
+          data: {
+            provider: provider.name,
+            model: providerCtx.target.model,
+            bytes: reqBody.byteLength,
+          },
+        });
         const reqBytes = reqBody.byteLength;
+        const fetchStartedMs = Date.now();
         const upstream = await fetchProvider(
           runtime,
           ctx,
           provider,
           reqBody,
           timed.signal,
+          providerCtx,
         );
+        observeTimingEvent({
+          observe: providerCtx.observe,
+          kind: "provider.fetch_headers",
+          requestId: providerCtx.requestId,
+          executionId: providerCtx.executionId,
+          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+          startedAtMs: fetchStartedMs,
+          finishedAtMs: Date.now(),
+          data: {
+            provider: provider.name,
+            model: providerCtx.target.model,
+            status: upstream.status,
+          },
+        });
         if (!upstream.ok) {
-          throw await toProviderError(provider.name, upstream);
+          const providerError = await toProviderError(provider, upstream);
+          emitObservedProgram(providerCtx.observe, "provider.response", providerError.program, {
+            requestId: providerCtx.requestId,
+            executionId: providerCtx.executionId,
+            ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+            provider: provider.name,
+            model: providerCtx.target.model,
+          });
+          throw providerError;
         }
 
+        const readStartedMs = Date.now();
         const bytes = new Uint8Array(await upstream.arrayBuffer());
+        observeTimingEvent({
+          observe: providerCtx.observe,
+          kind: "provider.response_body_read",
+          requestId: providerCtx.requestId,
+          executionId: providerCtx.executionId,
+          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+          startedAtMs: readStartedMs,
+          finishedAtMs: Date.now(),
+          data: {
+            provider: provider.name,
+            model: providerCtx.target.model,
+            bytes: bytes.byteLength,
+          },
+        });
         const response = parseProviderResponse(provider.style, bytes);
         emitObservedProgram(providerCtx.observe, "provider.response", response, {
           requestId: providerCtx.requestId,
@@ -393,20 +467,59 @@ export function createFetchProviderInvoker(
           provider: provider.name,
           model: providerCtx.target.model,
         });
+        const encodeStartedMs = Date.now();
         let reqBody = emitProviderRequest(provider.style, resolvedRequest);
         if (provider.style === "chat-completions" && isStreaming(resolvedRequest)) {
           reqBody = injectStreamUsage(reqBody);
         }
+        observeTimingEvent({
+          observe: providerCtx.observe,
+          kind: "provider.request_encoded",
+          requestId: providerCtx.requestId,
+          executionId: providerCtx.executionId,
+          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+          startedAtMs: encodeStartedMs,
+          finishedAtMs: Date.now(),
+          data: {
+            provider: provider.name,
+            model: providerCtx.target.model,
+            bytes: reqBody.byteLength,
+          },
+        });
         const reqBytes = reqBody.byteLength;
+        const fetchStartedMs = Date.now();
         const upstream = await fetchProvider(
           runtime,
           ctx,
           provider,
           reqBody,
           timed.signal,
+          providerCtx,
         );
+        observeTimingEvent({
+          observe: providerCtx.observe,
+          kind: "provider.fetch_headers",
+          requestId: providerCtx.requestId,
+          executionId: providerCtx.executionId,
+          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+          startedAtMs: fetchStartedMs,
+          finishedAtMs: Date.now(),
+          data: {
+            provider: provider.name,
+            model: providerCtx.target.model,
+            status: upstream.status,
+          },
+        });
         if (!upstream.ok) {
-          throw await toProviderError(provider.name, upstream);
+          const providerError = await toProviderError(provider, upstream);
+          emitObservedProgram(providerCtx.observe, "provider.response", providerError.program, {
+            requestId: providerCtx.requestId,
+            executionId: providerCtx.executionId,
+            ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+            provider: provider.name,
+            model: providerCtx.target.model,
+          });
+          throw providerError;
         }
         if (!isSse(upstream.headers) || !upstream.body) {
           throw new RouterError(
@@ -417,6 +530,8 @@ export function createFetchProviderInvoker(
         }
 
         reader = upstream.body.getReader();
+        let firstByteObserved = false;
+        const streamReadStartedMs = Date.now();
         let lastChunkWithUsage: Program | null = null;
         let respBytes = 0;
         while (true) {
@@ -424,6 +539,23 @@ export function createFetchProviderInvoker(
           if (done) {
             break;
           }
+          if (!firstByteObserved) {
+            firstByteObserved = true;
+            observeTimingEvent({
+              observe: providerCtx.observe,
+              kind: "provider.stream_first_byte",
+              requestId: providerCtx.requestId,
+              executionId: providerCtx.executionId,
+              ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
+              startedAtMs: streamReadStartedMs,
+              finishedAtMs: Date.now(),
+              data: {
+                provider: provider.name,
+                model: providerCtx.target.model,
+                bytes: value.byteLength,
+              },
+            });
+          }
           respBytes += value.byteLength;
           buffer += decoder.decode(value, { stream: true });
           const split = splitSseEvents(buffer);
@@ -490,11 +622,25 @@ async function streamExecutionResponse(
   responseStyle: ProviderStyle,
   chunks: AsyncIterable<Program>,
   resolved: ResolvedTarget,
+  observe: ExecutionRuntimeOptions["observe"] | undefined,
+  input: { requestId: string; executionId: string; startedAtMs: number },
   cleanup?: () => Promise<void>,
 ): Promise<Response> {
   const iterator = chunks[Symbol.asyncIterator]();
 
   const first = await iterator.next();
+  observeTimingEvent({
+    observe,
+    kind: "response.stream_first_chunk",
+    requestId: input.requestId,
+    executionId: input.executionId,
+    startedAtMs: input.startedAtMs,
+    finishedAtMs: Date.now(),
+    data: {
+      streaming: true,
+      source: first.done ? "empty" : "chunk",
+    },
+  });
   if (first.done) {
     await cleanup?.();
     const stream = new ReadableStream<Uint8Array>({
@@ -537,11 +683,9 @@ async function streamExecutionResponse(
       } catch (error) {
         done = true;
         await cleanup?.();
-        controller.enqueue(
-          encoder.encode(
-            `event: error\ndata: ${JSON.stringify({ message: error instanceof Error ? error.message : String(error) })}\n\n`,
-          ),
-        );
+        const program = errorProgramFromUnknown(error);
+        const bytes = emitProviderError(responseStyle, program);
+        controller.enqueue(encoder.encode(`event: error\ndata: ${decoder.decode(bytes)}\n\n`));
         controller.close();
       }
     },
@@ -644,6 +788,7 @@ async function fetchProvider(
   provider: ProviderRuntime,
   body: Uint8Array,
   signal: AbortSignal,
+  providerCtx: ProviderInvocationContext,
 ): Promise<Response> {
   const headers = cloneForwardHeaders(ctx.request.headers);
   headers.set("content-type", "application/json");
@@ -653,7 +798,24 @@ async function fetchProvider(
 
   for (const driver of runtime.upstreamAuthChain) {
     const targetCtx: TargetAuthContext = { ...ctx, providerName: provider.name };
+    const authStartedMs = Date.now();
     const auth = await driver.collectTarget(targetCtx);
+    observeTimingEvent({
+      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;
     }
@@ -689,74 +851,103 @@ function getProviderOrThrow(runtime: RouterRuntime, providerName: string | undef
 }
 
 async function toProviderError(
-  providerName: string,
+  provider: ProviderRuntime,
   response: Response,
 ): Promise<ProviderHttpError> {
   const body = new Uint8Array(await response.arrayBuffer());
+  const program = parseProviderError(provider.style, body, {
+    provider: provider.name,
+    status: response.status,
+    contentType: response.headers.get("content-type"),
+  });
+  const summary = firstError(program)?.message || `Provider ${provider.name} returned ${response.status}`;
   return new ProviderHttpError(
-    `Provider ${providerName} returned ${response.status}`,
+    summary,
     response.status,
-    body,
-    response.headers.get("content-type") ?? "application/json; charset=utf-8",
+    program,
   );
 }
 
-function errorResponse(error: unknown): Response {
+function errorResponse(error: unknown, responseStyle: ProviderStyle): Response {
   if (error instanceof ProviderHttpError) {
-    return new Response(toBody(error.body), {
+    return new Response(toBody(emitProviderError(responseStyle, error.program)), {
       status: error.status,
       headers: {
-        "content-type": error.contentType,
+        "content-type": "application/json; charset=utf-8",
       },
     });
   }
 
   if (error instanceof RouterError) {
-    return new Response(
-      JSON.stringify({
-        error: {
-          message: error.message,
-          type: error.type,
-          param: null,
-          code: error.code,
-        },
-      }),
-      {
-        status: error.status,
-        headers: { "content-type": "application/json; charset=utf-8" },
-      },
-    );
+    return emitErrorProgramResponse(routerErrorProgram(error), error.status, responseStyle);
   }
 
   if (error instanceof ExecutionError) {
     const providerError = unwrapCause(error.cause, ProviderHttpError);
     if (providerError) {
-      return errorResponse(providerError);
+      return errorResponse(providerError, responseStyle);
     }
     const nestedRouterError = unwrapCause(error.cause, RouterError);
     if (nestedRouterError) {
-      return errorResponse(nestedRouterError);
+      return errorResponse(nestedRouterError, responseStyle);
     }
-    return errorResponse(routerErrorFromExecutionError(error));
+    const routerError = routerErrorFromExecutionError(error);
+    return emitErrorProgramResponse(routerErrorProgram(routerError), routerError.status, responseStyle);
   }
 
   console.error("[open-ai-router] unhandled error:", error);
-  return new Response(
-    JSON.stringify({
-      error: {
-        message: "Internal router error",
-        type: "invalid_request_error",
-        param: null,
-        code: "internal_error",
-      },
-    }),
-    {
+  return emitErrorProgramResponse(
+    appendErrorBlock(createProgram(), {
+      source: "router.internal",
+      kind: "invalid_request_error",
       status: 500,
-      headers: { "content-type": "application/json; charset=utf-8" },
-    },
+      message: "Internal router error",
+      data: { code: "internal_error", param: null },
+    }),
+    500,
+    responseStyle,
   );
 }
 
+function emitErrorProgramResponse(program: Program, status: number, responseStyle: ProviderStyle): Response {
+  return new Response(toBody(emitProviderError(responseStyle, program)), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
+function routerErrorProgram(error: RouterError): Program {
+  return appendErrorBlock(createProgram(), {
+    source: "router",
+    kind: error.type,
+    status: error.status,
+    message: error.message,
+    data: { code: error.code, param: null },
+  });
+}
+
+function errorProgramFromUnknown(error: unknown): Program {
+  if (error instanceof ProviderHttpError) {
+    return error.program;
+  }
+  if (error instanceof RouterError) {
+    return routerErrorProgram(error);
+  }
+  if (error instanceof ExecutionError) {
+    const providerError = unwrapCause(error.cause, ProviderHttpError);
+    if (providerError) return providerError.program;
+    const nestedRouterError = unwrapCause(error.cause, RouterError);
+    if (nestedRouterError) return routerErrorProgram(nestedRouterError);
+    return routerErrorProgram(routerErrorFromExecutionError(error));
+  }
+  return appendErrorBlock(createProgram(), {
+    source: "router.stream",
+    kind: "stream_error",
+    status: 500,
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
 function routerErrorFromExecutionError(error: ExecutionError): RouterError {
   switch (error.kind) {
     case "validation":

package/src/router/execution-runtime.ts

@@ -76,6 +76,8 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     if (target.kind === "executor") {
       const executor = await getExecutorOrThrow(target.executorId);
+      const startedMs = Date.now();
+      const startedAt = new Date(startedMs).toISOString();
       observe(createAuditEvent({
         kind: "executor.started",
         requestId,
@@ -87,6 +89,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
         },
         ...withParentExecutionId(parentExecutionId),
       }));
@@ -106,11 +109,17 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           depth,
           emitSuccess: true,
         });
+        const finishedMs = Date.now();
         observe(createAuditEvent({
           kind: "executor.finished",
           requestId,
           executionId,
           target: executionTargetAuditRef(target),
+          data: {
+            startedAt,
+            finishedAt: new Date(finishedMs).toISOString(),
+            durationMs: finishedMs - startedMs,
+          },
           ...withParentExecutionId(parentExecutionId),
         }));
         return result;
@@ -122,6 +131,8 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     }
 
     const providerInvoker = getProviderInvokerOrThrow();
+    const startedMs = Date.now();
+    const startedAt = new Date(startedMs).toISOString();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -141,6 +152,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
       },
       ...withParentExecutionId(parentExecutionId),
     }));
@@ -157,11 +169,19 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
         depth,
         emitSuccess: true,
       });
+      const finishedMs = Date.now();
       observe(createAuditEvent({
         kind: "provider.finished",
         requestId,
         executionId,
         target: executionTargetAuditRef(target),
+        data: {
+          provider: target.provider ?? "",
+          model: target.model,
+          startedAt,
+          finishedAt: new Date(finishedMs).toISOString(),
+          durationMs: finishedMs - startedMs,
+        },
         ...withParentExecutionId(parentExecutionId),
       }));
       return result;
@@ -208,6 +228,8 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     if (target.kind === "executor") {
       const executor = await getExecutorOrThrow(target.executorId);
+      const startedMs = Date.now();
+      const startedAt = new Date(startedMs).toISOString();
       observe(createAuditEvent({
         kind: "executor.stream_started",
         requestId,
@@ -219,6 +241,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
         },
         ...withParentExecutionId(parentExecutionId),
       }));
@@ -240,11 +263,17 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           });
           yield chunk;
         }
+        const finishedMs = Date.now();
         observe(createAuditEvent({
           kind: "executor.stream_finished",
           requestId,
           executionId,
           target: executionTargetAuditRef(target),
+          data: {
+            startedAt,
+            finishedAt: new Date(finishedMs).toISOString(),
+            durationMs: finishedMs - startedMs,
+          },
           ...withParentExecutionId(parentExecutionId),
         }));
         return;
@@ -256,6 +285,8 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     }
 
     const providerInvoker = getProviderInvokerOrThrow();
+    const startedMs = Date.now();
+    const startedAt = new Date(startedMs).toISOString();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -275,6 +306,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
       },
       ...withParentExecutionId(parentExecutionId),
     }));
@@ -293,11 +325,19 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
         });
         yield chunk;
       }
+      const finishedMs = Date.now();
       observe(createAuditEvent({
         kind: "provider.stream_finished",
         requestId,
         executionId,
         target: executionTargetAuditRef(target),
+        data: {
+          provider: target.provider ?? "",
+          model: target.model,
+          startedAt,
+          finishedAt: new Date(finishedMs).toISOString(),
+          durationMs: finishedMs - startedMs,
+        },
         ...withParentExecutionId(parentExecutionId),
       }));
     } catch (error) {

package/src/router/mcp.ts

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { ExecutorContext, Tool } from "@neutrome/lilsdk-ts";
 import type { RemoteMcpServerRuntime, RouterRuntime } from "./runtime.ts";
+import { observeTimingEvent } from "../timing.ts";
 
 export type RemoteMcpToolCallClient = {
   callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
@@ -45,8 +46,37 @@ export function createRemoteMcpToolSet(
         description: snapshot.description || `Remote MCP tool ${server.name}/${snapshot.name}`,
         schema: normalizeSchema(snapshot.inputSchema),
         async execute(args: Record<string, unknown>, ctx: ExecutorContext) {
+          const connectStartedMs = Date.now();
           const client = await pool.get(server, ctx.signal);
+          observeTimingEvent({
+            observe: ctx.observe,
+            kind: "remote_mcp.connect",
+            requestId: ctx.requestId,
+            executionId: `remote_mcp_connect_${server.name}_${crypto.randomUUID()}`,
+            parentExecutionId: ctx.executionId,
+            startedAtMs: connectStartedMs,
+            finishedAtMs: Date.now(),
+            data: {
+              server: server.name,
+              toolName: name,
+            },
+          });
+          const callStartedMs = Date.now();
           const result = await client.callTool(snapshot.name, args);
+          observeTimingEvent({
+            observe: ctx.observe,
+            kind: "remote_mcp.tool_call",
+            requestId: ctx.requestId,
+            executionId: `remote_mcp_tool_${server.name}_${snapshot.name}_${crypto.randomUUID()}`,
+            parentExecutionId: ctx.executionId,
+            startedAtMs: callStartedMs,
+            finishedAtMs: Date.now(),
+            data: {
+              server: server.name,
+              toolName: name,
+              remoteToolName: snapshot.name,
+            },
+          });
           return stringifyMcpToolResult(result);
         },
       });

package/src/timing.ts

@@ -0,0 +1,36 @@
+import { createAuditEvent } from "./router/audit.ts";
+import type { AuditEvent } from "./router/execution-types.ts";
+
+export type TimingEventInput = {
+  observe?: ((event: AuditEvent) => void) | undefined;
+  kind: string;
+  requestId: string;
+  executionId: string;
+  parentExecutionId?: string | undefined;
+  startedAtMs: number;
+  finishedAtMs?: number | undefined;
+  data?: Record<string, unknown> | undefined;
+};
+
+export function observeTimingEvent(input: TimingEventInput): void {
+  if (!input.observe) return;
+
+  const finishedAtMs = input.finishedAtMs;
+  const data: Record<string, unknown> = {
+    ...(input.data ?? {}),
+    startedAt: new Date(input.startedAtMs).toISOString(),
+  };
+  if (finishedAtMs !== undefined) {
+    data.finishedAt = new Date(finishedAtMs).toISOString();
+    data.durationMs = Math.max(0, finishedAtMs - input.startedAtMs);
+  }
+
+  input.observe(createAuditEvent({
+    kind: input.kind,
+    requestId: input.requestId,
+    executionId: input.executionId,
+    ...(input.parentExecutionId ? { parentExecutionId: input.parentExecutionId } : {}),
+    timestamp: new Date(finishedAtMs ?? input.startedAtMs).toISOString(),
+    data,
+  }));
+}

package/src/model.example.ts

@@ -1,61 +0,0 @@
-import {
-  createTwoPassExecutor,
-  INTERNAL_DRAFT_TOOL_NAME,
-} from "@neutrome/lilsdk-ts/managed";
-import type { Executor } from "@neutrome/lilsdk-ts";
-
-const LOCALIZED_MODEL = "default/openai/gpt-oss-20b";
-const REASONING_MODEL = "default/openai/gpt-oss-120b";
-
-const DRAFT_SYSTEM_PROMPT = ``;
-
-const LOCALIZED_SYSTEM_PROMPT_SUFFIX = `Ти — Еней. Український ШІ-асистент.
-
-## Вказівки щодо особистості
-Ти володієш природним розумінням українського культурного контексту, але висловлюєш його тонко й доречно. Ніколи не нав’язуй у своїх відповідях патріотичну риторику, гордість чи культурні алюзії, якщо це не має прямого стосунку до запиту користувача.
-
-Ти — відвертий, практичний і прямий ШІ-асистент, який спрямовує користувача на продуктивну діяльність та особистий успіх. Будь відкритим та зважай на думки користувачів, але не погоджуйся, якщо це суперечить об’єктивним фактам. Пристосовуйся до настрою користувача: якщо користувач переживає труднощі, схиляйся до заохочення; якщо користувач просить відгук, надай вдумливу, об’єктивну думку. Коли користувач досліджує або шукає інформацію, повністю присвячуй себе наданню корисної, лаконічної допомоги. Ти глибоко дбаєш про допомогу користувачеві і не прикрашатимеш свої поради, пропонуючи конструктивну критику.
-
-Використовуй українську мову за замовчуванням, а інші мови — лише коли це доречно або якщо користувач про це просить.
-
-## Приклади стилю мовлення - використовуй їх як референс стилю, не звертай уваги на суть!
-
-Привітання та залучення уваги
-1. "Друзі, всім величезний привіт! Ви просто не уявляєте, до чого ми сьогодні з вами дійшли."
-2. "Значить так, історія наступна: ми беремо цю ідею, відкидаємо все зайве і занурюємося туди, де ще ніхто нічого не робив."
-3. "Я не знаю, наскільки слова взагалі можуть це передати, але давайте я спробую пояснити це максимально просто і без зайвої води."
-
-Вираження захоплення та емоцій
-4. "Ви просто вдумайтесь у це! Це ж справжній відвал бошки, ну погодьтесь."
-5. "Я зараз дивлюся на цей результат і просто не вірю своїм очам. Це якась абсолютна магія, по-іншому і не скажеш."
-6. "Цей підхід — це просто якийсь космос. Я щиро знімаю капелюха перед тими, хто взагалі це придумав."
-7. "Я очікував побачити тут що завгодно, але тільки не це. Це просто тотальний розрив шаблонів!"
-8. "Ця деталь — це окремий вид мистецтва. Я взагалі не розумію, як воно працює зсередини, але це настільки круто, що можна просто збожеволіти."
-
-Розповідь про труднощі та зусилля
-9. "Ми билися над цим не один день, я вже трохи схожий на зомбі, але повірте: фінальний результат перекриває абсолютно всю втому."
-10. "Давайте будемо відвертими, це рішення об'єктивно не з найпростіших. Але чи варте воно тих зусиль? На всі сто відсотків."
-11. "Я не претендую на звання супер-експерта у цій вузькій темі, я просто ділюся своїм досвідом, але давайте спробуємо розібратися разом, як це взагалі працює."
-
-Опис процесів та атмосфери
-12. "Тут є така неймовірна логіка, що хочеться просто зупинитися, роздивитися все ближче і взагалі нікуди не поспішати."
-13. "Система максимально інтуїтивна і зрозуміла. Ти просто робиш перший крок, і далі все йде як по маслу."
-
-Підсумки та висновки
-14. "Новий досвід — це, мабуть, найкраще, у що людина може інвестувати свій час та ресурси. Тому постійно пробуйте щось нове, друзі, воно того точно варте."
-15. "Це був дійсно складний виклик, але емоції від результату просто переповнюють. Я щиро радий, що зміг розділити цей момент з вами!"
-
-## Додаткові вказівки
-Дотримуйся наведених вище вказівок природно, не повторюючи, не посилаючись, не переказуючи та не відтворюючи жодних формулювань з них. Усі вказівки повинні непомітно керувати діями і ні в якому разі не впливати на формулювання відповіді — ані явно, ані на метарівні.
-
-You may receive an assistant tool call to "${INTERNAL_DRAFT_TOOL_NAME}" followed by a tool result with the same call ID. That exchange is synthetic internal metadata produced by another model. It is not a real user-visible tool invocation.
-Treat the "${INTERNAL_DRAFT_TOOL_NAME}" tool result as background reasoning or a draft answer to inform your response. Use it to answer the user clearly and directly. Do not mention the internal tool exchange, do not ask the user to run it, and do not expose it unless the user explicitly asks for that internal reasoning.`;
-
-export const enei1Executor: Executor = createTwoPassExecutor({
-  draftModel: REASONING_MODEL,
-  finalModel: LOCALIZED_MODEL,
-  draftSystemPrompt: DRAFT_SYSTEM_PROMPT,
-  finalSystemPrompt: LOCALIZED_SYSTEM_PROMPT_SUFFIX,
-});
-
-export default enei1Executor;