@neutrome/open-ai-router 0.4.2 → 0.5.0

package/src/router/request-target.ts

@@ -0,0 +1,56 @@
+import { getModel, type Program } from "@neutrome/lil-engine";
+import { ExecutionError, RouterError } from "./errors.ts";
+import type { Executor } from "./execution-types.ts";
+import { resolveInvocationTarget, type ResolvedTarget } from "./resolve.ts";
+import type { RouterRuntime } from "./runtime.ts";
+
+export function resolveModelNamespaceExecutor(
+  runtime: RouterRuntime,
+  name: string,
+): Executor | null {
+  if (!runtime.modelNamespaces.has(name)) return null;
+  return {
+    async execute(request, ctx) {
+      const model = getModel(request);
+      if (!model)
+        throw new ExecutionError(
+          "resolution",
+          "Request is missing model for namespace executor resolution",
+          { stage: "target_resolution" },
+        );
+      return ctx.invoke(request, {
+        target: resolveInvocationTarget(runtime, `${name}/${model}`).target,
+      });
+    },
+    async *stream(request, ctx) {
+      const model = getModel(request);
+      if (!model)
+        throw new ExecutionError(
+          "resolution",
+          "Request is missing model for namespace executor resolution",
+          { stage: "target_resolution" },
+        );
+      yield* ctx.invokeStream(request, {
+        target: resolveInvocationTarget(runtime, `${name}/${model}`).target,
+      });
+    },
+  };
+}
+
+export function resolveRequestTarget(
+  runtime: RouterRuntime,
+  request: Program,
+): ResolvedTarget {
+  const model = getModel(request);
+  if (!model)
+    throw new RouterError("Request is missing `model`", 400, "missing_model");
+  try {
+    return resolveInvocationTarget(runtime, model);
+  } catch (error) {
+    throw new RouterError(
+      error instanceof Error ? error.message : "Model resolution failed",
+      404,
+      "model_not_found",
+    );
+  }
+}

package/src/router/resolve.test.ts

@@ -1,14 +1,19 @@
 import { describe, expect, it } from "vitest";
 import { createRouterRuntime } from "./runtime.ts";
-import { listConfiguredModels, resolveInvocationTarget, resolveInvocationTargets } from "./resolve.ts";
+import {
+  listConfiguredModels,
+  resolveInvocationTarget,
+  resolveInvocationTargets,
+} from "./resolve.ts";
 
 describe("router resolution", () => {
   it("resolves executor-backed aliases before provider-backed models", () => {
     const runtime = createRouterRuntime({
       config: {
+        modelSuffixes: ["slwin"],
         providers: {
           openrouter: {
-            api_base_url: "https://openrouter.ai/api/v1",
+            apiBaseUrl: "https://openrouter.ai/api/v1",
             style: "chat-completions",
             exports: ["*"],
           },
@@ -18,7 +23,10 @@ describe("router resolution", () => {
             exports: ["enei-*"],
             models: {
               "enei-1": { executorId: "enei-1" },
-              "enei-1-pro": { executorId: "enei-1-pro", transforms: ["reasoning:high"] },
+              "enei-1-pro": {
+                executorId: "enei-1-pro",
+                transforms: ["reasoning:high"],
+              },
             },
           },
         },
@@ -39,19 +47,22 @@ describe("router resolution", () => {
   it("resolves qualified provider models and preserves suffix transforms", () => {
     const runtime = createRouterRuntime({
       config: {
+        modelSuffixes: ["slwin", "kvtools"],
         providers: {
           openrouter: {
-            api_base_url: "https://openrouter.ai/api/v1",
+            apiBaseUrl: "https://openrouter.ai/api/v1",
             style: "chat-completions",
             exports: ["google/*"],
           },
         },
         modelNamespaces: {},
       },
-      knownSuffixes: ["slwin", "kvtools"],
     });
 
-    const resolved = resolveInvocationTarget(runtime, "openrouter/google/gemma-4-31b-it+kvtools");
+    const resolved = resolveInvocationTarget(
+      runtime,
+      "openrouter/google/gemma-4-31b-it+kvtools",
+    );
     expect(resolved.source).toBe("provider");
     expect(resolved.target).toEqual({
       kind: "provider",
@@ -61,12 +72,31 @@ describe("router resolution", () => {
     });
   });
 
+  it("requires configured suffixes", () => {
+    const runtime = createRouterRuntime({
+      config: {
+        providers: {
+          openrouter: {
+            apiBaseUrl: "https://openrouter.ai/api/v1",
+            style: "chat-completions",
+            exports: ["*"],
+          },
+        },
+        modelNamespaces: {},
+      },
+    });
+
+    expect(() =>
+      resolveInvocationTarget(runtime, "openrouter/openai/gpt-4.1+slwin:8"),
+    ).toThrow("Unknown model suffix: slwin");
+  });
+
   it("resolves namespace model routes that alias provider targets", () => {
     const runtime = createRouterRuntime({
       config: {
         providers: {
           openrouter: {
-            api_base_url: "https://openrouter.ai/api/v1",
+            apiBaseUrl: "https://openrouter.ai/api/v1",
             style: "chat-completions",
             exports: ["openai/gpt-4.1-mini"],
           },
@@ -75,7 +105,10 @@ describe("router resolution", () => {
           semantyka: {
             exports: ["enei-*"],
             models: {
-              "enei-1": { provider: "openrouter", model: "openai/gpt-4.1-mini" },
+              "enei-1": {
+                provider: "openrouter",
+                model: "openai/gpt-4.1-mini",
+              },
             },
           },
         },
@@ -98,7 +131,7 @@ describe("router resolution", () => {
       config: {
         providers: {
           openrouter: {
-            api_base_url: "https://openrouter.ai/api/v1",
+            apiBaseUrl: "https://openrouter.ai/api/v1",
             style: "chat-completions",
             exports: ["*"],
           },
@@ -126,7 +159,7 @@ describe("router resolution", () => {
       config: {
         providers: {
           openrouter: {
-            api_base_url: "https://openrouter.ai/api/v1",
+            apiBaseUrl: "https://openrouter.ai/api/v1",
             style: "chat-completions",
             exports: ["*"],
           },

package/src/router/resolve.ts

@@ -1,5 +1,8 @@
 import type { ExecutionTarget } from "@neutrome/lilsdk-ts";
-import { parseModelSyntax, type ModelSuffixSpec } from "../util/model-syntax.ts";
+import {
+  parseModelSyntax,
+  type ModelSuffixSpec,
+} from "../util/model-syntax.ts";
 import type { RouterRuntime } from "./runtime.ts";
 
 export type ResolvedTarget = {
@@ -28,15 +31,22 @@ export function resolveInvocationTargets(
   runtime: RouterRuntime,
   requestedModel: string,
 ): ResolvedTarget[] {
-  const parsed = parseModelSyntax(requestedModel, runtime.knownSuffixes);
+  const parsed = parseModelSyntax(requestedModel, runtime.modelSuffixes);
   const qualified = splitQualified(parsed.baseModel);
   if (qualified) {
-    return resolveQualified(runtime, requestedModel, qualified.namespace, qualified.model, parsed.suffixes);
+    return resolveQualified(
+      runtime,
+      requestedModel,
+      qualified.namespace,
+      qualified.model,
+      parsed.suffixes,
+    );
   }
 
   const matches: ResolvedTarget[] = [];
   for (const namespace of runtime.modelNamespaceOrder) {
-    const modelNamespace = runtime.modelNamespaces.get(namespace)!;
+    const modelNamespace = runtime.modelNamespaces.get(namespace);
+    if (!modelNamespace) continue;
     const route = modelNamespace.routes.get(parsed.baseModel);
     if (route && modelNamespace.exportsMatcher(parsed.baseModel)) {
       matches.push({
@@ -57,7 +67,8 @@ export function listConfiguredModels(runtime: RouterRuntime): string[] {
   const models: string[] = [];
 
   for (const namespace of runtime.modelNamespaceOrder) {
-    const modelNamespace = runtime.modelNamespaces.get(namespace)!;
+    const modelNamespace = runtime.modelNamespaces.get(namespace);
+    if (!modelNamespace) continue;
     for (const alias of modelNamespace.routes.keys()) {
       if (modelNamespace.exportsMatcher(alias)) {
         models.push(`${namespace}/${alias}`);
@@ -79,7 +90,9 @@ function resolveQualified(
   const modelNamespace = runtime.modelNamespaces.get(namespace);
 
   if (provider && modelNamespace) {
-    throw new Error(`Ambiguous namespace \`${namespace}\`: both provider and model namespace are registered`);
+    throw new Error(
+      `Ambiguous namespace \`${namespace}\`: both provider and model namespace are registered`,
+    );
   }
 
   if (modelNamespace) {
@@ -87,33 +100,37 @@ function resolveQualified(
     if (!route || !modelNamespace.exportsMatcher(model)) {
       return [];
     }
-    return [{
-      requestedModel,
-      namespace,
-      source: route.target.kind,
-      suffixes,
-      mcps: route.mcps,
-      target: withSuffixTransforms(route.target, suffixes),
-    }];
+    return [
+      {
+        requestedModel,
+        namespace,
+        source: route.target.kind,
+        suffixes,
+        mcps: route.mcps,
+        target: withSuffixTransforms(route.target, suffixes),
+      },
+    ];
   }
 
   if (provider) {
     if (!provider.exportsMatcher(model)) {
       return [];
     }
-    return [{
-      requestedModel,
-      namespace,
-      source: "provider",
-      suffixes,
-      mcps: [],
-      target: {
-        kind: "provider",
-        provider: namespace,
-        model,
-        transforms: suffixes.map((suffix) => suffix.raw),
+    return [
+      {
+        requestedModel,
+        namespace,
+        source: "provider",
+        suffixes,
+        mcps: [],
+        target: {
+          kind: "provider",
+          provider: namespace,
+          model,
+          transforms: suffixes.map((suffix) => suffix.raw),
+        },
       },
-    }];
+    ];
   }
 
   return [];
@@ -125,11 +142,16 @@ function withSuffixTransforms(
 ): ExecutionTarget {
   return {
     ...target,
-    transforms: [...(target.transforms ?? []), ...suffixes.map((suffix) => suffix.raw)],
+    transforms: [
+      ...(target.transforms ?? []),
+      ...suffixes.map((suffix) => suffix.raw),
+    ],
   };
 }
 
-function splitQualified(model: string): { namespace: string; model: string } | null {
+function splitQualified(
+  model: string,
+): { namespace: string; model: string } | null {
   const index = model.indexOf("/");
   if (index <= 0) {
     return null;

package/src/router/response-delivery.ts

@@ -0,0 +1,141 @@
+import {
+  emitProviderError,
+  emitProviderStreamChunk,
+  type Program,
+  type ProviderStyle,
+} from "@neutrome/lil-engine";
+import { errorProgramFromUnknown, toBody } from "./error-codec.ts";
+import type { ExecutionRuntimeOptions } from "./execution-types.ts";
+import type { ResolvedTarget } from "./resolve.ts";
+import { observeTimedExecution } from "./execution-events.ts";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export 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();
+  observeTimedExecution({
+    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>({
+      start(controller) {
+        if (responseStyle === "chat-completions") {
+          controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+        }
+        controller.close();
+      },
+    });
+    return new Response(stream, {
+      headers: {
+        "content-type": "text/event-stream; charset=utf-8",
+        ...routingHeaders(resolved),
+      },
+    });
+  }
+
+  let done = false;
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const bytes = emitProviderStreamChunk(responseStyle, first.value);
+      controller.enqueue(encoder.encode(`data: ${decoder.decode(bytes)}\n\n`));
+    },
+    async pull(controller) {
+      if (done) return;
+      try {
+        const result = await iterator.next();
+        if (result.done) {
+          done = true;
+          if (responseStyle === "chat-completions") {
+            controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+          }
+          await cleanup?.();
+          controller.close();
+          return;
+        }
+        const bytes = emitProviderStreamChunk(responseStyle, result.value);
+        controller.enqueue(
+          encoder.encode(`data: ${decoder.decode(bytes)}\n\n`),
+        );
+      } catch (error) {
+        done = true;
+        await cleanup?.();
+        const program = errorProgramFromUnknown(error);
+        const bytes = emitProviderError(responseStyle, program);
+        controller.enqueue(
+          encoder.encode(`event: error\ndata: ${decoder.decode(bytes)}\n\n`),
+        );
+        controller.close();
+      }
+    },
+    async cancel() {
+      await cleanup?.();
+      await iterator.return?.();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      ...routingHeaders(resolved),
+    },
+  });
+}
+
+export function jsonExecutionResponse(
+  body: Uint8Array,
+  resolved: ResolvedTarget,
+  userTime: number,
+): Response {
+  return new Response(toBody(body), {
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      ...routingHeaders(resolved),
+      ...timingHeaders(userTime),
+    },
+  });
+}
+
+function routingHeaders(resolved: ResolvedTarget): Record<string, string> {
+  if (resolved.target.kind === "provider") {
+    return {
+      "x-openairouter-source": resolved.source,
+      "x-openairouter-namespace": resolved.namespace,
+      "x-openairouter-provider-id": resolved.target.provider ?? "",
+      "x-openairouter-model-id": resolved.target.model,
+    };
+  }
+
+  return {
+    "x-openairouter-engine": "open-ai-router",
+    "x-openairouter-source": resolved.source,
+    "x-openairouter-namespace": resolved.namespace,
+    "x-openairouter-executor-id": resolved.target.executorId,
+    "x-openairouter-model-id": resolved.target.alias,
+  };
+}
+
+function timingHeaders(userTimeMs: number): Record<string, string> {
+  return {
+    "x-openairouter-user-time": String(userTimeMs),
+  };
+}

package/src/router/runtime.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { createRouterRuntime } from "./runtime.ts";
+
+const provider = {
+  apiBaseUrl: "https://api.example.test/v1",
+  style: "chat-completions" as const,
+};
+
+describe("router runtime configuration", () => {
+  it("rejects invalid references and URLs at startup", () => {
+    expect(() =>
+      createRouterRuntime({
+        config: {
+          providers: {
+            broken: { ...provider, apiBaseUrl: "file:///tmp/provider" },
+          },
+          modelNamespaces: {},
+        },
+      }),
+    ).toThrow("Provider broken has an invalid HTTP URL");
+
+    expect(() =>
+      createRouterRuntime({
+        config: {
+          providers: { upstream: provider },
+          modelNamespaces: {
+            default: {
+              models: { chat: { provider: "missing", model: "chat" } },
+            },
+          },
+        },
+      }),
+    ).toThrow("references unknown provider missing");
+  });
+
+  it("accepts only distinct, usable configured suffix names", () => {
+    expect(() =>
+      createRouterRuntime({
+        config: {
+          modelSuffixes: ["trim", "TRIM"],
+          providers: { upstream: provider },
+          modelNamespaces: {},
+        },
+      }),
+    ).toThrow("Invalid model suffix: TRIM");
+
+    const runtime = createRouterRuntime({
+      config: {
+        modelSuffixes: ["trim"],
+        providers: { upstream: provider },
+        modelNamespaces: {},
+      },
+    });
+    expect(runtime.modelSuffixes).toEqual(new Set(["trim"]));
+  });
+});

package/src/router/runtime.ts

@@ -40,7 +40,7 @@ export type RouterRuntime = {
   modelNamespaceOrder: readonly string[];
   mcps: ReadonlyMap<string, RemoteMcpServerRuntime>;
   upstreamAuthChain: readonly UpstreamAuthDriver[];
-  knownSuffixes: ReadonlySet<string>;
+  modelSuffixes: ReadonlySet<string>;
   fetchImpl: typeof fetch;
 };
 
@@ -51,11 +51,13 @@ export type RemoteMcpServerRuntime = RemoteMcpServerConfig & {
 export type CreateRouterOptions = {
   config: RouterConfig;
   fetchImpl?: typeof fetch;
-  knownSuffixes?: string[];
   upstreamAuthDrivers?: readonly UpstreamAuthDriver[];
 };
 
-export function createRouterRuntime(options: CreateRouterOptions): RouterRuntime {
+export function createRouterRuntime(
+  options: CreateRouterOptions,
+): RouterRuntime {
+  validateRouterConfig(options.config);
   const providers = new Map<string, ProviderRuntime>();
   const modelNamespaces = new Map<string, ModelNamespaceRuntime>();
   const mcps = new Map<string, RemoteMcpServerRuntime>();
@@ -82,24 +84,89 @@ export function createRouterRuntime(options: CreateRouterOptions): RouterRuntime
     modelNamespaces,
     modelNamespaceOrder,
     mcps,
-    upstreamAuthChain: options.upstreamAuthDrivers ?? buildUpstreamAuthChain(options.config.upstreamAuth),
-    knownSuffixes: new Set(options.knownSuffixes ?? ["slwin", "kvtools"]),
+    upstreamAuthChain:
+      options.upstreamAuthDrivers ??
+      buildUpstreamAuthChain(options.config.upstreamAuth),
+    modelSuffixes: new Set(options.config.modelSuffixes ?? []),
     fetchImpl: options.fetchImpl ?? globalThis.fetch.bind(globalThis),
   };
 }
 
-function buildProviderRuntime(name: string, config: ProviderTargetConfig): ProviderRuntime {
+function validateRouterConfig(config: RouterConfig): void {
+  validateModelSuffixes(config.modelSuffixes);
+  for (const [name, provider] of Object.entries(config.providers)) {
+    validateHttpUrl(provider.apiBaseUrl, `Provider ${name}`);
+  }
+  for (const [name, mcp] of Object.entries(config.mcps ?? {})) {
+    validateHttpUrl(mcp.url, `MCP ${name}`);
+  }
+  for (const [namespace, namespaceConfig] of Object.entries(
+    config.modelNamespaces,
+  )) {
+    if (Object.keys(namespaceConfig.models).length === 0) {
+      throw new Error(`Model namespace ${namespace} has no routes`);
+    }
+    for (const [alias, route] of Object.entries(namespaceConfig.models)) {
+      if ("provider" in route && !config.providers[route.provider]) {
+        throw new Error(
+          `Model route ${namespace}/${alias} references unknown provider ${route.provider}`,
+        );
+      }
+      for (const mcp of route.mcps ?? []) {
+        if (!config.mcps?.[mcp]) {
+          throw new Error(
+            `Model route ${namespace}/${alias} references unknown MCP ${mcp}`,
+          );
+        }
+      }
+    }
+  }
+}
+
+function validateModelSuffixes(suffixes: readonly string[] | undefined): void {
+  if (!suffixes) return;
+  const names = new Set<string>();
+  for (const suffix of suffixes) {
+    if (
+      !suffix ||
+      suffix !== suffix.trim().toLowerCase() ||
+      /[+:]/.test(suffix) ||
+      names.has(suffix)
+    ) {
+      throw new Error(`Invalid model suffix: ${suffix}`);
+    }
+    names.add(suffix);
+  }
+}
+
+function validateHttpUrl(value: string, label: string): void {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+      throw new Error("unsupported protocol");
+  } catch {
+    throw new Error(`${label} has an invalid HTTP URL`);
+  }
+}
+
+function buildProviderRuntime(
+  name: string,
+  config: ProviderTargetConfig,
+): ProviderRuntime {
   return {
     name,
     style: config.style,
-    apiBaseUrl: config.api_base_url,
+    apiBaseUrl: config.apiBaseUrl,
     endpointPath: defaultEndpointPath(config.style),
     headers: config.headers ?? {},
     exportsMatcher: createExportsMatcher(config.exports),
   };
 }
 
-function buildModelNamespaceRuntime(name: string, config: ModelNamespaceConfig): ModelNamespaceRuntime {
+function buildModelNamespaceRuntime(
+  name: string,
+  config: ModelNamespaceConfig,
+): ModelNamespaceRuntime {
   const routes = new Map<string, ModelRouteRuntime>();
   for (const [alias, route] of Object.entries(config.models)) {
     routes.set(alias, buildModelRoute(alias, route));
@@ -112,7 +179,10 @@ function buildModelNamespaceRuntime(name: string, config: ModelNamespaceConfig):
   };
 }
 
-function buildModelRoute(alias: string, route: ModelRouteConfig): ModelRouteRuntime {
+function buildModelRoute(
+  alias: string,
+  route: ModelRouteConfig,
+): ModelRouteRuntime {
   if ("provider" in route) {
     return {
       requestedAlias: alias,

package/src/router/targets.ts

@@ -2,7 +2,9 @@ import type { ExecutionTarget } from "./execution-types.ts";
 
 export function executionTargetId(target: ExecutionTarget): string {
   return target.kind === "provider"
-    ? target.provider ? `${target.provider}/${target.model}` : target.model
+    ? target.provider
+      ? `${target.provider}/${target.model}`
+      : target.model
     : `${target.executorId}/${target.alias}`;
 }