@x12i/ai-dispatcher 2.4.1 → 3.1.0

package/dist/index.d.cts

@@ -3,6 +3,8 @@ export { ReasoningEffort, ReasoningOutcome, registerHostIntents } from '@x12i/ai
 import * as _x12i_openrouter_runtime from '@x12i/openrouter-runtime';
 import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeUsage, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
 export { CompiledOpenRouterRequest, METADATA_NORMALIZATION_MAP, NormalizedMetadataKey, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent, canonicalMetadataKey, decodeProviderMetadata, normalizeMetadata } from '@x12i/openrouter-runtime';
+import { CapabilityApproval } from '@x12i/ai-input/core';
+export { CapabilityApproval } from '@x12i/ai-input/core';
 import { CompiledBedrockRequest, BedrockRuntimeOptions } from '@x12i/bedrock-runtime';
 export { BedrockClientLike, BedrockCredentials, BedrockRuntimeOptions, CompiledBedrockRequest } from '@x12i/bedrock-runtime';
 
@@ -93,6 +95,52 @@ interface OpenAiRuntimeOptions {
     logger?: RuntimeLogger;
 }
 
+/** Compact and readable write outline. Raw is `JSON.stringify` or the original string. */
+type AiInputMode = "compact" | "readable" | "raw";
+/** Wire codec chosen for one prepared value. Compact and readable default to `outline`. */
+type AiInputCodec = "json" | "toon" | "text" | "outline";
+/** `auto` stays on outline, JSON, or text until a matching approval and a tokenizer allow an alternate. */
+type AiInputCodecChoice = "auto" | AiInputCodec;
+type AiInputReadableFormat = "auto" | "json" | "toon" | "outline";
+type AiInputSharing = "auto" | "off";
+/** `raw` is the model body. `self-describing` adds the `@ai-input/1` header. */
+type AiInputFraming = "self-describing" | "raw";
+/** Optional `gpt-tokenizer` encodings. The package is not installed by the dispatcher. */
+type AiInputTokenizer = "none" | "gpt:o200k_base" | "gpt:cl100k_base" | "gpt:p50k_base" | "gpt:p50k_edit" | "gpt:r50k_base";
+/**
+ * How one dispatcher prepares model-visible input.
+ * Omitted fields use compact mode, `codec: "auto"`, `sharing: "auto"`, raw framing, and no tokenizer.
+ * Compact writes outline for structured values. `codec: "json"` keeps compact JSON. `mode: "raw"` keeps `JSON.stringify`.
+ */
+interface AiInputSettings {
+    mode?: AiInputMode;
+    codec?: AiInputCodecChoice;
+    readableFormat?: AiInputReadableFormat;
+    sharing?: AiInputSharing;
+    framing?: AiInputFraming;
+    /**
+     * Approval lookup id. Defaults to the effective model for the call.
+     * Does not change the model sent to the provider.
+     */
+    model?: string;
+    tokenizer?: AiInputTokenizer;
+    /** Caller approvals. The dispatcher ships none. */
+    approvals?: readonly CapabilityApproval[];
+}
+/**
+ * What preparation did for one call.
+ * Omitted when preparation stayed on the unchanged JSON or text baseline.
+ */
+interface InputResolution {
+    enabled: boolean;
+    /** Approval lookup id. Omitted when preparation is off or the call has no model id. */
+    model?: string;
+    mode?: AiInputMode;
+    codec?: AiInputCodec;
+    representation?: "value" | "shared-v1";
+    approvalSource?: "none" | "registry" | "explicit-caller" | "baseline";
+    changed: boolean;
+}
 /** Caller role stamp. Omitted or blank fields are not stored. */
 interface RoleStamp {
     role?: string;
@@ -194,6 +242,13 @@ interface AiDispatcherRequest extends RuntimeRequest {
      * `endpoint` wins over `apiMode`. Stripped before the provider request is compiled.
      */
     cloudflare?: CloudflareRequestOptions;
+    /**
+     * Input preparation for this call.
+     * Omit it to use the dispatcher default. `false` skips preparation.
+     * A settings object overrides the dispatcher default for this call, including turning it back on.
+     * Stripped before the provider payload is built. This is not the Responses `input` field.
+     */
+    aiInput?: false | AiInputSettings;
 }
 interface DispatcherMcpTool {
     name: string;
@@ -234,9 +289,17 @@ interface AiDispatcherOptions {
      * The dispatcher trims on every call and adds a `METADATA_RECORD_TRIMMED` warning when it drops keys.
      * The default keeps `agentId`, `orgId`, `stepId`, `skillId`, `role`, `roleLayer`,
      * `roleDigest`, `profileChoice`, `recordId`, and `objectType`.
+     * A custom list replaces that default. Include `session_id`, `xtivix.caller`, and `xtivix.gate` when you pass one.
+     * With the default list, those short values stay until every longer unlisted value,
+     * including `xtivix.execution`, has been dropped.
      */
     metadataPriority?: readonly string[];
     logger?: RuntimeLogger;
+    /**
+     * Default input preparation. Omit it and every call uses compact `@x12i/ai-input`.
+     * `false` skips preparation unless a call passes settings.
+     */
+    aiInput?: false | AiInputSettings;
 }
 interface CompiledOpenAiRequest {
     provider: "openai";
@@ -248,6 +311,7 @@ interface CompiledOpenAiRequest {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }
 interface CompiledCloudflareRequest {
     provider: "cloudflare";
@@ -261,6 +325,7 @@ interface CompiledCloudflareRequest {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }
 type CompiledAiRequest = (CompiledOpenRouterRequest & {
     provider: "openrouter";
@@ -268,12 +333,14 @@ type CompiledAiRequest = (CompiledOpenRouterRequest & {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }) | (CompiledBedrockRequest & {
     provider: "bedrock";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }) | CompiledOpenAiRequest | CompiledCloudflareRequest;
 interface AiDispatcherUsage extends RuntimeUsage {
     /** Tokens read from a prompt cache. Omitted when the provider did not report any. */
@@ -286,6 +353,7 @@ interface AiDispatcherResponse extends RuntimeResponse {
     reasoningText?: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
     usage?: AiDispatcherUsage;
 }
 interface ProviderCallOptions {
@@ -309,16 +377,22 @@ interface CompiledOpenAiWireShape {
 interface AiDispatcher {
     run(request: AiDispatcherRequest): Promise<AiDispatcherResponse>;
     executeStreamingChat(request: AiDispatcherRequest): AsyncIterable<RuntimeStreamEvent>;
-    compile(request: AiDispatcherRequest): CompiledAiRequest;
+    compile(request: AiDispatcherRequest): Promise<CompiledAiRequest>;
     /** Relists servers that implement `listTools`. Other servers stay as registered. */
     refreshMcp(): Promise<void>;
     readonly provider: AiProviderId;
 }
 
-/** Identity keys stay when a record has to be trimmed. Earlier entries are kept ahead of later ones. */
+/**
+ * Identity keys stay when a record has to be trimmed. Earlier entries are kept ahead of later ones.
+ * `session_id`, `xtivix.caller`, and `xtivix.gate` stay off this list. A custom `metadataPriority` should include them.
+ */
 declare const DEFAULT_METADATA_PRIORITY: readonly ["agentId", "orgId", "stepId", "skillId", "role", "roleLayer", "roleDigest", "profileChoice", "recordId", "objectType"];
 declare function createAiDispatcher(options?: AiDispatcherOptions): AiDispatcher;
 
+/** Stored as `xtivix.gate` on every call this package packs. */
+declare const AI_DISPATCHER_GATE = "ai-dispatcher";
+
 declare class AiDispatcherError extends Error {
     readonly code: string;
     readonly details?: unknown | undefined;
@@ -334,4 +408,4 @@ declare function stripReasoningHistoryFields<T>(message: T, paths: readonly stri
 
 declare function resolveProvider(requestProvider: AiProviderId | undefined, defaultProvider: AiProviderId): ImplementedAiProvider;
 
-export { type AiDispatcher, AiDispatcherError, type AiDispatcherOptions, type AiDispatcherRequest, type AiDispatcherResponse, type AiDispatcherUsage, type AiProviderAdapter, type AiProviderId, type CacheMode, type CacheOutcome, type CachePolicy, type CacheResolution, type CacheTtl, type CloudflareBackoff, type CloudflareCallContext, type CloudflareEndpoint, type CloudflareEndpointChoice, type CloudflareGatewayControls, type CloudflareRequestOptions, type CloudflareRunOptions, type CloudflareRuntimeOptions, type CloudflareWebhookFormat, type CompiledAiRequest, type CompiledCloudflareRequest, type CompiledOpenAiRequest, DEFAULT_METADATA_PRIORITY, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, type RoleStamp, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };
+export { AI_DISPATCHER_GATE, type AiDispatcher, AiDispatcherError, type AiDispatcherOptions, type AiDispatcherRequest, type AiDispatcherResponse, type AiDispatcherUsage, type AiInputCodec, type AiInputCodecChoice, type AiInputFraming, type AiInputMode, type AiInputReadableFormat, type AiInputSettings, type AiInputSharing, type AiInputTokenizer, type AiProviderAdapter, type AiProviderId, type CacheMode, type CacheOutcome, type CachePolicy, type CacheResolution, type CacheTtl, type CloudflareBackoff, type CloudflareCallContext, type CloudflareEndpoint, type CloudflareEndpointChoice, type CloudflareGatewayControls, type CloudflareRequestOptions, type CloudflareRunOptions, type CloudflareRuntimeOptions, type CloudflareWebhookFormat, type CompiledAiRequest, type CompiledCloudflareRequest, type CompiledOpenAiRequest, DEFAULT_METADATA_PRIORITY, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type InputResolution, type OpenAiRuntimeOptions, type ReasoningResolution, type RoleStamp, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { ReasoningEffort, ReasoningOutcome, registerHostIntents } from '@x12i/ai
 import * as _x12i_openrouter_runtime from '@x12i/openrouter-runtime';
 import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeUsage, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
 export { CompiledOpenRouterRequest, METADATA_NORMALIZATION_MAP, NormalizedMetadataKey, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent, canonicalMetadataKey, decodeProviderMetadata, normalizeMetadata } from '@x12i/openrouter-runtime';
+import { CapabilityApproval } from '@x12i/ai-input/core';
+export { CapabilityApproval } from '@x12i/ai-input/core';
 import { CompiledBedrockRequest, BedrockRuntimeOptions } from '@x12i/bedrock-runtime';
 export { BedrockClientLike, BedrockCredentials, BedrockRuntimeOptions, CompiledBedrockRequest } from '@x12i/bedrock-runtime';
 
@@ -93,6 +95,52 @@ interface OpenAiRuntimeOptions {
     logger?: RuntimeLogger;
 }
 
+/** Compact and readable write outline. Raw is `JSON.stringify` or the original string. */
+type AiInputMode = "compact" | "readable" | "raw";
+/** Wire codec chosen for one prepared value. Compact and readable default to `outline`. */
+type AiInputCodec = "json" | "toon" | "text" | "outline";
+/** `auto` stays on outline, JSON, or text until a matching approval and a tokenizer allow an alternate. */
+type AiInputCodecChoice = "auto" | AiInputCodec;
+type AiInputReadableFormat = "auto" | "json" | "toon" | "outline";
+type AiInputSharing = "auto" | "off";
+/** `raw` is the model body. `self-describing` adds the `@ai-input/1` header. */
+type AiInputFraming = "self-describing" | "raw";
+/** Optional `gpt-tokenizer` encodings. The package is not installed by the dispatcher. */
+type AiInputTokenizer = "none" | "gpt:o200k_base" | "gpt:cl100k_base" | "gpt:p50k_base" | "gpt:p50k_edit" | "gpt:r50k_base";
+/**
+ * How one dispatcher prepares model-visible input.
+ * Omitted fields use compact mode, `codec: "auto"`, `sharing: "auto"`, raw framing, and no tokenizer.
+ * Compact writes outline for structured values. `codec: "json"` keeps compact JSON. `mode: "raw"` keeps `JSON.stringify`.
+ */
+interface AiInputSettings {
+    mode?: AiInputMode;
+    codec?: AiInputCodecChoice;
+    readableFormat?: AiInputReadableFormat;
+    sharing?: AiInputSharing;
+    framing?: AiInputFraming;
+    /**
+     * Approval lookup id. Defaults to the effective model for the call.
+     * Does not change the model sent to the provider.
+     */
+    model?: string;
+    tokenizer?: AiInputTokenizer;
+    /** Caller approvals. The dispatcher ships none. */
+    approvals?: readonly CapabilityApproval[];
+}
+/**
+ * What preparation did for one call.
+ * Omitted when preparation stayed on the unchanged JSON or text baseline.
+ */
+interface InputResolution {
+    enabled: boolean;
+    /** Approval lookup id. Omitted when preparation is off or the call has no model id. */
+    model?: string;
+    mode?: AiInputMode;
+    codec?: AiInputCodec;
+    representation?: "value" | "shared-v1";
+    approvalSource?: "none" | "registry" | "explicit-caller" | "baseline";
+    changed: boolean;
+}
 /** Caller role stamp. Omitted or blank fields are not stored. */
 interface RoleStamp {
     role?: string;
@@ -194,6 +242,13 @@ interface AiDispatcherRequest extends RuntimeRequest {
      * `endpoint` wins over `apiMode`. Stripped before the provider request is compiled.
      */
     cloudflare?: CloudflareRequestOptions;
+    /**
+     * Input preparation for this call.
+     * Omit it to use the dispatcher default. `false` skips preparation.
+     * A settings object overrides the dispatcher default for this call, including turning it back on.
+     * Stripped before the provider payload is built. This is not the Responses `input` field.
+     */
+    aiInput?: false | AiInputSettings;
 }
 interface DispatcherMcpTool {
     name: string;
@@ -234,9 +289,17 @@ interface AiDispatcherOptions {
      * The dispatcher trims on every call and adds a `METADATA_RECORD_TRIMMED` warning when it drops keys.
      * The default keeps `agentId`, `orgId`, `stepId`, `skillId`, `role`, `roleLayer`,
      * `roleDigest`, `profileChoice`, `recordId`, and `objectType`.
+     * A custom list replaces that default. Include `session_id`, `xtivix.caller`, and `xtivix.gate` when you pass one.
+     * With the default list, those short values stay until every longer unlisted value,
+     * including `xtivix.execution`, has been dropped.
      */
     metadataPriority?: readonly string[];
     logger?: RuntimeLogger;
+    /**
+     * Default input preparation. Omit it and every call uses compact `@x12i/ai-input`.
+     * `false` skips preparation unless a call passes settings.
+     */
+    aiInput?: false | AiInputSettings;
 }
 interface CompiledOpenAiRequest {
     provider: "openai";
@@ -248,6 +311,7 @@ interface CompiledOpenAiRequest {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }
 interface CompiledCloudflareRequest {
     provider: "cloudflare";
@@ -261,6 +325,7 @@ interface CompiledCloudflareRequest {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }
 type CompiledAiRequest = (CompiledOpenRouterRequest & {
     provider: "openrouter";
@@ -268,12 +333,14 @@ type CompiledAiRequest = (CompiledOpenRouterRequest & {
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }) | (CompiledBedrockRequest & {
     provider: "bedrock";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
 }) | CompiledOpenAiRequest | CompiledCloudflareRequest;
 interface AiDispatcherUsage extends RuntimeUsage {
     /** Tokens read from a prompt cache. Omitted when the provider did not report any. */
@@ -286,6 +353,7 @@ interface AiDispatcherResponse extends RuntimeResponse {
     reasoningText?: string;
     reasoningResolution?: ReasoningResolution;
     cacheResolution?: CacheResolution;
+    inputResolution?: InputResolution;
     usage?: AiDispatcherUsage;
 }
 interface ProviderCallOptions {
@@ -309,16 +377,22 @@ interface CompiledOpenAiWireShape {
 interface AiDispatcher {
     run(request: AiDispatcherRequest): Promise<AiDispatcherResponse>;
     executeStreamingChat(request: AiDispatcherRequest): AsyncIterable<RuntimeStreamEvent>;
-    compile(request: AiDispatcherRequest): CompiledAiRequest;
+    compile(request: AiDispatcherRequest): Promise<CompiledAiRequest>;
     /** Relists servers that implement `listTools`. Other servers stay as registered. */
     refreshMcp(): Promise<void>;
     readonly provider: AiProviderId;
 }
 
-/** Identity keys stay when a record has to be trimmed. Earlier entries are kept ahead of later ones. */
+/**
+ * Identity keys stay when a record has to be trimmed. Earlier entries are kept ahead of later ones.
+ * `session_id`, `xtivix.caller`, and `xtivix.gate` stay off this list. A custom `metadataPriority` should include them.
+ */
 declare const DEFAULT_METADATA_PRIORITY: readonly ["agentId", "orgId", "stepId", "skillId", "role", "roleLayer", "roleDigest", "profileChoice", "recordId", "objectType"];
 declare function createAiDispatcher(options?: AiDispatcherOptions): AiDispatcher;
 
+/** Stored as `xtivix.gate` on every call this package packs. */
+declare const AI_DISPATCHER_GATE = "ai-dispatcher";
+
 declare class AiDispatcherError extends Error {
     readonly code: string;
     readonly details?: unknown | undefined;
@@ -334,4 +408,4 @@ declare function stripReasoningHistoryFields<T>(message: T, paths: readonly stri
 
 declare function resolveProvider(requestProvider: AiProviderId | undefined, defaultProvider: AiProviderId): ImplementedAiProvider;
 
-export { type AiDispatcher, AiDispatcherError, type AiDispatcherOptions, type AiDispatcherRequest, type AiDispatcherResponse, type AiDispatcherUsage, type AiProviderAdapter, type AiProviderId, type CacheMode, type CacheOutcome, type CachePolicy, type CacheResolution, type CacheTtl, type CloudflareBackoff, type CloudflareCallContext, type CloudflareEndpoint, type CloudflareEndpointChoice, type CloudflareGatewayControls, type CloudflareRequestOptions, type CloudflareRunOptions, type CloudflareRuntimeOptions, type CloudflareWebhookFormat, type CompiledAiRequest, type CompiledCloudflareRequest, type CompiledOpenAiRequest, DEFAULT_METADATA_PRIORITY, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, type RoleStamp, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };
+export { AI_DISPATCHER_GATE, type AiDispatcher, AiDispatcherError, type AiDispatcherOptions, type AiDispatcherRequest, type AiDispatcherResponse, type AiDispatcherUsage, type AiInputCodec, type AiInputCodecChoice, type AiInputFraming, type AiInputMode, type AiInputReadableFormat, type AiInputSettings, type AiInputSharing, type AiInputTokenizer, type AiProviderAdapter, type AiProviderId, type CacheMode, type CacheOutcome, type CachePolicy, type CacheResolution, type CacheTtl, type CloudflareBackoff, type CloudflareCallContext, type CloudflareEndpoint, type CloudflareEndpointChoice, type CloudflareGatewayControls, type CloudflareRequestOptions, type CloudflareRunOptions, type CloudflareRuntimeOptions, type CloudflareWebhookFormat, type CompiledAiRequest, type CompiledCloudflareRequest, type CompiledOpenAiRequest, DEFAULT_METADATA_PRIORITY, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type InputResolution, type OpenAiRuntimeOptions, type ReasoningResolution, type RoleStamp, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };