@x12i/ai-dispatcher 3.0.0 → 3.2.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.2.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.3.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` 3.0.0. It runs on Node 22 or newer and publishes ESM and CommonJS from the same entry.
+The package is `@x12i/ai-dispatcher` 3.2.0. It runs on Node 22 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,21 @@ Connected MCP servers can be passed to `createAiDispatcher`. `run()` and `compil
 npm install @x12i/ai-dispatcher
 ```
 
-The package depends on `@x12i/ai-input@1.1.0`, `@x12i/ai-profiles@^5.2.0`, `@x12i/provider-metadata@^1.2.1`, `@x12i/openrouter-runtime@^2.2.1`, and `@x12i/bedrock-runtime@^2.2.2`. `gpt-tokenizer` and `ajv` are optional peers of `@x12i/ai-input` and are not installed with the dispatcher. `registerHostIntents` is re-exported from this package so a host registers intents on the same `@x12i/ai-profiles` copy the dispatcher resolves with.
+The package depends on `@x12i/ai-input@1.1.0`, `@x12i/ai-profiles@5.3.0`, `@x12i/provider-metadata@^1.2.1`, `@x12i/openrouter-runtime@^2.2.1`, and `@x12i/bedrock-runtime@^2.2.2`. `@x12i/ai-catalogs@1.2.0` comes in through profiles. `gpt-tokenizer` and `ajv` are optional peers of `@x12i/ai-input` and are not installed with the dispatcher. `registerHostIntents` and `resolveAIProfile` are re-exported from this package so a host uses the same `@x12i/ai-profiles` copy the dispatcher resolves with.
+
+## AI registry
+
+`@x12i/ai-profiles@5.3.0` loads `GET /v1/datasets/profiles` and `GET /v1/datasets/catalog` from `https://ai-registry.app.x12i.com`. A successful response is used as-is and cached briefly. If the registry is unreachable, the JSON shipped in the npm package is used. Do not set `AI_REGISTRY_SOURCE`. Override the origin only when you proxy it: `AI_REGISTRY_URL`.
+
+`resolveReasoning` still reads the bundled reasoning catalog. Profile names such as `cheap/default` resolve through the live registry:
+
+```ts
+import { resolveAIProfile } from "@x12i/ai-dispatcher";
+
+const profile = await resolveAIProfile("cheap/default", { catalogLane: "text" });
+```
+
+Leave `AUTHIX_TOKEN` unset for the published model. Set it only if a host is pinning a profile or role to a catalog id for an Authix subject. Omit `context` / `AI_REGISTRY_CONTEXT` for the default bucket. A stored pin replaces that profile. A key with no pin stays on the published model. If the pin service cannot be reached, the published model is used and a `CUSTOMIZATION_UNAVAILABLE` warning is attached. Resolve does not fail. The token is sent only to `/v1/customization`. This package does not write pins, does not depend on `@x12i/ai-registry-client` or `@x12i/agent-roles`, and does not log the token. A `role` stamp on the request is caller metadata.
 
 ## One request
 
@@ -56,7 +70,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.2.0`:
+Representative catalog results for `@x12i/ai-profiles@5.3.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.
@@ -144,7 +158,7 @@ Text can arrive as `prompt`, `messages`, `input`, `system`, or `instructions`. A
 | `functionTools` | Local function tools: `name`, `description`, `parameters`, optional `executor`. |
 | `toolChoice` | `"auto"`, `"none"`, `"required"`, `{ type: "function", functionName }`, or an OpenRouter `{ type: "server_tool", serverTool }`. |
 | `execution` | `maxToolIterations`, `maxServerToolCalls`, `maxFunctionToolCalls`, `timeoutMs`. Bedrock keeps the iteration, function-call, and timeout limits. |
-| `metadata` | The one metadata record. String, number, and boolean values, including `xtivix.execution`, `recordId`, and `objectType`. |
+| `metadata` | The one metadata record. String, number, and boolean values, including `session_id`, `xtivix.caller`, `xtivix.execution`, `recordId`, and `objectType`. The package adds `xtivix.gate`. |
 | `serverTools` | OpenRouter server tools only. Bedrock, direct OpenAI, and Cloudflare reject an enabled policy. |
 | `apiMode` | `"chat"`, `"responses"`, or `"auto"`. Direct OpenAI rejects `"chat"`. Bedrock rejects any `apiMode`. On Cloudflare, `"chat"` and `"responses"` select those endpoints when `cloudflare.endpoint` is omitted or `auto`. |
 | `responseFormat` | OpenRouter forwards it. Direct OpenAI and Cloudflare Responses place it on `text`. Cloudflare chat sends `response_format`. Cloudflare messages and run reject it. Bedrock rejects it. |
@@ -156,6 +170,8 @@ Text can arrive as `prompt`, `messages`, `input`, `system`, or `instructions`. A
 
 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.
 
+`session_id` is the thread id. Send the full string on `metadata`, including `dd:`, the package, the version, and the hash. Leave it as one string. `session.id` is promoted to `session_id`. A key named `sessionId` is a different key and does not become the thread. `xtivix.caller` is your name for who sent the call. Omit it when you do not have one. The dispatcher does not invent it. `xtivix.gate` is written by this package on every call, as `ai-dispatcher` (`AI_DISPATCHER_GATE`). A value you send for that key is replaced. The gate is not the model provider. These values are plain strings. Slashes, `@`, and colons in the session id need no escaping.
+
 ```ts
 import { decodeProviderMetadata } from "@x12i/ai-dispatcher";
 
@@ -167,6 +183,8 @@ await dispatcher.run({
   stepId: "step-3",
   skillId: "skill-9",
   metadata: {
+    session_id: "dd:@xverix/mail-decisions/vendor@0.1.0:46b03b5e",
+    "xtivix.caller": "mail-decisions",
     "xtivix.execution": executionJson,
     recordId: "rec-1",
     objectType: "note"
@@ -176,9 +194,9 @@ await dispatcher.run({
 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.
+`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. `xtivix.gate` is the exception: the package value wins. 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`. Pass the Cloudflare `cf-aig-metadata` header as that same object or as the raw JSON string. 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.
+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`. Pass the Cloudflare `cf-aig-metadata` header as that same object or as the raw JSON string. 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`. `session_id`, `xtivix.caller`, and `xtivix.gate` are not in that list. Unlisted keys are dropped longest first, so these short values stay unless the record is still over the limit after every longer unlisted value, including `xtivix.execution`, has been dropped. Include `session_id`, `xtivix.caller`, and `xtivix.gate` when you pass your own `metadataPriority`. 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.
 
@@ -311,7 +329,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.2.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.3.0 paths are empty, so a real directive deletes nothing.
 
 ## Streaming
 
@@ -507,18 +525,18 @@ OpenAI HTTP failures such as `401` return a failed response from `run()`. `FUNCT
 
 ## Logging
 
-Pass `logger` on the dispatcher. `run` and `executeStreamingChat` emit `ai-dispatcher.request.started` at info. `compile` emits `ai-dispatcher.request.compiled` at debug. The record can include `provider`, `entrypoint`, `streaming`, `requestedModel`, `effectiveModel`, `requestId`, `outcome`, and `bypassed`. It does not include credentials, prompts, reasoning text, or raw bodies.
+Pass `logger` on the dispatcher. `run` and `executeStreamingChat` emit `ai-dispatcher.request.started` at info. `compile` emits `ai-dispatcher.request.compiled` at debug. The record can include `provider`, `entrypoint`, `streaming`, `requestedModel`, `effectiveModel`, `requestId`, `outcome`, and `bypassed`. It does not include credentials, `AUTHIX_TOKEN`, prompts, reasoning text, or raw bodies.
 
 ## Limitations
 
-- Catalog 5.2.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.3.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.2.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.3.0 reasoning catalog for contract cases.
 - Input preparation does not claim release gate 9. Automatic TOON and `shared-v1` stay on compact outline or the original string until the caller passes a matching approval and a tokenizer. `codec: "toon"` sends TOON as a caller choice. `codec: "json"` and `mode: "raw"` keep JSON.
 - `gpt-tokenizer` and `ajv` are not installed. A `gpt:*` tokenizer is loaded only when that call requests it.
 - The dispatcher does not read `AI_INPUT_*` or a `.env` file for input preparation.

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AI_DISPATCHER_GATE: () => AI_DISPATCHER_GATE,
   AiDispatcherError: () => AiDispatcherError,
   DEFAULT_METADATA_PRIORITY: () => DEFAULT_METADATA_PRIORITY,
   IMPLEMENTED_AI_PROVIDERS: () => IMPLEMENTED_AI_PROVIDERS,
@@ -41,6 +42,7 @@ __export(index_exports, {
   normalizeMetadata: () => import_openrouter_runtime4.normalizeMetadata,
   providerNotImplemented: () => providerNotImplemented,
   registerHostIntents: () => import_ai_profiles2.registerHostIntents,
+  resolveAIProfile: () => import_ai_profiles2.resolveAIProfile,
   resolveProvider: () => resolveProvider,
   stripReasoningHistoryFields: () => stripReasoningHistoryFields
 });
@@ -2650,6 +2652,7 @@ function prepareDispatchRequest(params) {
   applyRoleStamp(cloned);
   applyDispatchIdentity(cloned);
   absorbOverrideMetadata(cloned);
+  applyDispatchGate(cloned);
   const provider = params.provider;
   const reasoningEffort = cloned.reasoningEffort;
   const bedrockControls = cloned.bedrockControls;
@@ -3002,6 +3005,12 @@ function applyDispatchIdentity(request) {
   for (const key of Object.keys(identity)) delete rest[key];
   request.metadata = { ...identity, ...rest };
 }
+var AI_DISPATCHER_GATE = "ai-dispatcher";
+function applyDispatchGate(request) {
+  const rest = { ...request.metadata ?? {} };
+  delete rest["xtivix.gate"];
+  request.metadata = { "xtivix.gate": AI_DISPATCHER_GATE, ...rest };
+}
 function cloneRequest(request) {
   const functionTools = request.functionTools?.map((tool) => ({ ...tool }));
   const cloned = JSON.parse(JSON.stringify(request));
@@ -4026,6 +4035,7 @@ function stripReasoningHistoryFields(message, paths) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AI_DISPATCHER_GATE,
   AiDispatcherError,
   DEFAULT_METADATA_PRIORITY,
   IMPLEMENTED_AI_PROVIDERS,
@@ -4037,6 +4047,7 @@ function stripReasoningHistoryFields(message, paths) {
   normalizeMetadata,
   providerNotImplemented,
   registerHostIntents,
+  resolveAIProfile,
   resolveProvider,
   stripReasoningHistoryFields
 });