@x12i/ai-dispatcher 3.0.0 → 3.1.0

package/README.md

@@ -144,7 +144,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 +156,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 +169,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 +180,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.
 

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,
@@ -2650,6 +2651,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 +3004,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 +4034,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,