@x12i/ai-dispatcher 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,363 @@
+# @x12i/ai-dispatcher
+
+One request shape for OpenRouter, AWS Bedrock, and the OpenAI Responses API. 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.
+
+**Implemented providers:** `openrouter`, `bedrock`, `openai`. Any other provider throws `PROVIDER_NOT_IMPLEMENTED`.
+
+The package is `@x12i/ai-dispatcher` 1.4.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).
+
+## Install
+
+```bash
+npm install @x12i/ai-dispatcher
+```
+
+The package depends on `@x12i/ai-profiles@5.0.0`, `@x12i/openrouter-runtime@^1.2.0`, and `@x12i/bedrock-runtime@^1.0.0`.
+
+## One request
+
+```ts
+import { createAiDispatcher } from "@x12i/ai-dispatcher";
+
+const dispatcher = createAiDispatcher({
+  openrouter: { apiKey: process.env.OPENROUTER_API_KEY },
+  bedrock: { region: process.env.AWS_REGION },
+  openai: { apiKey: process.env.OPENAI_API_KEY }
+});
+
+const response = await dispatcher.run({
+  provider: "openai",
+  model: "gpt-5.4",
+  prompt: "Explain the tradeoff in one paragraph.",
+  reasoningEffort: "low"
+});
+
+console.log(response.text);
+console.log(response.reasoningText);
+console.log(response.reasoningResolution);
+```
+
+Provider selection is `request.provider`, then `options.provider`, then `openrouter`. Model selection is `request.model`, then that provider's `defaultModel`.
+
+`openai` sends `POST {baseUrl}/responses`. The default base URL is `https://api.openai.com/v1`, and the catalog `reasoning` object is placed on that Responses body.
+
+Use model ids that belong to the selected catalog target. An OpenRouter id is not a Bedrock id and is not an OpenAI id.
+
+| Target | Example model id | `reasoningEffort: "low"` on the wire |
+| --- | --- | --- |
+| `openrouter` | `openai/gpt-5.2` | `reasoning.effort: "low"` on the chat-completions body |
+| `bedrock` | `anthropic.claude-fable-5-1` | `additionalModelRequestFields.thinking.type: "adaptive"` and `output_config.effort: "low"` |
+| `openai` | `gpt-5.4` | `reasoning.effort: "low"` on the Responses body |
+
+Representative catalog results for `@x12i/ai-profiles@5.0.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.
+- 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"`.
+- 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`.
+
+## Configuration
+
+```ts
+createAiDispatcher({
+  provider: "openrouter",
+  logger: {
+    info: (event, data) => console.log(event, data)
+  },
+  openrouter: {
+    apiKey: process.env.OPENROUTER_API_KEY,
+    defaultModel: "openai/gpt-5.2"
+  },
+  bedrock: {
+    region: process.env.AWS_REGION ?? "us-east-1",
+    defaultModel: "anthropic.claude-fable-5-1"
+  },
+  openai: {
+    apiKey: process.env.OPENAI_API_KEY, // or OPENAI_API_KEY
+    baseUrl: "https://api.openai.com/v1",
+    defaultModel: "gpt-5.4",
+    organization: process.env.OPENAI_ORG_ID,
+    project: process.env.OPENAI_PROJECT_ID,
+    timeoutMs: 60_000,
+    maxAttempts: 2
+  }
+});
+```
+
+`dispatcher.provider` is the default provider id. Adapters are created on first use and reused. The default provider's adapter is created immediately.
+
+The `logger` callback is `{ debug, info, warn, error }`. A provider-specific `logger` on `openrouter`, `bedrock`, or `openai` wins over the dispatcher logger for that adapter. You can inject `fetch` on OpenAI and OpenRouter, and a `client` on Bedrock.
+
+Missing OpenAI credentials throw `OPENAI_API_KEY_MISSING`. Missing Bedrock region throws the runtime's `REGION_REQUIRED`. Missing OpenRouter key throws `OPENROUTER_API_KEY_MISSING`.
+
+### Credentials and transport
+
+| Provider | Required | Default transport |
+| --- | --- | --- |
+| OpenRouter | `openrouter.apiKey` | OpenRouter chat completions |
+| Bedrock | `bedrock.region` | Converse / ConverseStream. Credentials are the AWS default chain, or `bedrock.credentials` |
+| OpenAI | `openai.apiKey` or `OPENAI_API_KEY` | `POST {baseUrl}/responses`. Default base URL is `https://api.openai.com/v1`. Default timeout is 120 seconds. Default attempts is 2 |
+
+Optional OpenAI headers are `OpenAI-Organization` and `OpenAI-Project`.
+
+OpenAI retries `429`, `408`, and `5xx` with backoff capped at 5 seconds. After the last retryable failure, `run()` returns a failed response and streaming yields `stream.error` and then throws. `401` and `403` become `PROVIDER_AUTH_FAILED`. `404` becomes `PROVIDER_MODEL_NOT_FOUND`. Other HTTP failures become `PROVIDER_REQUEST_FAILED`. Timeouts and network failures are `PROVIDER_GATEWAY_UNREACHABLE`. Config mistakes (`OPENAI_API_KEY_MISSING`, `MODEL_REQUIRED`, `INPUT_REQUIRED`, `UNSUPPORTED_REQUEST_FIELD`) throw from `run()` instead of becoming a failed response.
+
+## The request
+
+`AiDispatcherRequest` is the OpenRouter runtime request plus `provider`, `reasoningEffort`, `bedrockControls`, and `mcp`.
+
+Text can arrive as `prompt`, `messages`, `input`, `system`, or `instructions`. A message role is `system`, `user`, `assistant`, or `tool`. Content is a string or parts: `text`, `image_url`, or `file`.
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Caller request id. Logged when set. OpenAI uses it as a fallback response id. |
+| `temperature`, `maxTokens` | Sampling and output cap. OpenAI sends `maxTokens` as `max_output_tokens`. |
+| `reasoning` | Explicit wire object for OpenRouter and OpenAI. |
+| `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` | Passed through. |
+| `serverTools` | OpenRouter server tools only. Bedrock and direct OpenAI reject an enabled policy. |
+| `apiMode` | `"chat"`, `"responses"`, or `"auto"`. Direct OpenAI rejects `"chat"`. Bedrock rejects any `apiMode`. |
+| `responseFormat` | OpenRouter forwards it. Direct OpenAI places it on the Responses `text` field. Bedrock rejects it. |
+| `rawOpenRouterOverrides` | Merged onto an OpenRouter body. Rejected on Bedrock and direct OpenAI. |
+| `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. |
+
+OpenAI compilation order: `instructions` wins, then `system`, then system messages joined with newlines. `input` is sent as written. Otherwise non-system messages are converted, and a string `prompt` is appended as a user item. Tool messages become `function_call_output`. Image parts become `input_image`. A file part with `url` becomes `input_file` `file_url`. A file part with `data` becomes `input_file` `file_data`. `fileName` becomes `filename`. A file part with neither `url` nor `data` throws `UNSUPPORTED_REQUEST_FIELD`.
+
+Bedrock receives `id`, `model`, `messages`, `system`, `prompt`, `temperature`, `maxTokens`, `functionTools`, a Bedrock-compatible `toolChoice`, the execution limits above, and `metadata`. `instructions` is used as `system` when `system` is empty. A string `input` is used as `prompt` when `prompt` and `messages` are empty. `input` items with a role and content become `messages` when `messages` is empty. Sending both `messages` and `input` items throws `UNSUPPORTED_REQUEST_FIELD`. An enabled server tool, `responseFormat`, `rawOpenRouterOverrides`, `apiMode`, or a `server_tool` tool choice also throws. `toolChoice: "none"` omits tools. A `data:image/(png|jpeg|jpg|gif|webp);base64,...` part is sent as Converse image bytes (`jpg` is sent as `jpeg`). Any other image URL, and any other non-text part, throws `UNSUPPORTED_CONTENT`.
+
+## Entrypoints
+
+| Method | What it does |
+| --- | --- |
+| `dispatcher.run(request)` | Non-streaming call. Returns answer text, optional reasoning text, usage, tool results, and diagnostics. |
+| `dispatcher.executeStreamingChat(request)` | The only streaming entrypoint. Yields typed events. |
+| `dispatcher.compile(request)` | Same preparation as a live call, without sending. |
+| `dispatcher.refreshMcp()` | Reloads MCP servers that implement `listTools`. A failed reload keeps the previous list. |
+
+`compile()` returns a provider payload plus `requestedModel`, `effectiveModel`, and `reasoningResolution` when reasoning was involved:
+
+- OpenRouter: `{ provider, url, headers, body, warnings }`
+- Bedrock: `{ provider, modelId, input }`
+- OpenAI: `{ provider, url, headers, body, warnings }`
+
+`Authorization`, `x-api-key`, and `api-key` are replaced with `[redacted]` in the compiled result. Execution sends the real headers. A streaming call adds only the transport stream flag (`stream: true`, or Bedrock `ConverseStream`).
+
+## MCP tools
+
+Pass connected MCP servers to `createAiDispatcher`. The dispatcher does not spawn processes or open transports. It lists the tools you already fetched and calls `callTool` when the model uses one.
+
+```ts
+const dispatcher = createAiDispatcher({
+  openai: { apiKey: process.env.OPENAI_API_KEY },
+  mcp: {
+    servers: [{
+      id: "fs",
+      tools: [{
+        name: "read_file",
+        description: "Read a file",
+        inputSchema: { type: "object", properties: { path: { type: "string" } } }
+      }],
+      callTool: (name, args) => session.callTool({ name, arguments: args }),
+      listTools: async () => (await session.listTools()).tools
+    }]
+  }
+});
+
+await dispatcher.run({ model: "gpt-5.4", prompt: "Read notes.txt" });
+```
+
+Each tool is exposed as `${serverId}__${toolName}`. `callTool` still receives the raw MCP name. Server ids and tool names must match `^[A-Za-z0-9_-]+$`, and the exposed name must be at most 64 characters. A missing description is sent as an empty string. A missing `inputSchema` is sent as `{ type: "object", properties: {} }`.
+
+`run()` and `compile()` attach every registered tool. `executeStreamingChat` does not attach them and does not run them. Set `mcp: false` or `mcp: []` on a request to attach none. Set `mcp: ["fs__read_file"]` to attach that tool only. An unknown name in that list throws `MCP_TOOL_NOT_FOUND`.
+
+A `functionTools` entry with the same exposed name replaces the MCP tool for that call. If that entry has no executor, the MCP `callTool` does not run. An executor already stored on `openrouter.tools`, `bedrock.tools`, or `openai.tools` under the exposed name runs instead of `callTool`.
+
+Text blocks in an MCP result are joined and returned to the model. `isError: true` fails that tool call. Any other result is JSON. Bedrock `toolChoice: "none"` still omits tools. OpenRouter advisor, subagent, and fusion cannot call these sessions.
+
+`await dispatcher.refreshMcp()` reloads servers that implement `listTools` and leaves the others unchanged. Overlapping reloads run one after another. A failed reload, including a list that breaks the name rules, throws `MCP_LIST_FAILED` and keeps the previous catalog. A call already in progress keeps the tools it prepared.
+
+## Reasoning effort
+
+`reasoningEffort` is `minimal | low | medium | high | max`.
+
+| Request | Catalog |
+| --- | --- |
+| No `reasoningEffort` and no explicit control | Not called. The model id is forwarded as written, including ids the catalog does not know. |
+| `reasoningEffort` only | `resolveReasoning({ target, model, effort })` once for the original model. A catalog replacement model is the effective model and is not resolved again. |
+| Explicit control only | Kept. The catalog is not called. |
+| Both | The explicit control wins. The catalog body, model switch, and prompt prefix are not applied. `reasoningResolution.bypassed` is `true`, and `outcome` is omitted. |
+
+Explicit controls are transport fields:
+
+- OpenRouter and OpenAI: `request.reasoning`.
+- Bedrock: `request.bedrockControls.additionalModelRequestFields`.
+
+An OpenRouter `reasoning` object on a Bedrock call is not a Bedrock control. With `reasoningEffort`, the catalog still runs and that object is removed. Without `reasoningEffort`, the call fails with `UNSUPPORTED_REQUEST_FIELD`.
+
+Outcomes:
+
+- `applied` — the catalog wrote the requested effort.
+- `degraded` — the catalog wrote a supported nearby 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`.
+
+The dispatcher does not rank efforts, invent token budgets, or rewrite `maxTokens`. Profile notes about output-token headroom stay on the catalog profile. The directive body already contains companion fields the wire needs, and those fields are merged onto the compiled body.
+
+## Answers and reasoning text
+
+`response.text` is answer text. `response.reasoningText` is set only when the provider returned reasoning text. It is omitted when there is none.
+
+`response.usage` keeps the runtime usage fields: `inputTokens`, `outputTokens`, `totalTokens`, `costUsd`, and `raw`. When the catalog ran and published reasoning-token paths, `usage.reasoningTokens` is the first path that yields a number. A path that yields nothing removes a runtime-supplied `reasoningTokens` value.
+
+`response.reasoningResolution` is present when `reasoningEffort` was set or an explicit control bypassed the catalog:
+
+```ts
+{
+  requestedEffort: "max",
+  target: "openrouter",
+  requestedModel: "~google/gemini-flash-latest",
+  effectiveModel: "~google/gemini-flash-latest",
+  outcome: "degraded",
+  bypassed: false
+}
+```
+
+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.
+
+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.
+
+## Streaming
+
+```ts
+for await (const event of dispatcher.executeStreamingChat(request)) {
+  if (event.type === "stream.text.delta") process.stdout.write(event.data.text);
+  if (event.type === "stream.reasoning.delta") { /* thought text */ }
+}
+```
+
+Events, each with `type`, `requestId`, and `data`:
+
+| Event | `data` |
+| --- | --- |
+| `stream.start` | `model`, `apiMode`, `entrypoint`, and `reasoningResolution` when present |
+| `stream.text.delta` | `{ text }` |
+| `stream.reasoning.delta` | `{ text }` |
+| `stream.tool_call.delta` | `index`, optional `id`, `name`, `argumentsDelta` |
+| `stream.usage` | `{ usage }` |
+| `stream.warning` | `{ warning }` |
+| `stream.error` | `{ error }` |
+| `stream.done` | `text`, optional `finishReason`, `model`, optional `reasoningText`, optional `reasoningResolution` |
+
+## Tools
+
+Local function tools work on all three providers. OpenRouter, Bedrock, and direct OpenAI run the tool loop when every returned call has an `executor` on the tool or in that provider's `tools` registry. The loop defaults are 8 iterations and 20 function calls. On direct OpenAI, a call with no executor stops the loop: `run()` returns `requires_action` and does not send another request. Send that tool result back as a `role: "tool"` message with `toolCallId`. Streaming stays one request and does not run executors. Exceeding `maxFunctionToolCalls` on direct OpenAI fails the run with `FUNCTION_TOOL_LIMIT`.
+
+OpenRouter server tools are `webSearch`, `webFetch`, `datetime`, `imageGeneration`, `applyPatch`, `fusion`, `advisor`, and `subagent`. Each policy has a `mode` of `disabled`, `allowed`, or `required`. Bedrock and direct OpenAI throw `UNSUPPORTED_REQUEST_FIELD` when any of them is enabled, and also reject a `server_tool` tool choice. A policy whose mode is `disabled` is not enabled.
+
+### Nested OpenRouter tools
+
+Fusion, advisor, and subagent policies can set `reasoning` or `reasoningEffort`. They are not separate dispatcher calls. Before compilation, and only for OpenRouter, the dispatcher settles each policy once:
+
+1. A child `reasoning` object stays.
+2. Otherwise a child `reasoningEffort` is resolved with target `openrouter` and that tool's model.
+3. Otherwise a parent `reasoningEffort` is resolved the same way for advisor `model`, subagent `model`, and fusion `judgeModel`.
+4. Otherwise, when the parent supplied only an explicit `reasoning` object, the OpenRouter runtime copies that object onto nested tools that omit their own.
+5. A nested tool with no model id is not looked up and does not inherit the parent wire body.
+
+Each nested model is resolved on its own. A parent Bedrock or OpenAI body is never reused as another target's thinking config. A parent `reasoningEffort` also stops the OpenRouter runtime from copying the parent `reasoning` object onto those nested tools.
+
+## Escape hatches
+
+Set the provider control and leave `reasoningEffort` unset when you already have a wire object:
+
+```ts
+await dispatcher.run({
+  provider: "openrouter",
+  model: "openai/gpt-5.2",
+  prompt: "Hello",
+  reasoning: { effort: "low" }
+});
+
+await dispatcher.run({
+  provider: "bedrock",
+  model: "anthropic.claude-fable-5-1",
+  prompt: "Hello",
+  bedrockControls: {
+    additionalModelRequestFields: {
+      thinking: { type: "adaptive" },
+      output_config: { effort: "low" }
+    }
+  }
+});
+```
+
+`rawOpenRouterOverrides` still merges onto an OpenRouter body. It is rejected on Bedrock and direct OpenAI.
+
+## Supported features
+
+| Feature | OpenRouter | Bedrock | OpenAI Responses |
+| --- | --- | --- | --- |
+| `run`, `compile`, `executeStreamingChat` | yes | yes | yes |
+| `reasoningEffort` via the catalog | yes | yes | yes |
+| Explicit reasoning control | `reasoning` | `bedrockControls.additionalModelRequestFields` | `reasoning` |
+| Local function tools | yes, including the tool loop | yes, including the tool loop | yes, when every returned call has an executor; otherwise `requires_action` |
+| MCP tools from `mcp.servers` | `run` and `compile` | `run` and `compile` | `run` and `compile`. Streaming does not receive them |
+| OpenRouter server tools (fusion, advisor, subagent, datetime, and the rest) | yes | `UNSUPPORTED_REQUEST_FIELD` when enabled | `UNSUPPORTED_REQUEST_FIELD` when enabled |
+| `responseFormat` | forwarded | `UNSUPPORTED_REQUEST_FIELD` | placed on Responses `text` |
+| `apiMode: "chat"`, `rawOpenRouterOverrides` | OpenRouter fields | `UNSUPPORTED_REQUEST_FIELD` | `UNSUPPORTED_REQUEST_FIELD` |
+| File content parts | forwarded | non-text parts throw `UNSUPPORTED_CONTENT`, except data-URL images | `input_file` |
+
+## Errors
+
+Catalog failures throw `AiDispatcherError` with `code`, `message`, and the catalog `details`. Dispatcher codes include:
+
+| Code | When |
+| --- | --- |
+| `PROVIDER_NOT_IMPLEMENTED` | Provider is not `openrouter`, `bedrock`, or `openai` |
+| `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 |
+| `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 has no model id |
+| `INPUT_REQUIRED` | Direct OpenAI has no messages, input, or prompt |
+| `OPENAI_API_KEY_MISSING` | Direct OpenAI has no key |
+| `PROVIDER_AUTH_FAILED` | OpenAI HTTP `401` or `403` |
+| `PROVIDER_MODEL_NOT_FOUND` | OpenAI HTTP `404` |
+| `PROVIDER_REQUEST_FAILED` | Other OpenAI HTTP failures |
+| `PROVIDER_RETRYABLE` / `PROVIDER_GATEWAY_UNREACHABLE` | OpenAI transport failures after retries, including timeout |
+| `FUNCTION_TOOL_LIMIT` | Direct OpenAI function-tool calls exceed `maxFunctionToolCalls` |
+| `UNSUPPORTED_CONTENT` | Bedrock received an image URL or content part it cannot send |
+| `MCP_SERVER_INVALID` | An MCP server is missing an id, a tools array, or `callTool`, or a server id is repeated |
+| `MCP_TOOL_NAME_INVALID` | An MCP server id or tool name uses characters other than letters, numbers, underscores, and hyphens, or the exposed name is longer than 64 characters |
+| `MCP_TOOL_NAME_CONFLICT` | Two MCP tools share an exposed name |
+| `MCP_TOOL_NOT_FOUND` | `request.mcp` names a tool that is not registered, or `request.mcp` is not `false` or a list of names |
+| `MCP_LIST_FAILED` | `refreshMcp()` failed, or the new list breaks the name rules. The previous catalog stays |
+
+OpenAI HTTP failures such as `401` return a failed response from `run()`. `FUNCTION_TOOL_LIMIT` does too. Streaming yields `stream.error` and then throws, matching the other transports.
+
+## 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.
+
+## 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.
+- 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 and direct OpenAI reject them.
+- Direct OpenAI streaming does not run the function-tool loop. MCP tools are not attached to `executeStreamingChat` on any provider.
+- 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.