@neutrome/open-ai-router 0.8.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/open-ai-router",
-  "version": "0.8.1",
+  "version": "0.9.2",
   "type": "module",
   "files": [
     "src",
@@ -17,7 +17,7 @@
     "posthog-node": "^5.41.0",
     "zod": "^4.2.1",
     "@neutrome/lil-engine": "0.6.1",
-    "@neutrome/lilsdk": "0.6.1"
+    "@neutrome/lilsdk": "0.6.2"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/app/factory.test.ts

@@ -150,8 +150,14 @@ describe("createRouterApp trace finalization", () => {
       expect.objectContaining({
         requestedModel: "gpt-4o",
         outcome: "ok",
-        inputTokens: expect.any(Number),
-        outputTokens: expect.any(Number),
+        invocations: expect.arrayContaining([
+          expect.objectContaining({
+            kind: "incoming",
+            model: "gpt-4o",
+            inputTokens: expect.any(Number),
+            outputTokens: expect.any(Number),
+          }),
+        ]),
       }),
       {},
     );

package/src/app/factory.ts

@@ -297,6 +297,9 @@ export function createRouterApp(options: RouterAppOptions) {
         onUserResponse(result) {
           usage.setResult(result);
         },
+        onNamedInvocation(result) {
+          usage.recordInvocation(result);
+        },
         ...(options.upstreamTimeoutMs !== undefined
           ? { upstreamTimeoutMs: options.upstreamTimeoutMs }
           : {}),

package/src/app/user-usage-collector.ts

@@ -1,15 +1,17 @@
 import type { Program, ProviderStyle } from "@neutrome/lil-engine";
 import type { ExecutionSummary } from "../telemetry/index.ts";
+import type { NamedInvocationResult } from "../router/execution-types.ts";
 import {
   countUserProgramTokens,
+  createStreamUsageAccumulator,
   toolUsageFromEvents,
   type UserUsageReport,
 } from "../usage/user-usage.ts";
 
 export type UserResponseResult = Pick<
   UserUsageReport,
-  "outputTokens" | "outcome" | "httpStatus" | "error"
->;
+  "outcome" | "httpStatus" | "error"
+> & { outputTokens: number };
 
 export function createUserUsageCollector(input: {
   requestId: string;
@@ -19,6 +21,7 @@ export function createUserUsageCollector(input: {
   let inputTokens = 0;
   let requestedModel: string | null = null;
   let result: UserResponseResult | null = null;
+  const invocations: UserUsageReport["invocations"] = [];
   return {
     setRequest(program: Program, model: string | null) {
       inputTokens = countUserProgramTokens(program);
@@ -30,15 +33,42 @@ export function createUserUsageCollector(input: {
     inputTokens() {
       return inputTokens;
     },
+    recordInvocation(invocation: NamedInvocationResult) {
+      const accumulator = createStreamUsageAccumulator();
+      for (const chunk of invocation.stream ?? []) accumulator.add(chunk);
+      invocations.push({
+        executionId: invocation.executionId,
+        parentExecutionId: invocation.parentExecutionId ?? null,
+        kind: invocation.kind,
+        model: invocation.model,
+        inputTokens: countUserProgramTokens(invocation.input),
+        outputTokens: invocation.stream
+          ? accumulator.count()
+          : invocation.output
+            ? countUserProgramTokens(invocation.output)
+            : 0,
+        startedAt: new Date(invocation.startedAtMs).toISOString(),
+        finishedAt: new Date(invocation.finishedAtMs).toISOString(),
+        durationMs: Math.max(
+          0,
+          invocation.finishedAtMs - invocation.startedAtMs,
+        ),
+        outcome: invocation.outcome,
+        error: invocation.error ?? null,
+      });
+    },
     report(summary: ExecutionSummary): UserUsageReport {
       const finishedAt = new Date().toISOString();
+      const response =
+        result ?? responseResult(null, "Request did not produce a response");
       return {
         requestId: input.requestId,
         protocol: input.protocol,
         requestedModel,
-        inputTokens,
-        ...(result ??
-          responseResult(null, "Request did not produce a response")),
+        invocations: [...invocations],
+        outcome: response.outcome,
+        httpStatus: response.httpStatus,
+        error: response.error,
         tools: toolUsageFromEvents(
           summary.spans
             .filter((span) => span.kind === "tool" && span.toolName)

package/src/router/execute.ts

@@ -82,6 +82,7 @@ export type RouterExecutionOptions = Pick<
   remoteMcpClientFactory?: RemoteMcpClientFactory;
   incomingExecutionId?: string;
   userUsage?: { inputTokens: number };
+  onNamedInvocation?: ExecutionRuntimeOptions["onNamedInvocation"];
   onUserResponse?: (result: {
     outputTokens: number;
     outcome: "ok" | "error" | "cancelled";
@@ -156,6 +157,18 @@ export function createRouterExecutionRuntime(
   if (options.executionIdFactory) {
     runtimeOptions.executionIdFactory = options.executionIdFactory;
   }
+  runtimeOptions.isBillableModel = (model) => {
+    try {
+      return runtime.modelNamespaces.has(
+        resolveNestedInvocationTarget(runtime, model).namespace,
+      );
+    } catch {
+      return false;
+    }
+  };
+  if (options.onNamedInvocation) {
+    runtimeOptions.onNamedInvocation = options.onNamedInvocation;
+  }
 
   const userResolveExecutor = options.resolveExecutor;
   runtimeOptions.resolveExecutor = (name: string) => {
@@ -239,7 +252,15 @@ async function handleRequestStyle(
     if (isStreaming(request)) {
       try {
         const responseStartedMs = Date.now();
-        const chunks = execution.stream(request, { target: remoteMcp.target });
+        const rootBillable = options.runtime.modelNamespaces.has(
+          resolved.namespace,
+        );
+        const chunks = execution.stream(request, {
+          target: remoteMcp.target,
+          requestId: incomingExecutionId,
+          executionId: incomingExecutionId,
+          ...(rootBillable ? { namedModel: resolved.requestedModel } : {}),
+        });
         return await streamExecutionResponse(
           style,
           chunks,
@@ -266,6 +287,11 @@ async function handleRequestStyle(
     try {
       const response = await execution.execute(request, {
         target: remoteMcp.target,
+        requestId: incomingExecutionId,
+        executionId: incomingExecutionId,
+        ...(options.runtime.modelNamespaces.has(resolved.namespace)
+          ? { namedModel: resolved.requestedModel }
+          : {}),
       });
       const userTime = Date.now() - startTime;
       const outputTokens = countUserProgramTokens(response);

package/src/router/execution-invocation.ts

@@ -13,6 +13,7 @@ import type {
   ProviderInvocationContext,
   ProviderInvoker,
 } from "./execution-types.ts";
+import type { NamedInvocationResult } from "./execution-types.ts";
 
 type InvocationIdentity = {
   requestId: string;
@@ -39,6 +40,11 @@ export type InvocationOptions = {
     stage: "provider_result" | "executor_result" | "stream_chunk",
     mode: ValidationMode,
   ): void;
+  namedInvocation?: Omit<
+    NamedInvocationResult,
+    "output" | "stream" | "finishedAtMs" | "outcome" | "error"
+  >;
+  onNamedInvocation?(result: NamedInvocationResult): void;
 };
 
 export async function invokeExecution(
@@ -55,8 +61,10 @@ export async function invokeExecution(
     const result = await primitive.execute(options.program);
     options.validate(result, primitive.resultStage, "program");
     finishInvocation(options.identity, timing, false, options.observe);
+    finishNamed(options, { output: result, outcome: "ok" });
     return result;
   } catch (error) {
+    finishNamed(options, failureResult(error));
     throw observedFailure(
       options,
       error,
@@ -76,17 +84,51 @@ export async function* streamExecution(
     true,
     options.observe,
   );
+  const chunks: Program[] = [];
   try {
     for await (const chunk of primitive.stream(options.program)) {
       options.validate(chunk, "stream_chunk", "stream_chunk");
+      if (options.namedInvocation) chunks.push(chunk);
       yield chunk;
     }
     finishInvocation(options.identity, timing, true, options.observe);
+    finishNamed(options, { stream: chunks, outcome: "ok" });
   } catch (error) {
+    finishNamed(options, { ...failureResult(error), stream: chunks });
     throw observedFailure(options, error, "stream", "stream_chunk");
   }
 }
 
+function finishNamed(
+  options: InvocationOptions,
+  result: Pick<NamedInvocationResult, "outcome"> &
+    Partial<Pick<NamedInvocationResult, "output" | "stream" | "error">>,
+): void {
+  if (!options.namedInvocation || !options.onNamedInvocation) return;
+  options.onNamedInvocation({
+    ...options.namedInvocation,
+    ...result,
+    finishedAtMs: Date.now(),
+  });
+}
+
+function failureResult(
+  error: unknown,
+): Pick<NamedInvocationResult, "outcome" | "error"> {
+  const cancelled =
+    error instanceof DOMException
+      ? error.name === "AbortError"
+      : error instanceof Error &&
+        (error.name === "AbortError" || error.message === "Execution aborted");
+  return {
+    outcome: cancelled ? "cancelled" : "error",
+    error: (error instanceof Error ? error.message : String(error)).slice(
+      0,
+      500,
+    ),
+  };
+}
+
 function invocationPrimitive(options: InvocationOptions): {
   execute(program: Program): Promise<Program>;
   stream(program: Program): AsyncIterable<Program>;

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

@@ -20,6 +20,67 @@ import {
 import { observeExecutionStream } from "@neutrome/lilsdk/stream";
 
 describe("router execution runtime", () => {
+  it("records only named boundaries through anonymous executor fan-out", async () => {
+    const named: Array<{
+      executionId: string;
+      parentExecutionId?: string;
+      kind: "incoming" | "subrequest";
+      model: string;
+    }> = [];
+    const leaf = {
+      async execute(program: Program) {
+        return program;
+      },
+      async *stream() {},
+    };
+    const anonymousInner = {
+      async execute(program: Program, ctx: ExecutorContext) {
+        return ctx.invoke("namespace/model-b", program);
+      },
+      async *stream() {},
+    };
+    const anonymousOuter = {
+      async execute(program: Program, ctx: ExecutorContext) {
+        return ctx.invoke(anonymousInner, program);
+      },
+      async *stream() {},
+    };
+    const runtime = createExecutionRuntime({
+      executorImplementations: {
+        root: {
+          async execute(program, ctx) {
+            return ctx.invoke(anonymousOuter, program);
+          },
+          async *stream() {},
+        },
+        leaf,
+      },
+      resolveTarget(request) {
+        return getModel(request) === "namespace/model-b"
+          ? { kind: "executor", executorId: "leaf", alias: "model-b" }
+          : { kind: "executor", executorId: "root", alias: "model-a" };
+      },
+      onNamedInvocation(result) {
+        named.push(result);
+      },
+    });
+
+    await runtime.execute(createProgram(), {
+      executionId: "model-a-execution",
+      namedModel: "namespace/model-a",
+    });
+
+    expect(named).toHaveLength(2);
+    expect(named.find((item) => item.kind === "incoming")).toMatchObject({
+      executionId: "model-a-execution",
+      model: "namespace/model-a",
+    });
+    expect(named.find((item) => item.kind === "subrequest")).toMatchObject({
+      parentExecutionId: "model-a-execution",
+      model: "namespace/model-b",
+    });
+  });
+
   it("shares one cache with transforms and executors", async () => {
     const values = new Map<string, string>();
     const cache = {

package/src/router/execution-runtime.ts

@@ -146,6 +146,10 @@ export function createExecutionRuntime(
     depth: number,
   ): Promise<InvocationOptions> {
     const prepared = await prepareExecution(request, invokeOptions, depth);
+    const namedModel = invokeOptions.namedModel;
+    const billable =
+      namedModel !== undefined &&
+      (options.isBillableModel?.(namedModel) ?? true);
     const executor =
       prepared.target.kind === "executor"
         ? await resolveRuntimeExecutor(
@@ -172,6 +176,9 @@ export function createExecutionRuntime(
           prepared.parentExecutionId,
           prepared.signal,
           depth,
+          billable
+            ? prepared.executionId
+            : invokeOptions.namedParentExecutionId,
         ),
       createProviderContext: (target) =>
         createProviderInvocationContext(
@@ -192,6 +199,22 @@ export function createExecutionRuntime(
           depth,
           emitSuccess: stage !== "stream_chunk",
         }),
+      ...(billable
+        ? {
+            namedInvocation: {
+              executionId: prepared.executionId,
+              ...(invokeOptions.namedParentExecutionId
+                ? { parentExecutionId: invokeOptions.namedParentExecutionId }
+                : {}),
+              kind:
+                depth === 0 ? ("incoming" as const) : ("subrequest" as const),
+              model: namedModel,
+              input: cloneProgram(request),
+              startedAtMs: Date.now(),
+            },
+            onNamedInvocation: options.onNamedInvocation,
+          }
+        : {}),
     };
   }
 
@@ -201,6 +224,7 @@ export function createExecutionRuntime(
     parentExecutionId: string | undefined,
     signal: AbortSignal,
     depth: number,
+    namedParentExecutionId?: string,
   ): ExecutorContext {
     return {
       cache: options.cache ?? unavailableCache,
@@ -218,12 +242,18 @@ export function createExecutionRuntime(
               executionId,
               signal,
               depth + 1,
+              namedParentExecutionId,
             ),
           );
         }
         return executeTarget(
           setModel(cloneProgram(request), executor),
-          { requestId, parentExecutionId: executionId },
+          {
+            requestId,
+            parentExecutionId: executionId,
+            namedModel: executor,
+            ...(namedParentExecutionId ? { namedParentExecutionId } : {}),
+          },
           depth + 1,
         );
       },
@@ -238,13 +268,19 @@ export function createExecutionRuntime(
               executionId,
               signal,
               depth + 1,
+              namedParentExecutionId,
             ),
           );
           return;
         }
         yield* streamTarget(
           setModel(cloneProgram(request), executor),
-          { requestId, parentExecutionId: executionId },
+          {
+            requestId,
+            parentExecutionId: executionId,
+            namedModel: executor,
+            ...(namedParentExecutionId ? { namedParentExecutionId } : {}),
+          },
           depth + 1,
         );
       },

package/src/router/execution-types.ts

@@ -30,6 +30,22 @@ export type InvokeOptions = {
   requestId?: string;
   executionId?: string;
   parentExecutionId?: string;
+  namedModel?: string;
+  namedParentExecutionId?: string;
+};
+
+export type NamedInvocationResult = {
+  executionId: string;
+  parentExecutionId?: string;
+  kind: "incoming" | "subrequest";
+  model: string;
+  input: Program;
+  output?: Program;
+  stream?: readonly Program[];
+  startedAtMs: number;
+  finishedAtMs: number;
+  outcome: "ok" | "error" | "cancelled";
+  error?: string;
 };
 
 export type ProviderInvocationContext = {
@@ -71,6 +87,8 @@ export type ExecutionRuntimeOptions = {
   executionIdFactory?: () => string;
   maxDepth?: number;
   validatePrograms?: boolean;
+  isBillableModel?(model: string): boolean;
+  onNamedInvocation?(result: NamedInvocationResult): void;
 };
 
 export type ExecutionRuntime = {

package/src/usage/user-usage.ts

@@ -16,8 +16,7 @@ export type UserUsageReport = {
   requestId: string;
   protocol: ProviderStyle;
   requestedModel: string | null;
-  inputTokens: number;
-  outputTokens: number;
+  invocations: UserModelInvocation[];
   tools: UserToolUsage[];
   startedAt: string;
   finishedAt: string;
@@ -27,6 +26,20 @@ export type UserUsageReport = {
   error: string | null;
 };
 
+export type UserModelInvocation = {
+  executionId: string;
+  parentExecutionId: string | null;
+  kind: "incoming" | "subrequest";
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  startedAt: string;
+  finishedAt: string;
+  durationMs: number;
+  outcome: UserUsageOutcome;
+  error: string | null;
+};
+
 /** Counts semantic LIL content, never transport JSON, settings, model ids, or usage. */
 export function countUserProgramTokens(program: Program): number {
   return encode(semanticProgramText(program), { disallowedSpecial: "all" })