@x12i/ai-dispatcher 2.4.0 → 3.0.0

package/README.md

@@ -4,7 +4,7 @@ One request shape for OpenRouter, AWS Bedrock, the OpenAI Responses API, and Clo
 
 **Implemented providers:** `openrouter`, `bedrock`, `openai`, `cloudflare`. Any other provider throws `PROVIDER_NOT_IMPLEMENTED`.
 
-The package is `@x12i/ai-dispatcher` 2.4.0. It runs on Node 20 or newer and publishes ESM and CommonJS from the same entry.
+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.
 
 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.2.0`, `@x12i/provider-metadata@^1.2.1`, `@x12i/openrouter-runtime@^2.2.1`, and `@x12i/bedrock-runtime@^2.2.2`. `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.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.
 
 ## One request
 
@@ -128,7 +128,7 @@ OpenAI retries `429`, `408`, and `5xx` with backoff capped at 5 seconds. After t
 
 ## The request
 
-`AiDispatcherRequest` is the OpenRouter runtime request plus `provider`, `orgId`, `stepId`, `skillId`, `reasoningEffort`, `bedrockControls`, `cache`, `cloudflare`, and `mcp`. `agentId` is already on that request.
+`AiDispatcherRequest` is the OpenRouter runtime request plus `provider`, `orgId`, `stepId`, `skillId`, `reasoningEffort`, `bedrockControls`, `cache`, `cloudflare`, `mcp`, and `aiInput`. `agentId` is already on that request.
 
 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`.
 
@@ -152,6 +152,7 @@ Text can arrive as `prompt`, `messages`, `input`, `system`, or `instructions`. A
 | `cache` | Optional prompt-cache intent: `mode` (`auto`, `explicit`, or `disabled`), `key`, and `ttl` (`5m`, `30m`, or `1h`). Omit it and the compiled body is unchanged. `explicit` places one breakpoint at the end of `system` or `instructions` when that model supports it. On Cloudflare it also sets AI Gateway cache headers. |
 | `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. |
+| `aiInput` | `false` skips input preparation. A settings object overrides the dispatcher default for this call. Stripped before the provider payload is built. See [Input preparation](#input-preparation). |
 
 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.
 
@@ -195,10 +196,10 @@ Bedrock receives `id`, `model`, `messages`, `system`, `prompt`, `temperature`, `
 | --- | --- |
 | `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.compile(request)` | Returns a `Promise` of the 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:
+`compile()` returns a `Promise`. The value is a provider payload plus `requestedModel`, `effectiveModel`, and `reasoningResolution` when reasoning was involved. `inputResolution` is included when preparation is off, when model-visible text changes, or when the chosen codec is not the outline, JSON, or text baseline:
 
 - OpenRouter: `{ provider, url, headers, body, warnings }`
 - Bedrock: `{ provider, modelId, input }`
@@ -207,6 +208,20 @@ Bedrock receives `id`, `model`, `messages`, `system`, `prompt`, `temperature`, `
 
 `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`).
 
+## Input preparation
+
+Preparation is on unless `aiInput: false` is set on the dispatcher or on the request. A request settings object turns a disabled dispatcher back on for that call. The default policy is compact mode, `codec: "auto"`, `sharing: "auto"`, raw framing, and no tokenizer. A string prompt stays the original string unless it contains a JSON document, which compact opens in place. A plain object, including a tool result, becomes compact outline. `codec: "json"` keeps compact JSON. `mode: "raw"` keeps `JSON.stringify`. The dispatcher does not read `AI_INPUT_*` or `.env`.
+
+Prepared text is `prompt`, `system`, `instructions`, message text, string `input`, and `text` or `input_text` parts. Object results from request tools, MCP tools, and provider `tools` executors use the same policy before the runtime stringifies them. `Date`, class instances, and `undefined` stay on `JSON.stringify`.
+
+`mode` (`compact`, `readable`, `raw`), `codec` (`auto`, `json`, `toon`, `text`, `outline`), `readableFormat`, `sharing`, and `framing` can be set on the factory or the request. Approval lookup uses `aiInput.model` when set, and otherwise the effective model for the call. Changing `request.model` changes that id. `aiInput.model` does not change the provider model. `gpt-5.4` and `openai/gpt-5.4` are different keys.
+
+The built-in approval list is empty, so automatic TOON and `shared-v1` stay on the direct baseline until the caller passes a matching `CapabilityApproval` and a tokenizer. Explicit `codec: "toon"` does not need an approval. When the choice stays on outline, JSON, or text, the model sees the unframed body. This package does not claim release gate 9.
+
+`tokenizer: "gpt:o200k_base"` (also `cl100k_base`, `p50k_base`, `p50k_edit`, `r50k_base`) loads `@x12i/ai-input/tokenizers/gpt` for that call. If `gpt-tokenizer` is not installed, the call fails with `AI_INPUT_FAILED`. `ajv` is not used.
+
+`run()` and `compile()` attach `inputResolution` when preparation is disabled, when any model-visible text changes, or when the chosen codec is not the baseline. The inert default omits the field. The record has `enabled`, `model`, `mode`, `codec`, `representation`, `approvalSource`, and `changed`. Requirements are in [.operations/ai-input.md](.operations/ai-input.md).
+
 ## 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.
@@ -486,6 +501,7 @@ Catalog failures throw `AiDispatcherError` with `code`, `message`, and the catal
 | `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 |
+| `AI_INPUT_FAILED` | Input preparation failed. `details.code` is the `@x12i/ai-input` code, such as `ADAPTER_UNAVAILABLE` when a `gpt:*` tokenizer is requested and `gpt-tokenizer` is not installed |
 
 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.
 
@@ -503,3 +519,6 @@ Pass `logger` on the dispatcher. `run` and `executeStreamingChat` emit `ai-dispa
 - 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.
+- 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.