@neutrome/open-ai-router 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -9,7 +9,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "hono": "^4.12.18",
     "@neutrome/lil-engine": "0.2.1",
-    "@neutrome/lilsdk-ts": "0.2.3"
+    "@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

@@ -40,11 +40,15 @@ describe("createTraceCollector", () => {
       requestId: "request-1",
       executionId: "provider-1",
       timestamp: "2026-06-24T12:00:03.000Z",
-      data: { durationMs: 123 },
+      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","executionId":"provider-1","durationMs":123}',
+      ';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,8 +52,8 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
 
   return {
     observe(event) {
-      appendLilSegment(event);
       appendTimingComment(event);
+      appendLilSegment(event);
 
       switch (event.kind) {
         case "request.received":
@@ -159,19 +159,40 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
   }
 
   function appendTimingComment(event: AuditEvent): void {
+    const startedAt = asString(event.data?.startedAt);
+    const finishedAt = asString(event.data?.finishedAt);
     const rawDurationMs = event.data?.durationMs;
-    if (typeof rawDurationMs !== "number" || !Number.isFinite(rawDurationMs) || rawDurationMs < 0) return;
-    const durationMs = Math.round(rawDurationMs);
-    rawSegments.push(`;timing ${JSON.stringify({
+    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): TraceSpanKind | "remote_mcp" {
+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";
@@ -288,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.ts

@@ -45,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();
@@ -58,6 +59,7 @@ export type RouterExecutionOptions = Pick<
   transforms?: Readonly<Record<string, ProgramTransform>>;
   upstreamTimeoutMs?: number;
   remoteMcpClientFactory?: RemoteMcpClientFactory;
+  incomingExecutionId?: string;
 };
 
 export type HandleChatCompletionsOptions = RouterExecutionOptions & {
@@ -179,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,
@@ -190,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) {
@@ -256,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,
@@ -267,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) {
@@ -348,18 +364,49 @@ 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) {
           const providerError = await toProviderError(provider, upstream);
           emitObservedProgram(providerCtx.observe, "provider.response", providerError.program, {
@@ -372,7 +419,22 @@ export function createFetchProviderInvoker(
           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,
@@ -405,18 +467,49 @@ 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) {
           const providerError = await toProviderError(provider, upstream);
           emitObservedProgram(providerCtx.observe, "provider.response", providerError.program, {
@@ -437,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) {
@@ -444,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);
@@ -510,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>({
@@ -662,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");
@@ -671,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;
     }

package/src/router/execution-runtime.ts

@@ -77,6 +77,7 @@ 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,
@@ -88,6 +89,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
         },
         ...withParentExecutionId(parentExecutionId),
       }));
@@ -107,12 +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: { durationMs: Date.now() - startedMs },
+          data: {
+            startedAt,
+            finishedAt: new Date(finishedMs).toISOString(),
+            durationMs: finishedMs - startedMs,
+          },
           ...withParentExecutionId(parentExecutionId),
         }));
         return result;
@@ -125,6 +132,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     const providerInvoker = getProviderInvokerOrThrow();
     const startedMs = Date.now();
+    const startedAt = new Date(startedMs).toISOString();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -144,6 +152,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
       },
       ...withParentExecutionId(parentExecutionId),
     }));
@@ -160,12 +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: { durationMs: Date.now() - startedMs },
+        data: {
+          provider: target.provider ?? "",
+          model: target.model,
+          startedAt,
+          finishedAt: new Date(finishedMs).toISOString(),
+          durationMs: finishedMs - startedMs,
+        },
         ...withParentExecutionId(parentExecutionId),
       }));
       return result;
@@ -213,6 +229,7 @@ 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,
@@ -224,6 +241,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
         },
         ...withParentExecutionId(parentExecutionId),
       }));
@@ -245,12 +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: { durationMs: Date.now() - startedMs },
+          data: {
+            startedAt,
+            finishedAt: new Date(finishedMs).toISOString(),
+            durationMs: finishedMs - startedMs,
+          },
           ...withParentExecutionId(parentExecutionId),
         }));
         return;
@@ -263,6 +286,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     const providerInvoker = getProviderInvokerOrThrow();
     const startedMs = Date.now();
+    const startedAt = new Date(startedMs).toISOString();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -282,6 +306,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           transforms: target.transforms ?? [],
           depth,
           maxDepth,
+          startedAt,
       },
       ...withParentExecutionId(parentExecutionId),
     }));
@@ -300,12 +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: { durationMs: Date.now() - startedMs },
+        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>;
@@ -47,31 +48,33 @@ export function createRemoteMcpToolSet(
         async execute(args: Record<string, unknown>, ctx: ExecutorContext) {
           const connectStartedMs = Date.now();
           const client = await pool.get(server, ctx.signal);
-          ctx.observe({
+          observeTimingEvent({
+            observe: ctx.observe,
             kind: "remote_mcp.connect",
             requestId: ctx.requestId,
             executionId: `remote_mcp_connect_${server.name}_${crypto.randomUUID()}`,
             parentExecutionId: ctx.executionId,
-            timestamp: new Date().toISOString(),
+            startedAtMs: connectStartedMs,
+            finishedAtMs: Date.now(),
             data: {
               server: server.name,
               toolName: name,
-              durationMs: Date.now() - connectStartedMs,
             },
           });
           const callStartedMs = Date.now();
           const result = await client.callTool(snapshot.name, args);
-          ctx.observe({
+          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,
-            timestamp: new Date().toISOString(),
+            startedAtMs: callStartedMs,
+            finishedAtMs: Date.now(),
             data: {
               server: server.name,
               toolName: name,
               remoteToolName: snapshot.name,
-              durationMs: Date.now() - callStartedMs,
             },
           });
           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,
+  }));
+}