@x12i/ai-dispatcher 2.2.0 → 2.3.1

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.2.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.1. 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.2.0`, `@x12i/openrouter-runtime@^2.2.0`, and `@x12i/bedrock-runtime@^2.2.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,7 @@ 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.
 
@@ -243,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 |
 | --- | --- |
@@ -296,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
 
@@ -446,6 +446,17 @@ await dispatcher.run({
 
 Cloudflare supports the same `run`, `compile`, and `executeStreamingChat` entrypoints. `executeStreamingChat` rejects `/ai/run`. `reasoningEffort` uses the OpenAI or OpenRouter catalog, as described above. `cache` sets AI Gateway headers and, for GPT on Responses and Claude on Messages, the native breakpoint. Local function tools and MCP tools follow the OpenAI loop. OpenRouter server tools are rejected. `rawOpenRouterOverrides` is rejected except for a `metadata` object, which is folded into `metadata`. `responseFormat` is `text` on Responses, `response_format` on chat, and rejected on messages and run.
 
+## Credentials
+
+A provider is available when the dispatcher can resolve the credential it sends. `compile` and `run` throw when a required value is missing.
+
+| Provider | Option | Environment |
+| --- | --- | --- |
+| OpenRouter | `openrouter.apiKey` | `OPENROUTER_API_KEY`, then `OPEN_ROUTER_KEY` |
+| Bedrock | `bedrock.region` and optional `bedrock.credentials` | `AWS_REGION` or `AWS_DEFAULT_REGION`. When `credentials` is omitted, the AWS SDK default chain is used. An explicit credential is `accessKeyId`, `secretAccessKey`, and optional `sessionToken`. |
+| OpenAI | `openai.apiKey` | `OPENAI_API_KEY` |
+| Cloudflare | `cloudflare.apiToken` and `cloudflare.accountId` | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` |
+
 ## Errors
 
 Catalog failures throw `AiDispatcherError` with `code`, `message`, and the catalog `details`. Dispatcher codes include:
@@ -466,7 +477,7 @@ Catalog failures throw `AiDispatcherError` with `code`, `message`, and the catal
 | `PROVIDER_AUTH_FAILED` | OpenAI or Cloudflare HTTP `401` or `403` |
 | `PROVIDER_MODEL_NOT_FOUND` | OpenAI or Cloudflare HTTP `404` |
 | `PROVIDER_REQUEST_FAILED` | Other OpenAI or Cloudflare HTTP failures |
-| `PROVIDER_RATE_LIMITED` | Cloudflare HTTP `429` after retries |
+| `PROVIDER_RATE_LIMITED` | OpenAI or Cloudflare HTTP `429` after retries |
 | `PROVIDER_RETRYABLE` / `PROVIDER_GATEWAY_UNREACHABLE` | OpenAI or Cloudflare transport failures after retries, including timeout |
 | `FUNCTION_TOOL_LIMIT` | Function-tool calls exceed `maxFunctionToolCalls` |
 | `UNSUPPORTED_CONTENT` | Bedrock received an image URL or content part it cannot send |
@@ -484,11 +495,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

@@ -30,10 +30,12 @@ __export(index_exports, {
   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
@@ -2352,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;
@@ -2659,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;
@@ -3260,8 +3280,7 @@ async function readFailure2(response) {
 function classifyStatus2(status) {
   if (status === 401 || status === 403) return "PROVIDER_AUTH_FAILED";
   if (status === 404) return "PROVIDER_MODEL_NOT_FOUND";
-  if (status === 429) return "PROVIDER_RATE_LIMITED";
-  if (status === 408 || status >= 500) return "PROVIDER_RETRYABLE";
+  if (status === 429 || status === 408 || status >= 500) return "PROVIDER_RETRYABLE";
   return "PROVIDER_REQUEST_FAILED";
 }
 function isConfigError2(code) {
@@ -3269,6 +3288,8 @@ function isConfigError2(code) {
 }
 function asTerminalError2(error) {
   if (error instanceof AiDispatcherError && error.code === "PROVIDER_RETRYABLE") {
+    const status = isRecord7(error.details) ? error.details.status : void 0;
+    if (status === 429) return new AiDispatcherError("PROVIDER_RATE_LIMITED", error.message, error.details);
     return new AiDispatcherError("PROVIDER_GATEWAY_UNREACHABLE", error.message, error.details);
   }
   if (error instanceof AiDispatcherError) return error;
@@ -3528,7 +3549,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");
@@ -3694,6 +3726,7 @@ function stripReasoningHistoryFields(message, paths) {
   isImplementedAiProvider,
   normalizeMetadata,
   providerNotImplemented,
+  registerHostIntents,
   resolveProvider,
   stripReasoningHistoryFields
 });