@neutrome/open-ai-router 0.1.18 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # `@neutrome/open-ai-router`
 
-Deployable router app and reusable router/runtime library surface built on `lil-core` + `lil-exec`.
+Deployable router app and reusable router/runtime library built on
+`@neutrome/lil-engine` for protocol conversion and `@neutrome/lilsdk-ts` for
+executor/tool contracts.
 
 ```ts
 import { createApp, createRouterRuntime, type RouterConfig } from "@neutrome/open-ai-router";
@@ -8,8 +10,9 @@ import { createApp, createRouterRuntime, type RouterConfig } from "@neutrome/ope
 
 Primary runtime model:
 
-- client JSON/SSE -> `lil-core` IR
-- target resolution -> `lil-exec`
+- client JSON/SSE -> `@neutrome/lil-engine` IR
+- target resolution -> router execution runtime
+- SDK executor or upstream provider invocation
 - provider transport -> router host
 
 Development commands:
@@ -22,4 +25,5 @@ pnpm --filter @neutrome/open-ai-router typecheck
 Notes:
 
 - `RouterConfig` is the canonical router config surface.
-- `/v1/models` lists configured executor aliases plus provider `catalog` entries.
+- `/v1/models` lists configured executor aliases.
+- Executor contracts and `connectTools` come from `@neutrome/lilsdk-ts`.

package/package.json

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

package/src/app/factory.test.ts

@@ -12,7 +12,7 @@ const config: RouterConfig = {
       exports: ["*"],
     },
   },
-  executors: {
+  modelNamespaces: {
     default: {
       exports: ["*"],
       models: {
@@ -28,7 +28,7 @@ describe("createRouterApp trace finalization", () => {
     const onTrace = vi.fn(async () => {});
     const app = createRouterApp({
       config,
-      executors: {},
+      executorImplementations: {},
       auth: {
         async authenticate() {
           return {};
@@ -79,7 +79,7 @@ describe("createRouterApp trace finalization", () => {
     const onTrace = vi.fn(async () => {});
     const app = createRouterApp({
       config,
-      executors: {},
+      executorImplementations: {},
       auth: {
         async authenticate() {
           return {};

package/src/app/factory.ts

@@ -1,6 +1,5 @@
 import { Hono, type Context } from "hono";
-import type { Executor, ProgramTransform } from "@neutrome/lil-engine";
-import type { ExecutionRuntimeOptions } from "@neutrome/lil-engine";
+import type { Executor, ProgramTransform } from "@neutrome/lilsdk-ts";
 import { cors } from "./cors.ts";
 import { healthHandler } from "./health.ts";
 import { createTraceCollector, type ExecutionTrace } from "../observer.ts";
@@ -16,6 +15,7 @@ import {
 import type { RequestContext } from "../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";
 
 export type RouterAppAuth = {
   authenticate(request: Request, env: Record<string, unknown>): Promise<object | null>;
@@ -29,7 +29,7 @@ export type RouterAppHooks = {
 
 export type RouterAppOptions = {
   config: RouterConfig;
-  executors: Readonly<Record<string, Executor>>;
+  executorImplementations: Readonly<Record<string, Executor>>;
   transforms?: Readonly<Record<string, ProgramTransform>>;
   auth: RouterAppAuth;
   hooks?: RouterAppHooks;
@@ -135,7 +135,7 @@ export function createRouterApp(options: RouterAppOptions) {
       const response = await handler({
         runtime,
         ctx,
-        executors: options.executors,
+        executorImplementations: options.executorImplementations,
         ...(options.transforms ? { transforms: options.transforms } : {}),
         observe,
         ...(options.upstreamTimeoutMs !== undefined ? { upstreamTimeoutMs: options.upstreamTimeoutMs } : {}),

package/src/app/handlers.ts

@@ -1,5 +1,4 @@
 import type { Context } from "hono";
-import type { Executor, ProgramTransform } from "@neutrome/lil-engine";
 import type { RequestContext } from "../auth/types.ts";
 import {
   handleAnthropicMessages,
@@ -18,10 +17,7 @@ type OpenAiModel = {
   owned_by: string;
 };
 
-export type ChatCompletionsHandlerOptions = RouterExecutionOptions & {
-  executors?: Readonly<Record<string, Executor>>;
-  transforms?: Readonly<Record<string, ProgramTransform>>;
-};
+export type ChatCompletionsHandlerOptions = RouterExecutionOptions;
 
 export type ResponsesHandlerOptions = ChatCompletionsHandlerOptions;
 export type AnthropicMessagesHandlerOptions = ChatCompletionsHandlerOptions;
@@ -111,8 +107,8 @@ function createExecutionHandlerOptions(
     ctx,
   } as Parameters<typeof handleChatCompletions>[0];
 
-  if (options.executors) {
-    handlerOptions.executors = options.executors;
+  if (options.executorImplementations) {
+    handlerOptions.executorImplementations = options.executorImplementations;
   }
   if (options.resolveExecutor) {
     handlerOptions.resolveExecutor = options.resolveExecutor;

package/src/example.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
+import { appendAssistantMessage } from "@neutrome/lilsdk-ts/synthetic";
+import { streamTextResponse } from "@neutrome/lilsdk-ts/stream";
 import {
-  appendAssistantMessage,
   getModel,
-  streamTextResponse,
 } from "@neutrome/lil-engine";
 import { createApp } from "./example.ts";
 
@@ -19,11 +19,11 @@ describe("open-ai-router createApp", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           semantyka: {
             exports: ["enei-*"],
             models: {
-              "enei-1": { executor: "enei-1" },
+              "enei-1": { executorId: "enei-1" },
             },
           },
         },
@@ -59,7 +59,7 @@ describe("open-ai-router createApp", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -135,7 +135,7 @@ describe("open-ai-router createApp", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -209,7 +209,7 @@ describe("open-ai-router createApp", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -278,16 +278,16 @@ describe("open-ai-router createApp", () => {
     const app = createApp({
       config: {
         providers: {},
-        executors: {
+        modelNamespaces: {
           support: {
             exports: ["*"],
             models: {
-              "refund-router": { executor: "support/refund-router" },
+              "refund-router": { executorId: "support/refund-router" },
             },
           },
         },
       },
-      executors: {
+      executorImplementations: {
         "support/refund-router": {
           async execute(request) {
             executeCalled = true;
@@ -333,16 +333,16 @@ describe("open-ai-router createApp", () => {
     const app = createApp({
       config: {
         providers: {},
-        executors: {
+        modelNamespaces: {
           support: {
             exports: ["*"],
             models: {
-              "refund-router": { executor: "support/refund-router" },
+              "refund-router": { executorId: "support/refund-router" },
             },
           },
         },
       },
-      executors: {
+      executorImplementations: {
         "support/refund-router": {
           async execute(request) {
             capturedModel = getModel(request) ?? null;

package/src/example.ts

@@ -29,8 +29,8 @@ export function createApp(options: CreateAppOptions) {
   const app = new Hono();
 
   const handlerOptions = {} as ChatCompletionsHandlerOptions;
-  if (options.executors) {
-    handlerOptions.executors = options.executors;
+  if (options.executorImplementations) {
+    handlerOptions.executorImplementations = options.executorImplementations;
   }
   if (options.transforms) {
     handlerOptions.transforms = options.transforms;

package/src/index.ts

@@ -15,34 +15,56 @@ export type { CreateAppOptions } from "./example.ts";
 
 export {
   createFetchProviderInvoker,
+  createExecutionRuntime,
   createRouterExecutionRuntime,
   createRouterRuntime,
+  createAuditEvent,
+  createInMemoryAuditSink,
+  ExecutionError,
   handleAnthropicMessages,
   handleChatCompletions,
   handleGoogleGenAI,
   handleResponses,
+  isExecutionError,
   listConfiguredModels,
   ProviderHttpError,
   resolveInvocationTarget,
   resolveInvocationTargets,
   resolveRequestTarget,
   RouterError,
+  executionTargetAuditRef,
+  executionTargetId,
 } from "./router/index.ts";
 export type {
+  AuditEvent,
+  AuditEventInput,
   AuthConfig,
   CreateRouterOptions,
-  ExecutorNamespaceConfig,
-  ExecutorRouteConfig,
-  ExecutorRouteRuntime,
-  ExecutorRuntime,
+  ExecutionErrorDetails,
+  ExecutionErrorKind,
+  ExecutionErrorStage,
+  ExecutionRuntime,
+  ExecutionRuntimeOptions,
+  ExecutionTarget,
+  Executor,
   HandleAnthropicMessagesOptions,
   HandleChatCompletionsOptions,
   HandleGoogleGenAIOptions,
   HandleResponsesOptions,
+  InvokeOptions,
+  ModelNamespaceConfig,
+  ModelNamespaceRuntime,
+  ModelRouteConfig,
+  ModelRouteRuntime,
+  ProgramTransform,
   ProviderApiStyle,
   ProviderApiStyle as ProviderStyle,
+  ProviderInvocationContext,
+  ProviderInvoker,
   ProviderRuntime,
   ProviderTargetConfig,
+  ResolveExecutor,
+  ResolveTarget,
   RemoteMcpServerConfig,
   RemoteMcpToolConfig,
   ResolvedTarget,

package/src/model.example.ts

@@ -0,0 +1,61 @@
+import {
+  createTwoPassExecutor,
+  INTERNAL_DRAFT_TOOL_NAME,
+  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;

package/src/observer.ts

@@ -1,4 +1,5 @@
-import { opcodeName, type AuditEvent, type Program } from "@neutrome/lil-engine";
+import { opcodeName, type Program } from "@neutrome/lil-engine";
+import type { AuditEvent } from "./router/execution-types.ts";
 
 const decoder = new TextDecoder();
 

package/src/router/audit.ts

@@ -0,0 +1,21 @@
+import type { AuditEvent, AuditEventInput } from "./execution-types.ts";
+
+export function createAuditEvent(input: AuditEventInput): AuditEvent {
+  return {
+    ...input,
+    timestamp: input.timestamp ?? new Date().toISOString(),
+  };
+}
+
+export function createInMemoryAuditSink(): {
+  events: AuditEvent[];
+  observe(event: AuditEvent): void;
+} {
+  const events: AuditEvent[] = [];
+  return {
+    events,
+    observe(event: AuditEvent) {
+      events.push(event);
+    },
+  };
+}

package/src/router/config.ts

@@ -12,9 +12,9 @@ export type ProviderTargetConfig = {
   headers?: Record<string, string>;
 };
 
-export type ExecutorRouteConfig =
+export type ModelRouteConfig =
   | {
-      executor: string;
+      executorId: string;
       alias?: string;
       transforms?: string[];
       mcps?: string[];
@@ -26,9 +26,9 @@ export type ExecutorRouteConfig =
       mcps?: string[];
     };
 
-export type ExecutorNamespaceConfig = {
+export type ModelNamespaceConfig = {
   exports?: string[] | null;
-  models: Record<string, ExecutorRouteConfig>;
+  models: Record<string, ModelRouteConfig>;
 };
 
 export type RemoteMcpToolConfig = {
@@ -48,6 +48,6 @@ export type RouterConfig = {
   trace?: boolean;
   auth?: AuthConfig;
   providers: Record<string, ProviderTargetConfig>;
-  executors: Record<string, ExecutorNamespaceConfig>;
+  modelNamespaces: Record<string, ModelNamespaceConfig>;
   mcps?: Record<string, RemoteMcpServerConfig>;
 };

package/src/router/errors.ts

@@ -0,0 +1,60 @@
+import type { ValidationIssue } from "@neutrome/lil-engine";
+
+export type ExecutionErrorKind =
+  | "validation"
+  | "resolution"
+  | "provider"
+  | "transform"
+  | "executor"
+  | "stream"
+  | "cancellation"
+  | "recursion_limit";
+
+export type ExecutionErrorStage =
+  | "request"
+  | "target_resolution"
+  | "transform"
+  | "transform_output"
+  | "provider_invoke"
+  | "provider_result"
+  | "executor_invoke"
+  | "executor_result"
+  | "stream_chunk";
+
+export type ExecutionErrorDetails = {
+  issues?: ValidationIssue[];
+  depth?: number;
+  maxDepth?: number;
+  transform?: string;
+  target?: string;
+  source?: "provider" | "executor";
+};
+
+export class ExecutionError extends Error {
+  readonly kind: ExecutionErrorKind;
+  readonly stage?: ExecutionErrorStage;
+  readonly details?: ExecutionErrorDetails;
+
+  constructor(
+    kind: ExecutionErrorKind,
+    message: string,
+    options: {
+      stage?: ExecutionErrorStage;
+      details?: ExecutionErrorDetails;
+      cause?: unknown;
+    } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.kind = kind;
+    if (options.stage !== undefined) {
+      this.stage = options.stage;
+    }
+    if (options.details !== undefined) {
+      this.details = options.details;
+    }
+  }
+}
+
+export function isExecutionError(error: unknown): error is ExecutionError {
+  return error instanceof ExecutionError;
+}

package/src/router/execute.test.ts

@@ -1,4 +1,4 @@
-import { appendAssistantMessage } from "@neutrome/lil-engine";
+import { appendAssistantMessage } from "@neutrome/lilsdk-ts/synthetic";
 import { describe, expect, it, vi } from "vitest";
 import type { RequestContext } from "../auth/types.ts";
 import { handleChatCompletions } from "./execute.ts";
@@ -23,7 +23,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -132,7 +132,7 @@ describe("router execution", () => {
             }],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -239,7 +239,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -312,7 +312,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -387,7 +387,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -451,11 +451,11 @@ describe("router execution", () => {
     const runtime = createRouterRuntime({
       config: {
         providers: {},
-        executors: {
+        modelNamespaces: {
           enei: {
             exports: ["enei-*"],
             models: {
-              "enei-1": { executor: "enei-1" },
+              "enei-1": { executorId: "enei-1" },
             },
           },
         },
@@ -479,7 +479,7 @@ describe("router execution", () => {
     const response = await handleChatCompletions({
       runtime,
       ctx,
-      executors: {
+      executorImplementations: {
         "enei-1": {
           async execute(request) {
             return appendAssistantMessage(request, "done");
@@ -515,7 +515,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {
@@ -589,7 +589,7 @@ describe("router execution", () => {
             exports: ["*"],
           },
         },
-        executors: {
+        modelNamespaces: {
           default: {
             exports: ["*"],
             models: {