@x12i/ai-dispatcher 2.0.0 → 2.2.0

package/README.md

@@ -4,7 +4,7 @@ One request shape for OpenRouter, AWS Bedrock, the OpenAI Responses API, and Clo
 
 **Implemented providers:** `openrouter`, `bedrock`, `openai`, `cloudflare`. Any other provider throws `PROVIDER_NOT_IMPLEMENTED`.
 
-The package is `@x12i/ai-dispatcher` 2.0.0. It runs on Node 20 or newer and publishes ESM and CommonJS from the same entry.
+The package is `@x12i/ai-dispatcher` 2.2.0. It runs on Node 20 or newer and publishes ESM and CommonJS from the same entry.
 
 Connected MCP servers can be passed to `createAiDispatcher`. `run()` and `compile()` expose those tools to the model. `executeStreamingChat` does not. Details are in [MCP tools](#mcp-tools).
 
@@ -14,7 +14,7 @@ Connected MCP servers can be passed to `createAiDispatcher`. `run()` and `compil
 npm install @x12i/ai-dispatcher
 ```
 
-The package depends on `@x12i/ai-profiles@5.0.0`, `@x12i/openrouter-runtime@^2.0.0`, and `@x12i/bedrock-runtime@^2.0.0`.
+The package depends on `@x12i/ai-profiles@5.0.0`, `@x12i/provider-metadata@^1.2.0`, `@x12i/openrouter-runtime@^2.2.0`, and `@x12i/bedrock-runtime@^2.2.0`.
 
 ## One request
 
@@ -177,7 +177,9 @@ const record = decodeProviderMetadata(logMetadata);
 
 `metadata` is the one record. When `rawOpenRouterOverrides` only repeats `metadata`, the dispatcher folds it in. `metadata` wins when the same key is in both places. String, number, and boolean values are stored, including a JSON string. Objects and arrays stay on the normalized response and the tool context.
 
-Every provider writes that record as `m.0`, `m.1`, and so on: one base64 string, 256 characters per piece, at most 16 pieces. The base64 is the UTF-8 JSON object of the string map, with keys sorted. `decodeProviderMetadata` reads those pieces from OpenRouter body `metadata`, OpenAI Responses `metadata`, Bedrock `requestMetadata`, or Cloudflare body `metadata` and `cf-aig-metadata`. The pieces are the same on every provider. A larger record throws `METADATA_RECORD_TOO_LARGE`.
+Every provider writes that record as `m.0`, `m.1`, and so on: one base64 string, 256 characters per piece, at most 16 pieces. The base64 is the UTF-8 JSON object of the string map, with keys sorted. `decodeProviderMetadata` reads those pieces from OpenRouter body `metadata`, OpenAI Responses `metadata`, Bedrock `requestMetadata`, or Cloudflare body `metadata` and `cf-aig-metadata`. The pieces are the same on every provider. The dispatcher trims on every call. Pass `metadataPriority` (highest priority first) to choose what stays. The default keeps `agentId`, `orgId`, `stepId`, `skillId`, `recordId`, and `objectType`. A trimmed call adds a `METADATA_RECORD_TRIMMED` warning.
+
+Repeating vendor fields normalize to one key. Prefer `metadata.api_key_name` over `metadata.openrouter.api_key_name`. `normalizeMetadata` and `decodeProviderMetadata` promote known aliases and keep the vendor key. Grow `METADATA_NORMALIZATION_MAP` as more shared fields appear.
 
 OpenRouter also puts `agentId` in `X-Title` and `X-OpenRouter-Title`, ahead of `appAttribution.appName` and `defaultHeaders`. That header is the activity-log App name. `appAttribution.siteUrl` is still `HTTP-Referer` when set. The App header is not a second metadata record.
 

package/dist/index.cjs

@@ -21,10 +21,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AiDispatcherError: () => AiDispatcherError,
+  DEFAULT_METADATA_PRIORITY: () => DEFAULT_METADATA_PRIORITY,
   IMPLEMENTED_AI_PROVIDERS: () => IMPLEMENTED_AI_PROVIDERS,
+  METADATA_NORMALIZATION_MAP: () => import_openrouter_runtime4.METADATA_NORMALIZATION_MAP,
+  canonicalMetadataKey: () => import_openrouter_runtime4.canonicalMetadataKey,
   createAiDispatcher: () => createAiDispatcher,
   decodeProviderMetadata: () => import_openrouter_runtime4.decodeProviderMetadata,
   isImplementedAiProvider: () => isImplementedAiProvider,
+  normalizeMetadata: () => import_openrouter_runtime4.normalizeMetadata,
   providerNotImplemented: () => providerNotImplemented,
   resolveProvider: () => resolveProvider,
   stripReasoningHistoryFields: () => stripReasoningHistoryFields
@@ -32,6 +36,9 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_openrouter_runtime4 = require("@x12i/openrouter-runtime");
 
+// src/create-dispatcher.ts
+var import_provider_metadata = require("@x12i/provider-metadata");
+
 // src/cache-usage.ts
 function readCacheTokens(source) {
   const cached = [];
@@ -1178,8 +1185,8 @@ function restoreCloudflareModel(model, prefix) {
   if (!prefix || model.includes("/")) return model;
   return `${prefix}${model}`;
 }
-function createCloudflareProviderAdapter(options = {}) {
-  const resolved = resolveCloudflareOptions(options);
+function createCloudflareProviderAdapter(options = {}, packer) {
+  const resolved = resolveCloudflareOptions(options, packer);
   return {
     compile(request, call) {
       return compileCloudflareRequest(request, resolved, call, false);
@@ -1232,12 +1239,13 @@ function compileCloudflareRequest(request, options, call, streaming) {
   if (endpoint !== "run") body = { ...body, stream: streaming };
   const gateway = mergeGateway(options.gateway, call?.cloudflare?.gateway);
   const fromBody = isRecord5(body.metadata) ? body.metadata : void 0;
-  const record2 = (0, import_openrouter_runtime.toProviderMetadata)(
+  const packed = (0, import_openrouter_runtime.packProviderRecord)(
     request.metadata,
     request.agentId,
-    import_openrouter_runtime.OPENROUTER_METADATA_LIMITS,
-    overlayMetadata(gateway?.metadata, fromBody)
+    overlayMetadata(gateway?.metadata, fromBody),
+    options.metadataPacker
   );
+  const record2 = packed.wire;
   body = applyProviderRecord(body, record2);
   if (endpoint === "run") body = wrapRun(body, run);
   return {
@@ -1245,7 +1253,7 @@ function compileCloudflareRequest(request, options, call, streaming) {
     url: endpointUrl(options, endpoint),
     headers: buildHeaders(options, call?.cloudflare, model, record2),
     body,
-    warnings: []
+    warnings: packed.warning ? [packed.warning] : []
   };
 }
 function compileResponsesBody(request, model) {
@@ -2294,7 +2302,7 @@ function parseSsePart(part) {
     return void 0;
   }
 }
-function resolveCloudflareOptions(options) {
+function resolveCloudflareOptions(options, packer) {
   const {
     apiToken,
     accountId,
@@ -2323,7 +2331,8 @@ function resolveCloudflareOptions(options) {
     maxAttempts: maxAttempts ?? 2,
     fetch: fetch ?? globalThis.fetch,
     ...tools ? { tools } : {},
-    ...logger ? { logger } : {}
+    ...logger ? { logger } : {},
+    ...packer ? { metadataPacker: packer } : {}
   };
 }
 function hasGateway(gateway) {
@@ -2838,8 +2847,8 @@ function isBedrockToolChoice(toolChoice) {
 var import_openrouter_runtime2 = require("@x12i/openrouter-runtime");
 var DEFAULT_BASE_URL2 = "https://api.openai.com/v1";
 var DEFAULT_TIMEOUT_MS2 = 12e4;
-function createOpenAiProviderAdapter(options = {}) {
-  const resolved = resolveOpenAiOptions(options);
+function createOpenAiProviderAdapter(options = {}, packer) {
+  const resolved = resolveOpenAiOptions(options, packer);
   return {
     compile(request, call) {
       return compileOpenAiRequest(request, resolved, call, false);
@@ -2892,12 +2901,13 @@ function compileOpenAiRequest(request, options, call, streaming) {
   if (call?.finalizeBody) body = call.finalizeBody(body);
   if (streaming) body = { ...body, stream: true };
   else body = { ...body, stream: false };
-  body = attachProviderMetadata(body, request);
+  const packed = attachProviderMetadata(body, request, options.metadataPacker);
+  body = packed.body;
   return {
     url: `${options.baseUrl}/responses`,
     headers: buildHeaders2(options),
     body,
-    warnings: []
+    warnings: packed.warning ? [packed.warning] : []
   };
 }
 function assertSupported2(request) {
@@ -3397,14 +3407,14 @@ function messageFrom2(body) {
 function numberValue2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function attachProviderMetadata(body, request) {
+function attachProviderMetadata(body, request, packer) {
   const fromBody = isRecord7(body.metadata) ? body.metadata : void 0;
-  const metadata = (0, import_openrouter_runtime2.toProviderMetadata)(request.metadata, request.agentId, import_openrouter_runtime2.OPENROUTER_METADATA_LIMITS, fromBody);
-  if (metadata) return { ...body, metadata };
-  if (body.metadata === void 0) return body;
+  const packed = (0, import_openrouter_runtime2.packProviderRecord)(request.metadata, request.agentId, fromBody, packer);
+  if (packed.wire) return { body: { ...body, metadata: packed.wire }, ...packed.warning ? { warning: packed.warning } : {} };
+  if (body.metadata === void 0) return { body, ...packed.warning ? { warning: packed.warning } : {} };
   const rest = { ...body };
   delete rest.metadata;
-  return rest;
+  return { body: rest, ...packed.warning ? { warning: packed.warning } : {} };
 }
 function clean2(body) {
   return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== void 0));
@@ -3452,7 +3462,7 @@ function parseSsePart2(part) {
     return void 0;
   }
 }
-function resolveOpenAiOptions(options) {
+function resolveOpenAiOptions(options, packer) {
   const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/+$/, "");
   return {
     apiKey: options.apiKey ?? readEnv3("OPENAI_API_KEY") ?? "",
@@ -3464,7 +3474,8 @@ function resolveOpenAiOptions(options) {
     maxAttempts: options.maxAttempts ?? 3,
     fetch: options.fetch ?? globalThis.fetch,
     ...options.tools ? { tools: options.tools } : {},
-    ...options.logger ? { logger: options.logger } : {}
+    ...options.logger ? { logger: options.logger } : {},
+    ...packer ? { metadataPacker: packer } : {}
   };
 }
 function readEnv3(name) {
@@ -3517,7 +3528,9 @@ function resolveProvider(requestProvider, defaultProvider) {
 
 // src/create-dispatcher.ts
 var SECRET_HEADERS = /* @__PURE__ */ new Set(["authorization", "x-api-key", "api-key"]);
+var DEFAULT_METADATA_PRIORITY = ["agentId", "orgId", "stepId", "skillId", "recordId", "objectType"];
 function createAiDispatcher(options = {}) {
+  const packer = (0, import_provider_metadata.createMetadataPacker)({ priority: options.metadataPriority ?? DEFAULT_METADATA_PRIORITY });
   const defaultProvider = resolveProvider(options.provider, "openrouter");
   const catalog = createMcpCatalog(options.mcp);
   let refreshChain = Promise.resolve();
@@ -3526,6 +3539,7 @@ function createAiDispatcher(options = {}) {
     if (provider === "openrouter") {
       const openrouterOptions = {
         ...options.openrouter,
+        metadataPacker: packer,
         ...options.logger && !options.openrouter?.logger ? { logger: options.logger } : {}
       };
       return createOpenRouterProviderAdapter(openrouterOptions);
@@ -3533,6 +3547,7 @@ function createAiDispatcher(options = {}) {
     if (provider === "bedrock") {
       const bedrockOptions = {
         ...options.bedrock,
+        metadataPacker: packer,
         ...options.logger && !options.bedrock?.logger ? { logger: options.logger } : {}
       };
       return createBedrockProviderAdapter(bedrockOptions);
@@ -3542,14 +3557,14 @@ function createAiDispatcher(options = {}) {
         ...options.openai,
         ...options.logger && !options.openai?.logger ? { logger: options.logger } : {}
       };
-      return createOpenAiProviderAdapter(openaiOptions);
+      return createOpenAiProviderAdapter(openaiOptions, packer);
     }
     if (provider === "cloudflare") {
       const cloudflareOptions = {
         ...options.cloudflare,
         ...options.logger && !options.cloudflare?.logger ? { logger: options.logger } : {}
       };
-      return createCloudflareProviderAdapter(cloudflareOptions);
+      return createCloudflareProviderAdapter(cloudflareOptions, packer);
     }
     throw new AiDispatcherError(
       "PROVIDER_ADAPTER_MISSING",
@@ -3670,10 +3685,14 @@ function stripReasoningHistoryFields(message, paths) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AiDispatcherError,
+  DEFAULT_METADATA_PRIORITY,
   IMPLEMENTED_AI_PROVIDERS,
+  METADATA_NORMALIZATION_MAP,
+  canonicalMetadataKey,
   createAiDispatcher,
   decodeProviderMetadata,
   isImplementedAiProvider,
+  normalizeMetadata,
   providerNotImplemented,
   resolveProvider,
   stripReasoningHistoryFields