@neutrome/open-ai-router 0.1.18 → 0.3.0

package/src/router/execute.ts

@@ -1,5 +1,4 @@
 import {
-  createAuditEvent,
   emitChatCompletionsResponse,
   emitProviderRequest,
   emitProviderResponse,
@@ -14,20 +13,24 @@ import {
   setStreaming,
   type Program,
   type ProviderStyle,
-  withTools,
   usageObject,
-  type ExecutionTarget,
 } from "@neutrome/lil-engine";
+import { withTools } from "@neutrome/lilsdk-ts/tools";
 import {
   createExecutionRuntime,
-  ExecutionError,
-  type ExecutionRuntime,
-  type ExecutionRuntimeOptions,
-  type Executor,
-  type ProgramTransform,
-  type ProviderInvoker,
-} from "@neutrome/lil-engine";
-import type { RequestContext, TargetAuthContext } from "../auth/types.ts";
+} from "./execution-runtime.ts";
+import { ExecutionError } from "./errors.ts";
+import type {
+  ExecutionTarget,
+  ExecutionRuntime,
+  ExecutionRuntimeOptions,
+  Executor,
+  ProgramTransform,
+  ProviderInvocationContext,
+  ProviderInvoker,
+} from "./execution-types.ts";
+import { createAuditEvent } from "./audit.ts";
+import type { RequestContext, TargetAuthContext } from "../upstream-auth/types.ts";
 import { cloneForwardHeaders, isSse } from "../util/headers.ts";
 import { eventDataLines, splitSseEvents } from "../util/sse.ts";
 import { renderProgramAsLil } from "../observer.ts";
@@ -46,7 +49,7 @@ export type RouterExecutionOptions = Pick<
   ExecutionRuntimeOptions,
   "observe" | "requestIdFactory" | "executionIdFactory" | "resolveExecutor"
 > & {
-  executors?: Readonly<Record<string, Executor>>;
+  executorImplementations?: Readonly<Record<string, Executor>>;
   transforms?: Readonly<Record<string, ProgramTransform>>;
   upstreamTimeoutMs?: number;
   remoteMcpClientFactory?: RemoteMcpClientFactory;
@@ -55,21 +58,25 @@ export type RouterExecutionOptions = Pick<
 export type HandleChatCompletionsOptions = RouterExecutionOptions & {
   runtime: RouterRuntime;
   ctx: RequestContext;
+  program?: Program;
 };
 
 export type HandleResponsesOptions = RouterExecutionOptions & {
   runtime: RouterRuntime;
   ctx: RequestContext;
+  program?: Program;
 };
 
 export type HandleAnthropicMessagesOptions = RouterExecutionOptions & {
   runtime: RouterRuntime;
   ctx: RequestContext;
+  program?: Program;
 };
 
 export type HandleGoogleGenAIOptions = RouterExecutionOptions & {
   runtime: RouterRuntime;
   ctx: RequestContext;
+  program?: Program;
   forceStreaming?: boolean;
 };
 
@@ -102,7 +109,7 @@ export function createRouterExecutionRuntime(
 ): ExecutionRuntime {
   const runtimeOptions: ExecutionRuntimeOptions = {
     signal: ctx.request.signal,
-    resolveTarget(request) {
+    resolveTarget(request: Program) {
       return resolveRequestTarget(runtime, request).target;
     },
     providerInvoker: createFetchProviderInvoker(
@@ -112,8 +119,8 @@ export function createRouterExecutionRuntime(
     ),
   };
 
-  if (options.executors) {
-    runtimeOptions.executors = options.executors;
+  if (options.executorImplementations) {
+    runtimeOptions.executorImplementations = options.executorImplementations;
   }
   if (options.transforms) {
     runtimeOptions.transforms = options.transforms;
@@ -129,23 +136,23 @@ export function createRouterExecutionRuntime(
   }
 
   const userResolveExecutor = options.resolveExecutor;
-  runtimeOptions.resolveExecutor = (name) => {
+  runtimeOptions.resolveExecutor = (name: string) => {
     if (userResolveExecutor) {
       const result = userResolveExecutor(name);
       if (result) return result;
     }
-    return resolveNamespaceExecutor(runtime, name);
+    return resolveModelNamespaceExecutor(runtime, name);
   };
 
   return createExecutionRuntime(runtimeOptions);
 }
 
-function resolveNamespaceExecutor(
+function resolveModelNamespaceExecutor(
   runtime: RouterRuntime,
   name: string,
 ): Executor | null {
-  const executor = runtime.executors.get(name);
-  if (!executor) return null;
+  const modelNamespace = runtime.modelNamespaces.get(name);
+  if (!modelNamespace) return null;
 
   return {
     async execute(request, ctx) {
@@ -167,8 +174,7 @@ export async function handleChatCompletions(
   options: HandleChatCompletionsOptions,
 ): Promise<Response> {
   try {
-    const requestBody = new Uint8Array(await options.ctx.request.arrayBuffer());
-    const request = parseChatCompletionsRequest(requestBody);
+    const request = options.program ?? await parseRequestProgram("chat-completions", options.ctx.request);
     const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
     emitObservedProgram(options.observe, "request.received", request, {
       requestId: incomingExecutionId,
@@ -240,14 +246,13 @@ async function handleProviderStyle(
   options: RouterExecutionOptions & {
     runtime: RouterRuntime;
     ctx: RequestContext;
+    program?: Program;
   },
   mutateRequest?: (request: Program) => Program,
 ): Promise<Response> {
   try {
-    const requestBody = new Uint8Array(await options.ctx.request.arrayBuffer());
-    const request = mutateRequest
-      ? mutateRequest(parseProviderRequest(style, requestBody))
-      : parseProviderRequest(style, requestBody);
+    const baseRequest = options.program ?? await parseRequestProgram(style, options.ctx.request);
+    const request = mutateRequest ? mutateRequest(baseRequest) : baseRequest;
     const incomingExecutionId = `incoming_${crypto.randomUUID()}`;
     emitObservedProgram(options.observe, "request.received", request, {
       requestId: incomingExecutionId,
@@ -312,6 +317,16 @@ export function resolveRequestTarget(
   }
 }
 
+export async function parseRequestProgram(
+  style: ProviderStyle,
+  request: Request,
+): Promise<Program> {
+  const body = new Uint8Array(await request.arrayBuffer());
+  return style === "chat-completions"
+    ? parseChatCompletionsRequest(body)
+    : parseProviderRequest(style, body);
+}
+
 export function createFetchProviderInvoker(
   runtime: RouterRuntime,
   ctx: RequestContext,
@@ -556,13 +571,13 @@ function prepareRemoteMcpExecution(
   return {
     target: {
       kind: "executor",
-      executor: executorName,
+      executorId: executorName,
       alias: resolved.requestedModel,
     },
     options: {
       ...options,
-      executors: {
-        ...(options.executors ?? {}),
+      executorImplementations: {
+        ...(options.executorImplementations ?? {}),
         [executorName]: withTools(remoteMcp.tools, resolved.target),
       },
     },
@@ -598,7 +613,7 @@ function routingHeaders(resolved: ResolvedTarget): Record<string, string> {
     "x-openairouter-engine": "open-ai-router",
     "x-openairouter-source": resolved.source,
     "x-openairouter-namespace": resolved.namespace,
-    "x-openairouter-executor-id": resolved.target.executor,
+    "x-openairouter-executor-id": resolved.target.executorId,
     "x-openairouter-model-id": resolved.target.alias,
   };
 }
@@ -622,7 +637,7 @@ async function fetchProvider(
     headers.set(key, value);
   }
 
-  for (const driver of runtime.authChain) {
+  for (const driver of runtime.upstreamAuthChain) {
     const targetCtx: TargetAuthContext = { ...ctx, providerName: provider.name };
     const auth = await driver.collectTarget(targetCtx);
     if (!auth) {
@@ -819,7 +834,7 @@ function createUpstreamSignal(
 }
 
 function emitProviderUsage(
-  providerCtx: import("@neutrome/lil-engine").ProviderInvocationContext,
+  providerCtx: ProviderInvocationContext,
   response: Program | null,
   provider: string,
   requestBytes: number,

package/src/router/execution-runtime.test.ts

@@ -0,0 +1,327 @@
+import { describe, expect, it } from "vitest";
+import {
+  cloneProgram,
+  createProgram,
+  Opcode,
+} from "@neutrome/lil-engine";
+import {
+  createAuditEvent,
+  createExecutionRuntime,
+  createInMemoryAuditSink,
+  ExecutionError,
+  executionTargetAuditRef,
+  executionTargetId,
+} from "./index.ts";
+import { observeExecutionStream } from "@neutrome/lilsdk-ts/stream";
+
+describe("router execution runtime", () => {
+  it("creates audit events with a stable envelope", () => {
+    const event = createAuditEvent({
+      kind: "executor.started",
+      requestId: "req_1",
+      executionId: "exec_1",
+      target: { kind: "executor", id: "enei-1" },
+    });
+
+    expect(event.kind).toBe("executor.started");
+    expect(event.requestId).toBe("req_1");
+    expect(event.executionId).toBe("exec_1");
+    expect(event.target).toEqual({ kind: "executor", id: "enei-1" });
+    expect(typeof event.timestamp).toBe("string");
+    expect(event.timestamp.length).toBeGreaterThan(0);
+  });
+
+  it("collects audit events in memory", () => {
+    const sink = createInMemoryAuditSink();
+    sink.observe(createAuditEvent({
+      kind: "program.validated",
+      requestId: "req_2",
+      executionId: "exec_2",
+      data: { issues: 0 },
+    }));
+
+    expect(sink.events).toHaveLength(1);
+    expect(sink.events[0]?.kind).toBe("program.validated");
+    expect(sink.events[0]?.data).toEqual({ issues: 0 });
+  });
+
+  it("normalizes execution target identifiers", () => {
+    expect(executionTargetId({
+      kind: "provider",
+      provider: "openrouter",
+      model: "google/gemma-4-31b-it",
+    })).toBe("openrouter/google/gemma-4-31b-it");
+
+    expect(executionTargetAuditRef({
+      kind: "executor",
+      executorId: "enei",
+      alias: "enei-1",
+    })).toEqual({
+      kind: "executor",
+      id: "enei/enei-1",
+    });
+  });
+
+  it("invokes nested executors without router re-entry and preserves request identity", async () => {
+    const sink = createInMemoryAuditSink();
+    const runtime = createExecutionRuntime({
+      observe: sink.observe,
+      executorImplementations: {
+        parent: {
+          async execute(request, ctx) {
+            const childResult = await ctx.invoke(request, {
+              target: { kind: "executor", executorId: "child", alias: "child" },
+            });
+            return childResult;
+          },
+          async *stream() {
+            return;
+          },
+        },
+        child: {
+          async execute(request) {
+            const result = cloneProgram(request);
+            result.code.push({
+              opcode: Opcode.RESP_DONE,
+              value: { kind: "string", value: "stop" },
+            });
+            return result;
+          },
+          async *stream() {
+            return;
+          },
+        },
+      },
+    });
+
+    const request = createProgram({
+      code: [
+        { opcode: Opcode.SET_MODEL, value: { kind: "string", value: "enei-1" } },
+      ],
+    });
+
+    const result = await runtime.execute(request, {
+      target: { kind: "executor", executorId: "parent", alias: "parent" },
+      requestId: "req_nested",
+      executionId: "exec_root",
+    });
+
+    expect(result.code.at(-1)).toEqual({
+      opcode: Opcode.RESP_DONE,
+      value: { kind: "string", value: "stop" },
+    });
+
+    const started = sink.events.filter((event) => event.kind === "executor.started");
+    expect(started).toHaveLength(2);
+    expect(started[0]?.requestId).toBe("req_nested");
+    expect(started[1]?.requestId).toBe("req_nested");
+    expect(started[1]?.parentExecutionId).toBe("exec_root");
+    expect(started[0]?.data?.depth).toBe(0);
+    expect(started[1]?.data?.depth).toBe(1);
+  });
+
+  it("applies target transforms before provider invocation", async () => {
+    const providerCalls: string[] = [];
+    const runtime = createExecutionRuntime({
+      providerInvoker: {
+        async execute(request) {
+          const marker = request.code.find((instruction) =>
+            instruction.opcode === Opcode.SET_META &&
+            instruction.value.kind === "key_string" &&
+            instruction.value.key === "transform",
+          );
+          providerCalls.push(
+            marker?.value.kind === "key_string" ? marker.value.value : "missing",
+          );
+          return cloneProgram(request);
+        },
+        async *stream() {
+          return;
+        },
+      },
+      transforms: {
+        slwin: {
+          name: "slwin",
+          capabilities: ["write_messages"],
+          apply(program) {
+            const result = cloneProgram(program);
+            result.code.push({
+              opcode: Opcode.SET_META,
+              value: { kind: "key_string", key: "transform", value: "slwin" },
+            });
+            return result;
+          },
+        },
+      },
+    });
+
+    await runtime.execute(createProgram(), {
+      target: {
+        kind: "provider",
+        provider: "openrouter",
+        model: "gpt-4o",
+        transforms: ["slwin"],
+      },
+    });
+
+    expect(providerCalls).toEqual(["slwin"]);
+  });
+
+  it("streams through the provider invoker", async () => {
+    const runtime = createExecutionRuntime({
+      providerInvoker: {
+        async execute() {
+          throw new Error("not used");
+        },
+        async *stream(request) {
+          yield cloneProgram(request);
+          yield createProgram({
+            code: [
+              { opcode: Opcode.STREAM_DELTA, value: { kind: "string", value: "hello" } },
+            ],
+          });
+        },
+      },
+    });
+
+    const outputs = [];
+    for await (const chunk of runtime.stream(createProgram(), {
+      target: { kind: "provider", provider: "openrouter", model: "gpt-4o" },
+    })) {
+      outputs.push(chunk);
+    }
+
+    expect(outputs).toHaveLength(2);
+    expect(outputs[1]?.code[0]).toEqual({
+      opcode: Opcode.STREAM_DELTA,
+      value: { kind: "string", value: "hello" },
+    });
+  });
+
+  it("enforces recursion limits with typed errors", async () => {
+    const sink = createInMemoryAuditSink();
+    const runtime = createExecutionRuntime({
+      observe: sink.observe,
+      maxDepth: 1,
+      executorImplementations: {
+        parent: {
+          async execute(request, ctx) {
+            return ctx.invoke(request, {
+              target: { kind: "executor", executorId: "child", alias: "child" },
+            });
+          },
+          async *stream() {
+            return;
+          },
+        },
+        child: {
+          async execute(request, ctx) {
+            return ctx.invoke(request, {
+              target: { kind: "executor", executorId: "leaf", alias: "leaf" },
+            });
+          },
+          async *stream() {
+            return;
+          },
+        },
+        leaf: {
+          async execute(request) {
+            return request;
+          },
+          async *stream() {
+            return;
+          },
+        },
+      },
+    });
+
+    await expect(runtime.execute(createProgram(), {
+      target: { kind: "executor", executorId: "parent", alias: "parent" },
+    })).rejects.toMatchObject({
+      kind: "recursion_limit",
+      stage: "target_resolution",
+    } satisfies Partial<ExecutionError>);
+
+    const failed = sink.events.find((event) => event.kind === "execution.failed");
+    expect(failed?.errorKind).toBe("recursion_limit");
+    expect(failed?.data?.depth).toBe(2);
+  });
+
+  it("validates request and stream chunk shapes with typed validation errors", async () => {
+    const runtime = createExecutionRuntime({
+      providerInvoker: {
+        async execute(request) {
+          return request;
+        },
+        async *stream() {
+          yield createProgram({
+            code: [
+              { opcode: Opcode.MSG_START, value: { kind: "none" } },
+            ],
+          });
+        },
+      },
+    });
+
+    await expect(runtime.execute(createProgram({
+      code: [
+        { opcode: Opcode.EXT_DATA, value: { kind: "key_json", key: "provider", value: new Uint8Array([123, 125]) } },
+      ],
+    }), {
+      target: { kind: "provider", provider: "openrouter", model: "gpt-4o" },
+    })).rejects.toMatchObject({
+      kind: "validation",
+      stage: "request",
+    } satisfies Partial<ExecutionError>);
+
+    const iterator = runtime.stream(createProgram(), {
+      target: { kind: "provider", provider: "openrouter", model: "gpt-4o" },
+    })[Symbol.asyncIterator]();
+    await expect(iterator.next()).rejects.toMatchObject({
+      kind: "validation",
+      stage: "stream_chunk",
+    } satisfies Partial<ExecutionError>);
+  });
+
+  it("observes text-first streams and tool-call streams", async () => {
+    const textObserved = await observeExecutionStream((async function* () {
+      yield createProgram({
+        code: [
+          { opcode: Opcode.STREAM_DELTA, value: { kind: "string", value: "hello" } },
+        ],
+      });
+      yield createProgram({
+        code: [
+          { opcode: Opcode.STREAM_DELTA, value: { kind: "string", value: " world" } },
+          { opcode: Opcode.RESP_DONE, value: { kind: "string", value: "stop" } },
+        ],
+      });
+    })());
+
+    expect(textObserved).toEqual({
+      mode: "text",
+      transcript: "hello world",
+      emittedText: true,
+    });
+
+    const toolObserved = await observeExecutionStream((async function* () {
+      yield createProgram({
+        code: [
+          { opcode: Opcode.STREAM_TOOL_DELTA, value: { kind: "json", value: new Uint8Array([123, 125]) } },
+        ],
+      });
+      yield createProgram({
+        code: [
+          { opcode: Opcode.RESP_DONE, value: { kind: "string", value: "tool_calls" } },
+        ],
+      });
+    })());
+
+    expect(toolObserved.mode).toBe("tool");
+    if (toolObserved.mode === "tool") {
+      expect(toolObserved.chunks).toHaveLength(2);
+      expect(toolObserved.emittedText).toBe(false);
+      expect(toolObserved.transcript).toBe("");
+    }
+  });
+});