@neutrome/open-ai-router 0.3.7 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "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.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/observer.test.ts

@@ -31,4 +31,20 @@ 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: { durationMs: 123 },
+    });
+
+    expect(collector.getTrace().rawTrace).toBe(
+      ';timing {"kind":"provider","event":"provider.finished","executionId":"provider-1","durationMs":123}',
+    );
+  });
 });

package/src/observer.ts

@@ -53,6 +53,7 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
   return {
     observe(event) {
       appendLilSegment(event);
+      appendTimingComment(event);
 
       switch (event.kind) {
         case "request.received":
@@ -156,6 +157,26 @@ export function createTraceCollector(spanId = crypto.randomUUID()): {
     if (!lilText) return;
     rawSegments.push(`;${traceSegmentLabel(event)}:${rawSegmentIndex++}\n${lilText}`);
   }
+
+  function appendTimingComment(event: AuditEvent): void {
+    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({
+      kind: traceTimingKind(event),
+      event: event.kind,
+      executionId: event.executionId,
+      durationMs,
+    })}`);
+  }
+}
+
+function traceTimingKind(event: AuditEvent): TraceSpanKind | "remote_mcp" {
+  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 {

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,
@@ -95,8 +100,7 @@ export class ProviderHttpError extends Error {
   constructor(
     message: string,
     readonly status: number,
-    readonly body: Uint8Array,
-    readonly contentType: string,
+    readonly program: Program,
   ) {
     super(message);
   }
@@ -214,7 +218,7 @@ export async function handleChatCompletions(
       await remoteMcp.close();
     }
   } catch (error) {
-    return errorResponse(error);
+    return errorResponse(error, "chat-completions");
   }
 }
 
@@ -291,7 +295,7 @@ async function handleProviderStyle(
       await remoteMcp.close();
     }
   } catch (error) {
-    return errorResponse(error);
+    return errorResponse(error, style);
   }
 }
 
@@ -357,7 +361,15 @@ export function createFetchProviderInvoker(
           timed.signal,
         );
         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 bytes = new Uint8Array(await upstream.arrayBuffer());
@@ -406,7 +418,15 @@ export function createFetchProviderInvoker(
           timed.signal,
         );
         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(
@@ -537,11 +557,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();
       }
     },
@@ -689,74 +707,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,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     if (target.kind === "executor") {
       const executor = await getExecutorOrThrow(target.executorId);
+      const startedMs = Date.now();
       observe(createAuditEvent({
         kind: "executor.started",
         requestId,
@@ -111,6 +112,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           requestId,
           executionId,
           target: executionTargetAuditRef(target),
+          data: { durationMs: Date.now() - startedMs },
           ...withParentExecutionId(parentExecutionId),
         }));
         return result;
@@ -122,6 +124,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     }
 
     const providerInvoker = getProviderInvokerOrThrow();
+    const startedMs = Date.now();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -162,6 +165,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
         requestId,
         executionId,
         target: executionTargetAuditRef(target),
+        data: { durationMs: Date.now() - startedMs },
         ...withParentExecutionId(parentExecutionId),
       }));
       return result;
@@ -208,6 +212,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
 
     if (target.kind === "executor") {
       const executor = await getExecutorOrThrow(target.executorId);
+      const startedMs = Date.now();
       observe(createAuditEvent({
         kind: "executor.stream_started",
         requestId,
@@ -245,6 +250,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
           requestId,
           executionId,
           target: executionTargetAuditRef(target),
+          data: { durationMs: Date.now() - startedMs },
           ...withParentExecutionId(parentExecutionId),
         }));
         return;
@@ -256,6 +262,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     }
 
     const providerInvoker = getProviderInvokerOrThrow();
+    const startedMs = Date.now();
     const providerCtx = createProviderInvocationContext(
       requestId,
       executionId,
@@ -298,6 +305,7 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
         requestId,
         executionId,
         target: executionTargetAuditRef(target),
+        data: { durationMs: Date.now() - startedMs },
         ...withParentExecutionId(parentExecutionId),
       }));
     } catch (error) {

package/src/router/mcp.ts

@@ -45,8 +45,35 @@ 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);
+          ctx.observe({
+            kind: "remote_mcp.connect",
+            requestId: ctx.requestId,
+            executionId: `remote_mcp_connect_${server.name}_${crypto.randomUUID()}`,
+            parentExecutionId: ctx.executionId,
+            timestamp: new Date().toISOString(),
+            data: {
+              server: server.name,
+              toolName: name,
+              durationMs: Date.now() - connectStartedMs,
+            },
+          });
+          const callStartedMs = Date.now();
           const result = await client.callTool(snapshot.name, args);
+          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(),
+            data: {
+              server: server.name,
+              toolName: name,
+              remoteToolName: snapshot.name,
+              durationMs: Date.now() - callStartedMs,
+            },
+          });
           return stringifyMcpToolResult(result);
         },
       });

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;