@x12i/ai-dispatcher 3.1.0 → 3.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.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.6.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.3.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.6.0`, `@x12i/provider-metadata@^1.2.1`, `@x12i/openrouter-runtime@^2.3.0`, and `@x12i/bedrock-runtime@^2.2.2`. `@x12i/ai-catalogs@1.3.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.6.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,12 +70,12 @@ 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`:
+The model catalog decides which efforts a model accepts. `@x12i/ai-profiles@5.6.0` still supplies the wire shape: response paths, stream keys, usage paths, and where the effort is written. The effort string itself is not rewritten.
 
-- OpenRouter `~google/gemini-flash-latest` + `max` is `degraded` and sends `reasoning.effort: "high"`.
+- OpenRouter `openai/gpt-6-astra` at `xhigh` sends `reasoning.effort: "xhigh"`. `max` sends `max`.
+- `minimal` and `none` on Astra fail with `EFFORT_UNSUPPORTED`. Set `degradeReasoningEffort: true` to keep a mapping substitution. The resolution then records `requestedEffort`, `sentEffort`, and `outcome: "degraded"`.
 - OpenRouter `aion-labs/aion-2.0` is `ignored` with an empty reasoning body. The call still runs.
-- Bedrock `anthropic.claude-fable-5-1` + `max` is `degraded` and sends `output_config.effort: "high"`.
-- OpenAI `gpt-5.4` + `max` is `applied` and sends `reasoning.effort: "max"`.
+- Bedrock `anthropic.claude-fable-5-1` at `max` sends `output_config.effort: "max"`, because the catalog lists `max`.
 - OpenAI `gpt-4o` is `ignored`. The Responses call still runs.
 
 The type `AiProviderId` also lists `anthropic`, `google`, `azure`, `groq`, `mistral`, `cohere`, `together`, `fireworks`, `xai`, `deepseek`, and `custom`. Passing any of those throws `PROVIDER_NOT_IMPLEMENTED`.
@@ -262,7 +276,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`. `extra-high` is rejected with `INVALID_EFFORT`. It is not stored as `max`.
+`reasoningEffort` is the effort name to send. It is valid when that model's `reasoning.supportedEfforts` lists it. An effort the model does not list fails with `EFFORT_UNSUPPORTED`. The error names the model, the requested effort, and the supported list. Unknown model ids still fail with `UNKNOWN_MODEL`. Set `degradeReasoningEffort: true` to allow the mapping's substitution. The call then records both efforts and `outcome: "degraded"`.
 
 | Request | Catalog |
 | --- | --- |
@@ -280,8 +294,8 @@ An OpenRouter `reasoning` object on a Bedrock call is not a Bedrock control. Wit
 
 Outcomes:
 
-- `applied` — the catalog wrote the requested effort.
-- `degraded` — the catalog wrote a supported nearby effort. The call still runs.
+- `applied` — the checked effort was written as requested.
+- `degraded` — `degradeReasoningEffort` was set and the mapping wrote a different listed effort. The call still runs.
 - `ignored` — the model has no reasoning control. The call still runs with an empty catalog body.
 
 Unknown models and missing mappings throw. The error keeps the catalog `code` and `details`, including `UNKNOWN_MODEL` and `REASONING_MAPPING_MISSING`. `reasoningEffort` without any model id throws `REASONING_MODEL_REQUIRED`.
@@ -301,21 +315,25 @@ The dispatcher does not rank efforts, invent token budgets, or rewrite `maxToken
 ```ts
 {
   requestedEffort: "max",
+  sentEffort: "max",
+  reportedEffort: "xhigh",
   target: "openrouter",
-  requestedModel: "~google/gemini-flash-latest",
-  effectiveModel: "~google/gemini-flash-latest",
-  outcome: "degraded",
+  requestedModel: "openai/gpt-6-astra",
+  effectiveModel: "openai/gpt-6-astra",
+  outcome: "applied",
   bypassed: false
 }
 ```
 
+`reportedEffort` is set when the provider returns an effort. A gateway can echo `max` back as `xhigh`. `sentEffort` is omitted when the mapping ignores the model and writes no effort.
+
 The same record is on `compile()` output, `stream.start`, and `stream.done`.
 
 The rest of the response is the runtime shape: `id`, `status` (`completed`, `failed`, `requires_action`, `policy_violation`), `apiMode`, `model`, `messages`, `citations`, `images`, `patches`, `toolUsage`, `finishReason`, `warnings`, `errors`, `raw`, and `metadata`. Direct OpenAI sets `apiMode` to `"responses"` and returns function calls as `requires_action` without running them. Cloudflare Responses does the same. Cloudflare chat, messages, and run report `apiMode: "chat"`.
 
 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.6.0 paths are empty, so a real directive deletes nothing.
 
 ## Streaming
 
@@ -486,6 +504,7 @@ Catalog failures throw `AiDispatcherError` with `code`, `message`, and the catal
 | `PROVIDER_REQUIRED` | No provider string is available |
 | `PROVIDER_ADAPTER_MISSING` | An implemented provider has no adapter |
 | `REASONING_MODEL_REQUIRED` | `reasoningEffort` is set and no model id is available |
+| `EFFORT_UNSUPPORTED` | The model's `supportedEfforts` does not list the requested effort, and `degradeReasoningEffort` is not set |
 | `REASONING_PREFIX_UNSUPPORTED` | A catalog prompt prefix has no user text to attach to |
 | `UNSUPPORTED_REQUEST_FIELD` | A field cannot be sent on the selected provider |
 | `MODEL_REQUIRED` | Direct OpenAI or Cloudflare has no model id |
@@ -511,18 +530,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.6.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.6.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.