@neutrome/open-ai-router 0.4.1 → 0.5.0

package/src/router/execution-runtime.ts

@@ -1,32 +1,45 @@
-import { cloneProgram, validateProgram } from "@neutrome/lil-engine";
+import { cloneProgram } from "@neutrome/lil-engine";
 import type { Program, ValidationMode } from "@neutrome/lil-engine";
 import type { ExecutorContext } from "@neutrome/lilsdk-ts";
-import { createAuditEvent } from "./audit.ts";
-import { ExecutionError, isExecutionError } from "./errors.ts";
-import { executionTargetAuditRef, executionTargetId } from "./targets.ts";
+import { validateProgramOrThrow as validateObservedProgram } from "./execution-observation.ts";
+import {
+  ensureActiveSignal as assertActiveSignal,
+  providerInvokerOrThrow as requireProviderInvoker,
+  resolveExecutorOrThrow as resolveRuntimeExecutor,
+  resolveTargetOrThrow as resolveRuntimeTarget,
+  throwIfRecursionExceeded as throwIfDepthExceeded,
+} from "./execution-resolution.ts";
+import {
+  invokeExecution,
+  streamExecution,
+  type InvocationOptions,
+} from "./execution-invocation.ts";
+import { applyExecutionTransforms } from "./execution-transforms.ts";
 import type {
-  AuditEvent,
   ExecutionRuntime,
   ExecutionRuntimeOptions,
   ExecutionTarget,
-  Executor,
   InvokeOptions,
-  ProgramTransform,
   ProviderInvocationContext,
-  ProviderInvoker,
 } from "./execution-types.ts";
 
 const DEFAULT_MAX_DEPTH = 8;
 
-export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): ExecutionRuntime {
+export function createExecutionRuntime(
+  options: ExecutionRuntimeOptions = {},
+): ExecutionRuntime {
   let requestCounter = 0;
   let executionCounter = 0;
 
-  const requestIdFactory = options.requestIdFactory ?? (() => `req_${++requestCounter}`);
-  const executionIdFactory = options.executionIdFactory ?? (() => `exec_${++executionCounter}`);
+  const requestIdFactory =
+    options.requestIdFactory ?? (() => `req_${++requestCounter}`);
+  const executionIdFactory =
+    options.executionIdFactory ?? (() => `exec_${++executionCounter}`);
   const observe = options.observe ?? (() => {});
   const fallbackSignal = options.signal ?? new AbortController().signal;
-  const executorImplementations = new Map(Object.entries(options.executorImplementations ?? {}));
+  const executorImplementations = new Map(
+    Object.entries(options.executorImplementations ?? {}),
+  );
   const transforms = new Map(Object.entries(options.transforms ?? {}));
   const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
   const validatePrograms = options.validatePrograms ?? true;
@@ -40,19 +53,19 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     },
   };
 
-  async function executeTarget(
+  async function prepareExecution(
     request: ReturnType<typeof cloneProgram>,
-    invokeOptions: InvokeOptions = {},
+    invokeOptions: InvokeOptions,
     depth: number,
   ) {
-    throwIfRecursionExceeded(depth);
+    throwIfDepthExceeded(depth, maxDepth);
     const requestId = invokeOptions.requestId ?? requestIdFactory();
     const executionId = invokeOptions.executionId ?? executionIdFactory();
     const parentExecutionId = invokeOptions.parentExecutionId;
     const signal = fallbackSignal;
-    const target = resolveTargetOrThrow(request, invokeOptions);
+    const target = resolveRuntimeTarget(options, request, invokeOptions);
 
-    ensureActiveSignal(signal, "request", target, depth);
+    assertActiveSignal(signal, target, depth, maxDepth);
     validateProgramOrThrow(request, {
       stage: "request",
       mode: "program",
@@ -64,287 +77,117 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
       emitSuccess: true,
     });
 
-    const transformed = applyTransforms(
-      request,
-      target,
+    return {
       requestId,
       executionId,
       parentExecutionId,
       signal,
-      depth,
-    );
-
-    if (target.kind === "executor") {
-      const executor = await getExecutorOrThrow(target.executorId);
-      const startedMs = Date.now();
-      const startedAt = new Date(startedMs).toISOString();
-      observe(createAuditEvent({
-        kind: "executor.started",
-        requestId,
-        executionId,
-        target: executionTargetAuditRef(target),
-        data: {
-          executorId: target.executorId,
-          alias: target.alias,
-          transforms: target.transforms ?? [],
-          depth,
-          maxDepth,
-          startedAt,
-        },
-        ...withParentExecutionId(parentExecutionId),
-      }));
-
-      try {
-        const result = await executor.execute(
-          transformed,
-          createExecutionContext(requestId, executionId, parentExecutionId, signal, depth),
-        );
-        validateProgramOrThrow(result, {
-          stage: "executor_result",
-          mode: "program",
+      target,
+      transformed: await applyExecutionTransforms({
+        program: request,
+        target,
+        transforms,
+        context: createExecutionContext(
           requestId,
           executionId,
           parentExecutionId,
-          target,
-          depth,
-          emitSuccess: true,
-        });
-        const finishedMs = Date.now();
-        observe(createAuditEvent({
-          kind: "executor.finished",
-          requestId,
-          executionId,
-          target: executionTargetAuditRef(target),
-          data: {
-            startedAt,
-            finishedAt: new Date(finishedMs).toISOString(),
-            durationMs: finishedMs - startedMs,
-          },
-          ...withParentExecutionId(parentExecutionId),
-        }));
-        return result;
-      } catch (error) {
-        const normalized = normalizeExecutionError(error, "executor", "executor_invoke", target, depth);
-        observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
-        throw normalized;
-      }
-    }
-
-    const providerInvoker = getProviderInvokerOrThrow();
-    const startedMs = Date.now();
-    const startedAt = new Date(startedMs).toISOString();
-    const providerCtx = createProviderInvocationContext(
-      requestId,
-      executionId,
-      parentExecutionId,
-      target,
-      signal,
-    );
-
-    observe(createAuditEvent({
-      kind: "provider.started",
-      requestId,
-      executionId,
-      target: executionTargetAuditRef(target),
-        data: {
-          model: target.model,
-          provider: target.provider ?? "",
-          transforms: target.transforms ?? [],
+          signal,
           depth,
-          maxDepth,
-          startedAt,
-      },
-      ...withParentExecutionId(parentExecutionId),
-    }));
-
-    try {
-      const result = await providerInvoker.execute(transformed, providerCtx);
-      validateProgramOrThrow(result, {
-        stage: "provider_result",
-        mode: "program",
+        ),
         requestId,
         executionId,
         parentExecutionId,
-        target,
         depth,
-        emitSuccess: true,
-      });
-      const finishedMs = Date.now();
-      observe(createAuditEvent({
-        kind: "provider.finished",
-        requestId,
-        executionId,
-        target: executionTargetAuditRef(target),
-        data: {
-          provider: target.provider ?? "",
-          model: target.model,
-          startedAt,
-          finishedAt: new Date(finishedMs).toISOString(),
-          durationMs: finishedMs - startedMs,
-        },
-        ...withParentExecutionId(parentExecutionId),
-      }));
-      return result;
-    } catch (error) {
-      const normalized = normalizeExecutionError(error, "provider", "provider_invoke", target, depth);
-      observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
-      throw normalized;
-    }
+        maxDepth,
+        observe,
+        validate: (program) =>
+          validateProgramOrThrow(program, {
+            stage: "transform_output",
+            mode: "program",
+            requestId,
+            executionId,
+            parentExecutionId,
+            target,
+            depth,
+            emitSuccess: true,
+          }),
+      }),
+    };
   }
 
-  async function* streamTarget(
+  async function executeTarget(
     request: ReturnType<typeof cloneProgram>,
     invokeOptions: InvokeOptions = {},
     depth: number,
   ) {
-    throwIfRecursionExceeded(depth);
-    const requestId = invokeOptions.requestId ?? requestIdFactory();
-    const executionId = invokeOptions.executionId ?? executionIdFactory();
-    const parentExecutionId = invokeOptions.parentExecutionId;
-    const signal = fallbackSignal;
-    const target = resolveTargetOrThrow(request, invokeOptions);
-
-    ensureActiveSignal(signal, "request", target, depth);
-    validateProgramOrThrow(request, {
-      stage: "request",
-      mode: "program",
-      requestId,
-      executionId,
-      parentExecutionId,
-      target,
-      depth,
-      emitSuccess: true,
-    });
-
-    const transformed = applyTransforms(
-      request,
-      target,
-      requestId,
-      executionId,
-      parentExecutionId,
-      signal,
-      depth,
+    return invokeExecution(
+      await prepareInvocation(request, invokeOptions, depth),
     );
+  }
 
-    if (target.kind === "executor") {
-      const executor = await getExecutorOrThrow(target.executorId);
-      const startedMs = Date.now();
-      const startedAt = new Date(startedMs).toISOString();
-      observe(createAuditEvent({
-        kind: "executor.stream_started",
-        requestId,
-        executionId,
-        target: executionTargetAuditRef(target),
-        data: {
-          executorId: target.executorId,
-          alias: target.alias,
-          transforms: target.transforms ?? [],
-          depth,
-          maxDepth,
-          startedAt,
-        },
-        ...withParentExecutionId(parentExecutionId),
-      }));
-
-      try {
-        for await (const chunk of executor.stream(
-          transformed,
-          createExecutionContext(requestId, executionId, parentExecutionId, signal, depth),
-        )) {
-          validateProgramOrThrow(chunk, {
-            stage: "stream_chunk",
-            mode: "stream_chunk",
-            requestId,
-            executionId,
-            parentExecutionId,
-            target,
-            depth,
-            emitSuccess: false,
-          });
-          yield chunk;
-        }
-        const finishedMs = Date.now();
-        observe(createAuditEvent({
-          kind: "executor.stream_finished",
-          requestId,
-          executionId,
-          target: executionTargetAuditRef(target),
-          data: {
-            startedAt,
-            finishedAt: new Date(finishedMs).toISOString(),
-            durationMs: finishedMs - startedMs,
-          },
-          ...withParentExecutionId(parentExecutionId),
-        }));
-        return;
-      } catch (error) {
-        const normalized = normalizeExecutionError(error, "stream", "stream_chunk", target, depth);
-        observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
-        throw normalized;
-      }
-    }
-
-    const providerInvoker = getProviderInvokerOrThrow();
-    const startedMs = Date.now();
-    const startedAt = new Date(startedMs).toISOString();
-    const providerCtx = createProviderInvocationContext(
-      requestId,
-      executionId,
-      parentExecutionId,
-      target,
-      signal,
+  async function* streamTarget(
+    request: ReturnType<typeof cloneProgram>,
+    invokeOptions: InvokeOptions = {},
+    depth: number,
+  ) {
+    yield* streamExecution(
+      await prepareInvocation(request, invokeOptions, depth),
     );
+  }
 
-    observe(createAuditEvent({
-      kind: "provider.stream_started",
-      requestId,
-      executionId,
-      target: executionTargetAuditRef(target),
-        data: {
-          model: target.model,
-          provider: target.provider ?? "",
-          transforms: target.transforms ?? [],
+  async function prepareInvocation(
+    request: Program,
+    invokeOptions: InvokeOptions,
+    depth: number,
+  ): Promise<InvocationOptions> {
+    const prepared = await prepareExecution(request, invokeOptions, depth);
+    const executor =
+      prepared.target.kind === "executor"
+        ? await resolveRuntimeExecutor(
+            options,
+            executorImplementations,
+            prepared.target.executorId,
+          )
+        : undefined;
+    return {
+      program: prepared.transformed,
+      identity: { ...prepared, depth },
+      signal: prepared.signal,
+      maxDepth,
+      observe,
+      executor,
+      providerInvoker:
+        prepared.target.kind === "provider"
+          ? requireProviderInvoker(options)
+          : undefined,
+      createExecutorContext: () =>
+        createExecutionContext(
+          prepared.requestId,
+          prepared.executionId,
+          prepared.parentExecutionId,
+          prepared.signal,
           depth,
-          maxDepth,
-          startedAt,
-      },
-      ...withParentExecutionId(parentExecutionId),
-    }));
-
-    try {
-      for await (const chunk of providerInvoker.stream(transformed, providerCtx)) {
-        validateProgramOrThrow(chunk, {
-          stage: "stream_chunk",
-          mode: "stream_chunk",
-          requestId,
-          executionId,
-          parentExecutionId,
+        ),
+      createProviderContext: (target) =>
+        createProviderInvocationContext(
+          prepared.requestId,
+          prepared.executionId,
+          prepared.parentExecutionId,
           target,
+          prepared.signal,
+        ),
+      validate: (program, stage, mode) =>
+        validateProgramOrThrow(program, {
+          stage,
+          mode,
+          requestId: prepared.requestId,
+          executionId: prepared.executionId,
+          parentExecutionId: prepared.parentExecutionId,
+          target: prepared.target,
           depth,
-          emitSuccess: false,
-        });
-        yield chunk;
-      }
-      const finishedMs = Date.now();
-      observe(createAuditEvent({
-        kind: "provider.stream_finished",
-        requestId,
-        executionId,
-        target: executionTargetAuditRef(target),
-        data: {
-          provider: target.provider ?? "",
-          model: target.model,
-          startedAt,
-          finishedAt: new Date(finishedMs).toISOString(),
-          durationMs: finishedMs - startedMs,
-        },
-        ...withParentExecutionId(parentExecutionId),
-      }));
-    } catch (error) {
-      const normalized = normalizeExecutionError(error, "stream", "stream_chunk", target, depth);
-      observeExecutionError(normalized, requestId, executionId, parentExecutionId, target, depth);
-      throw normalized;
-    }
+          emitSuccess: stage !== "stream_chunk",
+        }),
+    };
   }
 
   function createExecutionContext(
@@ -359,165 +202,30 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
       executionId,
       ...(parentExecutionId ? { parentExecutionId } : {}),
       async invoke(request, invokeOptions = {}) {
-        return executeTarget(cloneProgram(request), {
-          ...invokeOptions,
-          requestId,
-          parentExecutionId: executionId,
-        }, depth + 1);
-      },
-      async *invokeStream(request, invokeOptions = {}) {
-        yield* streamTarget(cloneProgram(request), {
-          ...invokeOptions,
-          requestId,
-          parentExecutionId: executionId,
-        }, depth + 1);
-      },
-      observe,
-      signal,
-    };
-  }
-
-  function applyTransforms(
-    program: ReturnType<typeof cloneProgram>,
-    target: ExecutionTarget,
-    requestId: string,
-    executionId: string,
-    parentExecutionId: string | undefined,
-    signal: AbortSignal,
-    depth: number,
-  ) {
-    let current = cloneProgram(program);
-    for (const transformName of target.transforms ?? []) {
-      const transform = transforms.get(transformName);
-      if (!transform) {
-        throw new ExecutionError(
-          "transform",
-          `Unknown transform: ${transformName}`,
+        return executeTarget(
+          cloneProgram(request),
           {
-            stage: "transform",
-            details: { transform: transformName, target: executionTargetId(target), depth, maxDepth },
-          },
-        );
-      }
-      try {
-        current = transform.apply(current, { observe, signal });
-      } catch (error) {
-        throw new ExecutionError(
-          "transform",
-          `Transform ${transform.name} failed`,
-          {
-            stage: "transform",
-            details: { transform: transform.name, target: executionTargetId(target), depth, maxDepth },
-            cause: error,
+            ...invokeOptions,
+            requestId,
+            parentExecutionId: executionId,
           },
+          depth + 1,
         );
-      }
-      validateProgramOrThrow(current, {
-        stage: "transform_output",
-        mode: "program",
-        requestId,
-        executionId,
-        parentExecutionId,
-        target,
-        depth,
-        emitSuccess: true,
-      });
-      observe(createAuditEvent({
-        kind: "transform.applied",
-        requestId,
-        executionId,
-        target: executionTargetAuditRef(target),
-        data: {
-          transform: transform.name,
-          target: executionTargetId(target),
-          depth,
-          maxDepth,
-        },
-        ...withParentExecutionId(parentExecutionId),
-      }));
-    }
-    return current;
-  }
-
-  function resolveTargetOrThrow(
-    request: ReturnType<typeof cloneProgram>,
-    invokeOptions: InvokeOptions,
-  ): ExecutionTarget {
-    if (invokeOptions.target) {
-      return invokeOptions.target;
-    }
-    if (options.resolveTarget) {
-      try {
-        return options.resolveTarget(request, invokeOptions);
-      } catch (error) {
-        throw new ExecutionError(
-          "resolution",
-          error instanceof Error ? error.message : "Execution target resolution failed",
+      },
+      async *invokeStream(request, invokeOptions = {}) {
+        yield* streamTarget(
+          cloneProgram(request),
           {
-            stage: "target_resolution",
-            cause: error,
+            ...invokeOptions,
+            requestId,
+            parentExecutionId: executionId,
           },
+          depth + 1,
         );
-      }
-    }
-    throw new ExecutionError("resolution", "No execution target specified", {
-      stage: "target_resolution",
-    });
-  }
-
-  async function getExecutorOrThrow(name: string): Promise<Executor> {
-    const cached = executorImplementations.get(name);
-    if (cached) {
-      return cached;
-    }
-
-    const resolved = await options.resolveExecutor?.(name);
-    if (resolved) {
-      executorImplementations.set(name, resolved);
-      return resolved;
-    }
-
-    const executor = executorImplementations.get(name);
-    if (!executor) {
-      throw new ExecutionError("resolution", `Unknown executor: ${name}`, {
-        stage: "target_resolution",
-      });
-    }
-    return executor;
-  }
-
-  function getProviderInvokerOrThrow(): ProviderInvoker {
-    if (!options.providerInvoker) {
-      throw new ExecutionError("provider", "No provider invoker configured", {
-        stage: "provider_invoke",
-      });
-    }
-    return options.providerInvoker;
-  }
-
-  function observeExecutionError(
-    error: ExecutionError,
-    requestId: string,
-    executionId: string,
-    parentExecutionId: string | undefined,
-    target: ExecutionTarget,
-    depth: number,
-  ): void {
-    observe(createAuditEvent({
-      kind: "execution.failed",
-      requestId,
-      executionId,
-      target: executionTargetAuditRef(target),
-      errorKind: error.kind,
-      data: {
-        message: error.message,
-        stage: error.stage,
-        depth,
-        maxDepth,
-        ...(error.details ?? {}),
       },
-      ...withParentExecutionId(parentExecutionId),
-    }));
+      observe,
+      signal,
+    };
   }
 
   function createProviderInvocationContext(
@@ -546,24 +254,15 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
     return { parentExecutionId };
   }
 
-  function throwIfRecursionExceeded(depth: number): void {
-    if (depth <= maxDepth) {
-      return;
-    }
-    throw new ExecutionError(
-      "recursion_limit",
-      `Execution recursion depth ${depth} exceeds maxDepth ${maxDepth}`,
-      {
-        stage: "target_resolution",
-        details: { depth, maxDepth },
-      },
-    );
-  }
-
   function validateProgramOrThrow(
     program: Program,
     context: {
-      stage: "request" | "transform_output" | "provider_result" | "executor_result" | "stream_chunk";
+      stage:
+        | "request"
+        | "transform_output"
+        | "provider_result"
+        | "executor_result"
+        | "stream_chunk";
       mode: ValidationMode;
       requestId: string;
       executionId: string;
@@ -573,100 +272,10 @@ export function createExecutionRuntime(options: ExecutionRuntimeOptions = {}): E
       emitSuccess: boolean;
     },
   ): void {
-    if (!validatePrograms) {
-      return;
-    }
-
-    const result = validateProgram(program, { mode: context.mode });
-    if (!result.ok) {
-      throw new ExecutionError(
-        "validation",
-        `Program validation failed during ${context.stage}`,
-        {
-          stage: context.stage,
-          details: {
-            issues: result.issues,
-            depth: context.depth,
-            maxDepth,
-            target: executionTargetId(context.target),
-          },
-        },
-      );
-    }
-
-    if (context.emitSuccess) {
-      observe(createAuditEvent({
-        kind: "program.validated",
-        requestId: context.requestId,
-        executionId: context.executionId,
-        target: executionTargetAuditRef(context.target),
-        data: {
-          stage: context.stage,
-          mode: context.mode,
-          issues: 0,
-          depth: context.depth,
-          maxDepth,
-        },
-        ...withParentExecutionId(context.parentExecutionId),
-      }));
-    }
-  }
-
-  function ensureActiveSignal(
-    signal: AbortSignal,
-    stage: "request",
-    target: ExecutionTarget,
-    depth: number,
-  ): void {
-    if (!signal.aborted) {
-      return;
-    }
-    throw new ExecutionError(
-      "cancellation",
-      "Execution aborted",
-      {
-        stage,
-        details: { depth, maxDepth, target: executionTargetId(target) },
-        cause: signal.reason,
-      },
-    );
-  }
-
-  function normalizeExecutionError(
-    error: unknown,
-    fallbackKind: "provider" | "executor" | "stream",
-    fallbackStage: "provider_invoke" | "executor_invoke" | "stream_chunk",
-    target: ExecutionTarget,
-    depth: number,
-  ): ExecutionError {
-    if (isExecutionError(error)) {
-      return error;
-    }
-    if (isAbortLike(error)) {
-      return new ExecutionError(
-        "cancellation",
-        "Execution aborted",
-        {
-          stage: fallbackStage,
-          details: { depth, maxDepth, target: executionTargetId(target) },
-          cause: error,
-        },
-      );
-    }
-    return new ExecutionError(
-      fallbackKind,
-      error instanceof Error ? error.message : String(error),
-      {
-        stage: fallbackStage,
-        details: { depth, maxDepth, target: executionTargetId(target) },
-        cause: error,
-      },
-    );
-  }
-
-  function isAbortLike(error: unknown): boolean {
-    return error instanceof DOMException
-      ? error.name === "AbortError"
-      : error instanceof Error && error.name === "AbortError";
+    validateObservedProgram(program, context, {
+      enabled: validatePrograms,
+      maxDepth,
+      observe,
+    });
   }
 }