@neutrome/open-ai-router 0.4.2 → 0.5.0

package/src/router/execute.ts

@@ -1,16 +1,12 @@
 import {
-  appendErrorBlock,
-  createProgram,
   emitChatCompletionsResponse,
   emitProviderError,
   emitProviderRequest,
   emitProviderResponse,
   emitProviderStreamChunk,
-  firstError,
   getModel,
   isStreaming,
   parseChatCompletionsRequest,
-  parseProviderError,
   parseProviderRequest,
   parseProviderResponse,
   parseProviderStreamChunk,
@@ -20,11 +16,32 @@ import {
   type ProviderStyle,
   usageObject,
 } from "@neutrome/lil-engine";
-import { withTools } from "@neutrome/lilsdk-ts/tools";
+import { createExecutionRuntime } from "./execution-runtime.ts";
+import { createFetchProviderInvoker } from "./provider-invoker.ts";
+import { ExecutionError, ProviderHttpError, RouterError } from "./errors.ts";
 import {
-  createExecutionRuntime,
-} from "./execution-runtime.ts";
-import { ExecutionError } from "./errors.ts";
+  errorProgramFromUnknown,
+  errorResponse,
+  toBody,
+  toProviderError,
+} from "./error-codec.ts";
+import {
+  createUpstreamSignal,
+  fetchProvider,
+  getProviderOrThrow,
+  normalizeUpstreamAbort,
+} from "./upstream-client.ts";
+import { emitProviderUsage, injectStreamUsage } from "./provider-telemetry.ts";
+import {
+  jsonExecutionResponse,
+  streamExecutionResponse,
+} from "./response-delivery.ts";
+import { prepareRemoteMcpExecution } from "./remote-mcp-execution.ts";
+import { parseRequestProgram } from "./request-program.ts";
+import {
+  resolveModelNamespaceExecutor,
+  resolveRequestTarget,
+} from "./request-target.ts";
 import type {
   ExecutionTarget,
   ExecutionRuntime,
@@ -34,18 +51,13 @@ import type {
   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 type { RequestContext } from "../upstream-auth/types.ts";
+import { isSse } from "../util/headers.ts";
 import { eventDataLines, splitSseEvents } from "../util/sse.ts";
-import { renderProgramAsLil } from "../observer.ts";
 import { resolveInvocationTarget, type ResolvedTarget } from "./resolve.ts";
-import {
-  createRemoteMcpToolSet,
-  type RemoteMcpClientFactory,
-} from "./mcp.ts";
+import type { RemoteMcpClientFactory } from "./mcp.ts";
 import type { ProviderRuntime, RouterRuntime } from "./runtime.ts";
-import { observeTimingEvent } from "../timing.ts";
+import { observeTimedExecution } from "./execution-events.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -87,26 +99,7 @@ export type HandleGoogleGenAIOptions = RouterExecutionOptions & {
   forceStreaming?: boolean;
 };
 
-export class RouterError extends Error {
-  constructor(
-    message: string,
-    readonly status: number,
-    readonly code: string,
-    readonly type = "invalid_request_error",
-  ) {
-    super(message);
-  }
-}
-
-export class ProviderHttpError extends Error {
-  constructor(
-    message: string,
-    readonly status: number,
-    readonly program: Program,
-  ) {
-    super(message);
-  }
-}
+export { ProviderHttpError, RouterError } from "./errors.ts";
 
 export function createRouterExecutionRuntime(
   runtime: RouterRuntime,
@@ -153,126 +146,73 @@ export function createRouterExecutionRuntime(
   return createExecutionRuntime(runtimeOptions);
 }
 
-function resolveModelNamespaceExecutor(
-  runtime: RouterRuntime,
-  name: string,
-): Executor | null {
-  const modelNamespace = runtime.modelNamespaces.get(name);
-  if (!modelNamespace) 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" });
-      const resolved = resolveInvocationTarget(runtime, `${name}/${model}`);
-      return ctx.invoke(request, { target: resolved.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" });
-      const resolved = resolveInvocationTarget(runtime, `${name}/${model}`);
-      yield* ctx.invokeStream(request, { target: resolved.target });
-    },
-  };
-}
-
 export async function handleChatCompletions(
   options: HandleChatCompletionsOptions,
 ): Promise<Response> {
-  try {
-    const request = options.program ?? await parseRequestProgram("chat-completions", options.ctx.request);
-    const incomingExecutionId = options.incomingExecutionId ?? `incoming_${crypto.randomUUID()}`;
-    emitObservedProgram(options.observe, "request.received", request, {
-      requestId: incomingExecutionId,
-      executionId: incomingExecutionId,
-    });
-    const resolved = resolveRequestTarget(options.runtime, request);
-    const remoteMcp = prepareRemoteMcpExecution(options.runtime, resolved, options);
-    const execution = createRouterExecutionRuntime(options.runtime, options.ctx, remoteMcp.options);
-
-    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) {
-        await remoteMcp.close();
-        throw error;
-      }
-    }
-
-    const startTime = Date.now();
-    try {
-      const response = await execution.execute(request, {
-        target: remoteMcp.target,
-      });
-      const userTime = Date.now() - startTime;
-      return jsonExecutionResponse(
-        emitChatCompletionsResponse(response),
-        resolved,
-        userTime,
-      );
-    } finally {
-      await remoteMcp.close();
-    }
-  } catch (error) {
-    return errorResponse(error, "chat-completions");
-  }
+  return handleRequestStyle(
+    "chat-completions",
+    options,
+    emitChatCompletionsResponse,
+  );
 }
 
 export async function handleResponses(
   options: HandleResponsesOptions,
 ): Promise<Response> {
-  return handleProviderStyle("responses", options);
+  return handleRequestStyle("responses", options, (program) =>
+    emitProviderResponse("responses", program),
+  );
 }
 
 export async function handleAnthropicMessages(
   options: HandleAnthropicMessagesOptions,
 ): Promise<Response> {
-  return handleProviderStyle("anthropic-messages", options);
+  return handleRequestStyle("anthropic-messages", options, (program) =>
+    emitProviderResponse("anthropic-messages", program),
+  );
 }
 
 export async function handleGoogleGenAI(
   options: HandleGoogleGenAIOptions,
 ): Promise<Response> {
-  return handleProviderStyle(
+  return handleRequestStyle(
     "google-genai",
     options,
-    options.forceStreaming ? (request) => setStreaming(request, true) : undefined,
+    (program) => emitProviderResponse("google-genai", program),
+    options.forceStreaming
+      ? (request) => setStreaming(request, true)
+      : undefined,
   );
 }
 
-async function handleProviderStyle(
-  style: Exclude<ProviderStyle, "chat-completions">,
+async function handleRequestStyle(
+  style: ProviderStyle,
   options: RouterExecutionOptions & {
     runtime: RouterRuntime;
     ctx: RequestContext;
     program?: Program;
   },
+  emitResponse: (program: Program) => Uint8Array,
   mutateRequest?: (request: Program) => Program,
 ): Promise<Response> {
   try {
-    const baseRequest = options.program ?? await parseRequestProgram(style, options.ctx.request);
+    const baseRequest =
+      options.program ??
+      (await parseRequestProgram(style, options.ctx.request));
     const request = mutateRequest ? mutateRequest(baseRequest) : baseRequest;
-    const incomingExecutionId = options.incomingExecutionId ?? `incoming_${crypto.randomUUID()}`;
-    emitObservedProgram(options.observe, "request.received", request, {
-      requestId: incomingExecutionId,
-      executionId: incomingExecutionId,
-    });
+    const incomingExecutionId =
+      options.incomingExecutionId ?? `incoming_${crypto.randomUUID()}`;
     const resolved = resolveRequestTarget(options.runtime, request);
-    const remoteMcp = prepareRemoteMcpExecution(options.runtime, resolved, options);
-    const execution = createRouterExecutionRuntime(options.runtime, options.ctx, remoteMcp.options);
+    const remoteMcp = prepareRemoteMcpExecution(
+      options.runtime,
+      resolved,
+      options,
+    );
+    const execution = createRouterExecutionRuntime(
+      options.runtime,
+      options.ctx,
+      remoteMcp.options,
+    );
 
     if (isStreaming(request)) {
       try {
@@ -302,11 +242,7 @@ async function handleProviderStyle(
         target: remoteMcp.target,
       });
       const userTime = Date.now() - startTime;
-      return jsonExecutionResponse(
-        emitProviderResponse(style, response),
-        resolved,
-        userTime,
-      );
+      return jsonExecutionResponse(emitResponse(response), resolved, userTime);
     } finally {
       await remoteMcp.close();
     }
@@ -315,798 +251,6 @@ async function handleProviderStyle(
   }
 }
 
-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",
-    );
-  }
-}
-
-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,
-  upstreamTimeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS,
-): ProviderInvoker {
-  return {
-    async execute(request, providerCtx) {
-      const provider = getProviderOrThrow(runtime, providerCtx.target.provider);
-      const timed = createUpstreamSignal(providerCtx.signal, upstreamTimeoutMs);
-
-      try {
-        const resolvedRequest = setModel(request, providerCtx.target.model);
-        emitObservedProgram(providerCtx.observe, "provider.request", resolvedRequest, {
-          requestId: providerCtx.requestId,
-          executionId: providerCtx.executionId,
-          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-          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, {
-            requestId: providerCtx.requestId,
-            executionId: providerCtx.executionId,
-            ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-            provider: provider.name,
-            model: providerCtx.target.model,
-          });
-          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,
-          executionId: providerCtx.executionId,
-          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-          provider: provider.name,
-          model: providerCtx.target.model,
-        });
-        emitProviderUsage(providerCtx, response, provider.name, reqBytes, bytes.byteLength);
-        return response;
-      } catch (error) {
-        throw normalizeUpstreamAbort(error, timed.signal);
-      } finally {
-        timed.cleanup();
-      }
-    },
-
-    async *stream(request, providerCtx) {
-      const provider = getProviderOrThrow(runtime, providerCtx.target.provider);
-      const timed = createUpstreamSignal(providerCtx.signal, upstreamTimeoutMs);
-      let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
-      let buffer = "";
-
-      try {
-        const resolvedRequest = setModel(request, providerCtx.target.model);
-        emitObservedProgram(providerCtx.observe, "provider.request", resolvedRequest, {
-          requestId: providerCtx.requestId,
-          executionId: providerCtx.executionId,
-          ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-          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, {
-            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(
-            `Provider ${provider.name} did not return an event stream`,
-            502,
-            "invalid_upstream_stream",
-          );
-        }
-
-        reader = upstream.body.getReader();
-        let firstByteObserved = false;
-        const streamReadStartedMs = Date.now();
-        let lastChunkWithUsage: Program | null = null;
-        let respBytes = 0;
-        while (true) {
-          const { done, value } = await reader.read();
-          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);
-          buffer = split.remainder;
-          for (const event of split.events) {
-            for (const data of eventDataLines(event)) {
-              if (data === "[DONE]") {
-                emitProviderUsage(providerCtx, lastChunkWithUsage, provider.name, reqBytes, respBytes);
-                return;
-              }
-              if (data[0] !== "{") continue;
-              const chunk = parseProviderStreamChunk(
-                provider.style,
-                encoder.encode(data),
-              );
-              if (usageObject(chunk) !== undefined) lastChunkWithUsage = chunk;
-              emitObservedProgram(providerCtx.observe, "provider.response_chunk", chunk, {
-                requestId: providerCtx.requestId,
-                executionId: providerCtx.executionId,
-                ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-                provider: provider.name,
-                model: providerCtx.target.model,
-              });
-              yield chunk;
-            }
-          }
-        }
-
-        if (buffer.length > 0) {
-          for (const data of eventDataLines(buffer)) {
-            if (data === "[DONE]") {
-              emitProviderUsage(providerCtx, lastChunkWithUsage, provider.name, reqBytes, respBytes);
-              return;
-            }
-            if (data[0] !== "{") continue;
-            const chunk = parseProviderStreamChunk(
-              provider.style,
-              encoder.encode(data),
-            );
-            if (usageObject(chunk) !== undefined) lastChunkWithUsage = chunk;
-            emitObservedProgram(providerCtx.observe, "provider.response_chunk", chunk, {
-              requestId: providerCtx.requestId,
-              executionId: providerCtx.executionId,
-              ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-              provider: provider.name,
-              model: providerCtx.target.model,
-            });
-            yield chunk;
-          }
-        }
-        emitProviderUsage(providerCtx, lastChunkWithUsage, provider.name, reqBytes, respBytes);
-      } catch (error) {
-        throw normalizeUpstreamAbort(error, timed.signal);
-      } finally {
-        await reader?.cancel().catch(() => {});
-        reader?.releaseLock();
-        timed.cleanup();
-      }
-    },
-  };
-}
-
-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>({
-      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),
-    },
-  });
-}
-
-function prepareRemoteMcpExecution(
-  runtime: RouterRuntime,
-  resolved: ResolvedTarget,
-  options: RouterExecutionOptions,
-): {
-  target: ExecutionTarget;
-  options: RouterExecutionOptions;
-  close: () => Promise<void>;
-} {
-  if (resolved.mcps.length === 0) {
-    return { target: resolved.target, options, close: async () => {} };
-  }
-
-  const remoteMcp = createRemoteMcpToolSet(
-    runtime,
-    resolved.mcps,
-    options.remoteMcpClientFactory,
-  );
-  if (remoteMcp.tools.length === 0) {
-    return { target: resolved.target, options, close: remoteMcp.close };
-  }
-
-  const executorName = `__remote_mcp_${crypto.randomUUID()}`;
-  return {
-    target: {
-      kind: "executor",
-      executorId: executorName,
-      alias: resolved.requestedModel,
-    },
-    options: {
-      ...options,
-      executorImplementations: {
-        ...(options.executorImplementations ?? {}),
-        [executorName]: withTools(remoteMcp.tools, resolved.target),
-      },
-    },
-    close: remoteMcp.close,
-  };
-}
-
-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),
-  };
-}
-
-async function fetchProvider(
-  runtime: RouterRuntime,
-  ctx: RequestContext,
-  provider: ProviderRuntime,
-  body: Uint8Array,
-  signal: AbortSignal,
-  providerCtx: ProviderInvocationContext,
-): Promise<Response> {
-  const headers = cloneForwardHeaders(ctx.request.headers);
-  headers.set("content-type", "application/json");
-  for (const [key, value] of Object.entries(provider.headers)) {
-    headers.set(key, value);
-  }
-
-  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;
-    }
-    new Headers(auth.headers).forEach((value, key) => headers.set(key, value));
-    break;
-  }
-
-  return runtime.fetchImpl(`${provider.apiBaseUrl}${provider.endpointPath}`, {
-    method: "POST",
-    headers,
-    body: toBody(body),
-    signal,
-  });
-}
-
-function getProviderOrThrow(runtime: RouterRuntime, providerName: string | undefined) {
-  if (!providerName) {
-    throw new RouterError(
-      "No provider specified on execution target",
-      500,
-      "provider_not_configured",
-    );
-  }
-  const provider = runtime.providers.get(providerName);
-  if (!provider) {
-    throw new RouterError(
-      `Provider ${providerName} is not configured`,
-      500,
-      "provider_not_configured",
-    );
-  }
-  return provider;
-}
-
-async function toProviderError(
-  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(
-    summary,
-    response.status,
-    program,
-  );
-}
-
-function errorResponse(error: unknown, responseStyle: ProviderStyle): Response {
-  if (error instanceof ProviderHttpError) {
-    return new Response(toBody(emitProviderError(responseStyle, error.program)), {
-      status: error.status,
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-      },
-    });
-  }
-
-  if (error instanceof RouterError) {
-    return emitErrorProgramResponse(routerErrorProgram(error), error.status, responseStyle);
-  }
-
-  if (error instanceof ExecutionError) {
-    const providerError = unwrapCause(error.cause, ProviderHttpError);
-    if (providerError) {
-      return errorResponse(providerError, responseStyle);
-    }
-    const nestedRouterError = unwrapCause(error.cause, RouterError);
-    if (nestedRouterError) {
-      return errorResponse(nestedRouterError, responseStyle);
-    }
-    const routerError = routerErrorFromExecutionError(error);
-    return emitErrorProgramResponse(routerErrorProgram(routerError), routerError.status, responseStyle);
-  }
-
-  console.error("[open-ai-router] unhandled error:", error);
-  return emitErrorProgramResponse(
-    appendErrorBlock(createProgram(), {
-      source: "router.internal",
-      kind: "invalid_request_error",
-      status: 500,
-      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":
-      return new RouterError(error.message, 400, "invalid_program");
-    case "resolution":
-      return new RouterError(error.message, 400, "target_resolution_failed");
-    case "cancellation":
-      return new RouterError(error.message, 499, "request_cancelled");
-    case "provider":
-      return new RouterError(error.message, 502, "provider_execution_failed");
-    case "transform":
-      return new RouterError(error.message, 500, "transform_failed");
-    case "executor":
-      return new RouterError(error.message, 500, "executor_failed");
-    case "stream":
-      return new RouterError(error.message, 500, "stream_failed");
-    case "recursion_limit":
-      return new RouterError(error.message, 500, "recursion_limit");
-  }
-}
-
-function unwrapCause<T extends Error>(
-  error: unknown,
-  ctor: new (...args: any[]) => T,
-): T | null {
-  let current = error;
-  while (current && typeof current === "object") {
-    if (current instanceof ctor) {
-      return current;
-    }
-    if (!("cause" in current)) {
-      return null;
-    }
-    current = (current as { cause?: unknown }).cause;
-  }
-  return null;
-}
-
-function toBody(bytes: Uint8Array): ArrayBuffer {
-  return bytes.buffer.slice(
-    bytes.byteOffset,
-    bytes.byteOffset + bytes.byteLength,
-  ) as ArrayBuffer;
-}
-
-function createUpstreamSignal(
-  signal: AbortSignal,
-  timeoutMs: number,
-): {
-  signal: AbortSignal;
-  cleanup(): void;
-} {
-  if (timeoutMs <= 0) {
-    return {
-      signal,
-      cleanup() {},
-    };
-  }
-
-  const controller = new AbortController();
-  const onAbort = () => controller.abort(signal.reason);
-  if (signal.aborted) {
-    onAbort();
-  } else {
-    signal.addEventListener("abort", onAbort, { once: true });
-  }
-
-  const timer = setTimeout(() => {
-    controller.abort(
-      new RouterError(
-        `Upstream provider timed out after ${timeoutMs}ms`,
-        504,
-        "upstream_timeout",
-      ),
-    );
-  }, timeoutMs);
-
-  return {
-    signal: controller.signal,
-    cleanup() {
-      clearTimeout(timer);
-      signal.removeEventListener("abort", onAbort);
-    },
-  };
-}
-
-function emitProviderUsage(
-  providerCtx: ProviderInvocationContext,
-  response: Program | null,
-  provider: string,
-  requestBytes: number,
-  responseBytes: number,
-): void {
-  const usage = response ? usageObject(response) : undefined;
-  const u = (usage && typeof usage === "object" ? usage : {}) as Record<string, unknown>;
-  const tokensInput = asNum(u.prompt_tokens) || asNum(u.input_tokens);
-  const tokensOutput = asNum(u.completion_tokens) || asNum(u.output_tokens);
-  const details = u.prompt_tokens_details as Record<string, unknown> | undefined;
-  const cachedTokensInput = details ? asNum(details.cached_tokens) : 0;
-  providerCtx.observe(createAuditEvent({
-    kind: "provider.usage",
-    requestId: providerCtx.requestId,
-    executionId: providerCtx.executionId,
-    ...(providerCtx.parentExecutionId ? { parentExecutionId: providerCtx.parentExecutionId } : {}),
-    data: {
-      provider,
-      model: providerCtx.target.model,
-      tokensInput,
-      tokensOutput,
-      cachedTokensInput,
-      requestBytes,
-      responseBytes,
-    },
-  }));
-}
-
-function asNum(v: unknown): number {
-  return typeof v === "number" && v >= 0 ? v : 0;
-}
-
-function injectStreamUsage(body: Uint8Array): Uint8Array {
-  try {
-    const obj = JSON.parse(decoder.decode(body)) as Record<string, unknown>;
-    obj.stream_options = { include_usage: true };
-    return encoder.encode(JSON.stringify(obj));
-  } catch {
-    return body;
-  }
-}
-
-function normalizeUpstreamAbort(error: unknown, signal: AbortSignal): unknown {
-  if (signal.aborted && signal.reason instanceof RouterError) {
-    return signal.reason;
-  }
-  return error;
-}
-
-function emitObservedProgram(
-  observe: ExecutionRuntimeOptions["observe"],
-  kind: string,
-  program: Program,
-  input: {
-    requestId: string;
-    executionId: string;
-    parentExecutionId?: string;
-    provider?: string;
-    model?: string;
-  },
-): void {
-  if (!observe) return;
-  observe(createAuditEvent({
-    kind,
-    requestId: input.requestId,
-    executionId: input.executionId,
-    ...(input.parentExecutionId ? { parentExecutionId: input.parentExecutionId } : {}),
-    data: {
-      ...(input.provider ? { provider: input.provider } : {}),
-      ...(input.model ? { model: input.model } : {}),
-      lilText: renderProgramAsLil(program),
-    },
-  }));
-}
+export { parseRequestProgram } from "./request-program.ts";
+export { resolveRequestTarget } from "./request-target.ts";
+export { createFetchProviderInvoker } from "./provider-invoker.ts";