@x12i/ai-dispatcher 2.1.0 → 2.3.0

package/README.md

@@ -1,10 +1,10 @@
 # @x12i/ai-dispatcher
 
-One request shape for OpenRouter, AWS Bedrock, the OpenAI Responses API, and Cloudflare AI. You send the same request shape. The package picks the provider, and `@x12i/ai-profiles@5.0.0` turns `reasoningEffort` into that provider's wire fields. Callers do not map effort levels onto provider fields or parse provider reasoning channels.
+One request shape for OpenRouter, AWS Bedrock, the OpenAI Responses API, and Cloudflare AI. You send the same request shape. The package picks the provider, and `@x12i/ai-profiles@^5.1.0` turns `reasoningEffort` into that provider's wire fields. Callers do not map effort levels onto provider fields or parse provider reasoning channels.
 
 **Implemented providers:** `openrouter`, `bedrock`, `openai`, `cloudflare`. Any other provider throws `PROVIDER_NOT_IMPLEMENTED`.
 
-The package is `@x12i/ai-dispatcher` 2.1.0. It runs on Node 20 or newer and publishes ESM and CommonJS from the same entry.
+The package is `@x12i/ai-dispatcher` 2.3.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/provider-metadata@1.1.0`, `@x12i/openrouter-runtime@^2.1.0`, and `@x12i/bedrock-runtime@^2.1.0`.
+The package depends on `@x12i/ai-profiles@^5.1.0`, `@x12i/provider-metadata@^1.2.0`, `@x12i/openrouter-runtime@^2.2.0`, and `@x12i/bedrock-runtime@^2.2.0`. `registerHostIntents` is re-exported from this package so a host registers intents on the same `@x12i/ai-profiles` copy the dispatcher resolves with.
 
 ## One request
 
@@ -56,7 +56,7 @@ Use model ids that belong to the selected catalog target. An OpenRouter id is no
 | `openai` | `gpt-5.4` | `reasoning.effort: "low"` on the Responses body |
 | `cloudflare` | `openai/gpt-5.4` | `reasoning.effort: "low"` on the Cloudflare Responses body |
 
-Representative catalog results for `@x12i/ai-profiles@5.0.0`:
+Representative catalog results for `@x12i/ai-profiles@5.1.0`:
 
 - OpenRouter `~google/gemini-flash-latest` + `max` is `degraded` and sends `reasoning.effort: "high"`.
 - OpenRouter `aion-labs/aion-2.0` is `ignored` with an empty reasoning body. The call still runs.
@@ -153,7 +153,7 @@ Text can arrive as `prompt`, `messages`, `input`, `system`, or `instructions`. A
 | `cloudflare` | Per-call overrides: `endpoint`, `gatewayId`, `run`, and `cf-aig-*` controls. Stripped before compilation. |
 | `mcp` | `false` or `[]` omits MCP tools registered at initialization. A list of exposed names attaches only those tools. Omit the field to attach every registered MCP tool. |
 
-Set `metadata` for the pairs you want back from a log. `agentId`, `orgId`, `stepId`, and `skillId` are fields on the same record. A dedicated field wins over the same key inside `metadata`. Omit an id you do not have. The dispatcher does not invent one.
+Set `metadata` for the pairs you want back from a log. `agentId`, `orgId`, `stepId`, and `skillId` are fields on the same record. A `role` object expands to `role`, `roleLayer`, `roleDigest`, and `profileChoice` on that record. A dedicated field wins over the same key inside `metadata`. Omit an id you do not have. The dispatcher does not invent one.
 
 ```ts
 import { decodeProviderMetadata } from "@x12i/ai-dispatcher";
@@ -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. 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.
+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`, `role`, `roleLayer`, `roleDigest`, `profileChoice`, `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.
 
@@ -241,7 +243,7 @@ Text blocks in an MCP result are joined and returned to the model. `isError: tru
 
 ## Reasoning effort
 
-`reasoningEffort` is `minimal | low | medium | high | max`.
+`reasoningEffort` is `minimal | low | medium | high | max`. `extra-high` is rejected with `INVALID_EFFORT`. It is not stored as `max`.
 
 | Request | Catalog |
 | --- | --- |
@@ -294,7 +296,7 @@ The rest of the response is the runtime shape: `id`, `status` (`completed`, `fai
 
 Streaming emits `stream.reasoning.delta` for thought text. That text is not copied into `stream.text.delta`, tool-argument deltas, or structured-output text. If a future catalog asks for think-tag stripping, tags are split out of answer deltas before those deltas are yielded.
 
-The dispatcher does not store conversation history. When a directive lists history fields to drop, callers pass those paths to `stripReasoningHistoryFields(message, paths)`. The helper clones the message, deletes only those pointers, and is safe to call twice. Catalog 5.0.0 paths are empty, so a real directive deletes nothing.
+The dispatcher does not store conversation history. When a directive lists history fields to drop, callers pass those paths to `stripReasoningHistoryFields(message, paths)`. The helper clones the message, deletes only those pointers, and is safe to call twice. Catalog 5.1.0 paths are empty, so a real directive deletes nothing.
 
 ## Streaming
 
@@ -482,11 +484,11 @@ Pass `logger` on the dispatcher. `run` and `executeStreamingChat` emit `ai-dispa
 
 ## Limitations
 
-- Catalog 5.0.0 does not currently emit a prompt prefix, a replacement model, think-tag stripping, history deletions, or a reasoning token budget. Those paths exist for the directive type and are covered by synthetic tests.
+- Catalog 5.1.0 does not currently emit a prompt prefix, a replacement model, think-tag stripping, history deletions, or a reasoning token budget. Those paths exist for the directive type and are covered by synthetic tests.
 - Prompt caching is a dispatcher profile, not an `@x12i/ai-profiles` field. It writes one breakpoint after `system` or `instructions`. It does not place extra breakpoints on tools or on a prefix that changes in the middle of the call.
 - Provenance notes about output-token headroom are not enforced, because the resolver does not return them as fields.
 - OpenRouter server tools, `apiMode: "chat"`, and `rawOpenRouterOverrides` stay on OpenRouter. Bedrock, direct OpenAI, and Cloudflare reject the server-tool fields and `rawOpenRouterOverrides` keys other than `metadata`. Cloudflare accepts `apiMode: "chat"` as the chat-completions endpoint.
 - Direct OpenAI and Cloudflare streaming do not run the function-tool loop. MCP tools are not attached to `executeStreamingChat` on any provider. Cloudflare `/ai/run` does not stream.
 - OpenRouter advisor, subagent, and fusion cannot call MCP sessions registered on the dispatcher.
 - Bedrock `run()` returns a failed response for `UNSUPPORTED_CONTENT`. `compile()` throws that error.
-- Live provider calls are not part of the package test suite. Tests mock HTTP and the Bedrock client and use the real 5.0.0 catalog for contract cases.
+- Live provider calls are not part of the package test suite. Tests mock HTTP and the Bedrock client and use the real 5.1.0 catalog for contract cases.

package/dist/index.cjs

@@ -23,14 +23,19 @@ __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,
+  registerHostIntents: () => import_ai_profiles2.registerHostIntents,
   resolveProvider: () => resolveProvider,
   stripReasoningHistoryFields: () => stripReasoningHistoryFields
 });
 module.exports = __toCommonJS(index_exports);
+var import_ai_profiles2 = require("@x12i/ai-profiles");
 var import_openrouter_runtime4 = require("@x12i/openrouter-runtime");
 
 // src/create-dispatcher.ts
@@ -2349,6 +2354,7 @@ function isRecord5(value) {
 // src/prepare-request.ts
 function prepareDispatchRequest(params) {
   const cloned = cloneRequest(params.request);
+  applyRoleStamp(cloned);
   applyDispatchIdentity(cloned);
   absorbOverrideMetadata(cloned);
   const provider = params.provider;
@@ -2656,6 +2662,23 @@ function defaultModelFor(provider, options) {
   return options.openai?.defaultModel;
 }
 var DISPATCH_IDENTITY_FIELDS = ["orgId", "stepId", "skillId"];
+var ROLE_STAMP_FIELDS = ["role", "roleLayer", "roleDigest", "profileChoice"];
+function applyRoleStamp(request) {
+  const stamp = request.role;
+  delete request.role;
+  if (!isRecord6(stamp)) return;
+  const identity = {};
+  for (const field of ROLE_STAMP_FIELDS) {
+    const value = stamp[field];
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed) identity[field] = trimmed;
+  }
+  if (!Object.keys(identity).length) return;
+  const rest = { ...request.metadata ?? {} };
+  for (const key of Object.keys(identity)) delete rest[key];
+  request.metadata = { ...identity, ...rest };
+}
 function absorbOverrideMetadata(request) {
   const overrides = request.rawOpenRouterOverrides;
   if (!isRecord6(overrides) || !Object.prototype.hasOwnProperty.call(overrides, "metadata")) return;
@@ -3525,7 +3548,18 @@ 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"];
+var DEFAULT_METADATA_PRIORITY = [
+  "agentId",
+  "orgId",
+  "stepId",
+  "skillId",
+  "role",
+  "roleLayer",
+  "roleDigest",
+  "profileChoice",
+  "recordId",
+  "objectType"
+];
 function createAiDispatcher(options = {}) {
   const packer = (0, import_provider_metadata.createMetadataPacker)({ priority: options.metadataPriority ?? DEFAULT_METADATA_PRIORITY });
   const defaultProvider = resolveProvider(options.provider, "openrouter");
@@ -3684,10 +3718,14 @@ function stripReasoningHistoryFields(message, paths) {
   AiDispatcherError,
   DEFAULT_METADATA_PRIORITY,
   IMPLEMENTED_AI_PROVIDERS,
+  METADATA_NORMALIZATION_MAP,
+  canonicalMetadataKey,
   createAiDispatcher,
   decodeProviderMetadata,
   isImplementedAiProvider,
+  normalizeMetadata,
   providerNotImplemented,
+  registerHostIntents,
   resolveProvider,
   stripReasoningHistoryFields
 });