@x12i/ai-dispatcher 1.4.0 → 2.0.0

package/dist/index.d.cts

@@ -1,16 +1,83 @@
 import * as _x12i_openrouter_runtime from '@x12i/openrouter-runtime';
-import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
-export { CompiledOpenRouterRequest, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent } from '@x12i/openrouter-runtime';
+import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeUsage, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
+export { CompiledOpenRouterRequest, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent, decodeProviderMetadata } from '@x12i/openrouter-runtime';
 import { ReasoningEffort, ReasoningOutcome } from '@x12i/ai-profiles';
 export { ReasoningEffort, ReasoningOutcome } from '@x12i/ai-profiles';
 import { CompiledBedrockRequest, BedrockRuntimeOptions } from '@x12i/bedrock-runtime';
 export { BedrockClientLike, BedrockCredentials, BedrockRuntimeOptions, CompiledBedrockRequest } from '@x12i/bedrock-runtime';
 
-type AiProviderId = "openrouter" | "openai" | "anthropic" | "google" | "azure" | "bedrock" | "groq" | "mistral" | "cohere" | "together" | "fireworks" | "xai" | "deepseek" | "custom";
-declare const IMPLEMENTED_AI_PROVIDERS: readonly ["openrouter", "bedrock", "openai"];
+type AiProviderId = "openrouter" | "openai" | "anthropic" | "google" | "azure" | "bedrock" | "groq" | "mistral" | "cohere" | "together" | "fireworks" | "xai" | "deepseek" | "cloudflare" | "custom";
+declare const IMPLEMENTED_AI_PROVIDERS: readonly ["openrouter", "bedrock", "openai", "cloudflare"];
 type ImplementedAiProvider = (typeof IMPLEMENTED_AI_PROVIDERS)[number];
 declare function isImplementedAiProvider(provider: string): provider is ImplementedAiProvider;
 
+/** Concrete Cloudflare AI REST endpoint. */
+type CloudflareEndpoint = "chat" | "responses" | "messages" | "run";
+/** `auto` picks chat, responses, or messages from the model id. */
+type CloudflareEndpointChoice = CloudflareEndpoint | "auto";
+type CloudflareBackoff = "constant" | "linear" | "exponential";
+type CloudflareWebhookFormat = "raw" | "chat";
+/** Per-request AI Gateway headers (`cf-aig-*`). */
+interface CloudflareGatewayControls {
+    skipCache?: boolean;
+    /** Seconds. Sent as `cf-aig-cache-ttl`. */
+    cacheTtlSeconds?: number;
+    cacheKey?: string;
+    collectLog?: boolean;
+    requestTimeoutMs?: number;
+    /** Sent as `cf-aig-max-attempts`. Cloudflare caps this at 5. */
+    maxGatewayAttempts?: number;
+    /** Sent as `cf-aig-retry-delay`. Cloudflare caps this at 60000. */
+    retryDelayMs?: number;
+    backoff?: CloudflareBackoff;
+    /** Merged into `cf-aig-metadata`. Request metadata wins on the same key. */
+    metadata?: Record<string, unknown>;
+}
+/** `/ai/run` background execution. `webhookUrl` requires `background: true`. */
+interface CloudflareRunOptions {
+    background?: boolean;
+    webhookUrl?: string;
+    webhookFormat?: CloudflareWebhookFormat;
+}
+/** Per-request overrides. Credentials stay on dispatcher options. */
+interface CloudflareRequestOptions extends CloudflareGatewayControls {
+    endpoint?: CloudflareEndpointChoice;
+    /** Workers AI (`@cf/`) defaults to `"default"` when this is omitted. */
+    gatewayId?: string;
+    run?: CloudflareRunOptions;
+}
+interface CloudflareRuntimeOptions extends CloudflareRequestOptions {
+    /** Or `CLOUDFLARE_API_TOKEN`. Needs Account > Workers AI > Read. */
+    apiToken?: string;
+    /** Or `CLOUDFLARE_ACCOUNT_ID`. */
+    accountId?: string;
+    /** Defaults to `https://api.cloudflare.com/client/v4`. */
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+    /** HTTP attempts for 429, 408, and 5xx. Defaults to 2. */
+    maxAttempts?: number;
+    fetch?: typeof globalThis.fetch;
+    /** Executors for function tools that do not carry their own `executor`. */
+    tools?: Record<string, RuntimeToolExecutor>;
+    logger?: RuntimeLogger;
+}
+/**
+ * Resolved call settings passed from preparation into the adapter.
+ * Request fields win over dispatcher options. `cache` comes from the dispatcher cache policy.
+ */
+interface CloudflareCallContext {
+    endpoint?: CloudflareEndpoint;
+    gatewayId?: string;
+    run?: CloudflareRunOptions;
+    gateway?: CloudflareGatewayControls;
+    cache?: {
+        skip: boolean;
+        ttlSeconds?: number;
+        key?: string;
+    };
+}
+
 interface OpenAiRuntimeOptions {
     apiKey?: string;
     /** Defaults to `https://api.openai.com/v1`. Requests are sent to `{baseUrl}/responses`. */
@@ -39,8 +106,52 @@ interface ReasoningResolution {
     outcome?: ReasoningOutcome;
     bypassed: boolean;
 }
+/** How a call asks for prompt caching. Omitted `mode` means `explicit`. */
+type CacheMode = "auto" | "explicit" | "disabled";
+/** Normalized cache lifetime. Providers fold this to a supported value. */
+type CacheTtl = "5m" | "30m" | "1h";
+/**
+ * `applied` — the requested caching was written.
+ * `degraded` — a nearby TTL was written and the call still runs.
+ * `ignored` — no cache marker was written and the call still runs.
+ */
+type CacheOutcome = "applied" | "degraded" | "ignored";
+/**
+ * Provider-neutral prompt-cache intent.
+ * One explicit breakpoint is placed at the end of the stable prefix
+ * (`system` or `instructions`) when the model supports it.
+ */
+interface CachePolicy {
+    mode?: CacheMode;
+    /** Stable id for caches that route on a key. Omitted from the wire when the dialect has no key field. */
+    key?: string;
+    ttl?: CacheTtl;
+}
+/** What the dispatcher did with `cache` for one call. */
+interface CacheResolution {
+    mode: CacheMode;
+    target: ImplementedAiProvider;
+    requestedModel: string;
+    effectiveModel: string;
+    outcome: CacheOutcome;
+    /** TTL written on the wire. Omitted when no TTL was sent. */
+    ttl?: CacheTtl;
+    keyPresent: boolean;
+}
 interface AiDispatcherRequest extends RuntimeRequest {
     provider?: AiProviderId;
+    /**
+     * Caller organization id. Stored in the one provider metadata record as `orgId`.
+     */
+    orgId?: string;
+    /**
+     * Caller step id. Stored in the one provider metadata record as `stepId`.
+     */
+    stepId?: string;
+    /**
+     * Caller skill id. Stored in the one provider metadata record as `skillId`.
+     */
+    skillId?: string;
     /**
      * Provider-neutral reasoning intent. The bundled catalog chooses the wire action.
      * An explicit provider control on the same request wins and the catalog is not called.
@@ -59,6 +170,17 @@ interface AiDispatcherRequest extends RuntimeRequest {
      * A string list attaches only those exposed names.
      */
     mcp?: false | string[];
+    /**
+     * Optional prompt-cache intent. Omit it and the compiled body is unchanged.
+     * `explicit` marks the end of `system` or `instructions` when the model supports it.
+     * On Cloudflare this also sets AI Gateway cache headers.
+     */
+    cache?: CachePolicy;
+    /**
+     * Cloudflare AI REST overrides for this call.
+     * `endpoint` wins over `apiMode`. Stripped before the provider request is compiled.
+     */
+    cloudflare?: CloudflareRequestOptions;
 }
 interface DispatcherMcpTool {
     name: string;
@@ -82,13 +204,15 @@ interface DispatcherMcpOptions {
 interface AiDispatcherOptions {
     /**
      * Default provider for run / stream / compile.
-     * Implemented: `"openrouter"` | `"bedrock"` | `"openai"`.
+     * Implemented: `"openrouter"` | `"bedrock"` | `"openai"` | `"cloudflare"`.
      */
     provider?: AiProviderId;
     openrouter?: OpenRouterRuntimeOptions;
     bedrock?: BedrockRuntimeOptions;
     /** Direct OpenAI Responses API. */
     openai?: OpenAiRuntimeOptions;
+    /** Cloudflare AI REST API: Workers AI and third-party models. */
+    cloudflare?: CloudflareRuntimeOptions;
     /** Connected MCP servers. The dispatcher does not open transports. */
     mcp?: DispatcherMcpOptions;
     logger?: RuntimeLogger;
@@ -102,27 +226,53 @@ interface CompiledOpenAiRequest {
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
+}
+interface CompiledCloudflareRequest {
+    provider: "cloudflare";
+    /** REST dialect selected for this call. */
+    endpoint: "chat" | "responses" | "messages" | "run";
+    url: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    warnings: _x12i_openrouter_runtime.RuntimeWarning[];
+    requestedModel: string;
+    effectiveModel: string;
+    reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
 }
 type CompiledAiRequest = (CompiledOpenRouterRequest & {
     provider: "openrouter";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
 }) | (CompiledBedrockRequest & {
     provider: "bedrock";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
-}) | CompiledOpenAiRequest;
+    cacheResolution?: CacheResolution;
+}) | CompiledOpenAiRequest | CompiledCloudflareRequest;
+interface AiDispatcherUsage extends RuntimeUsage {
+    /** Tokens read from a prompt cache. Omitted when the provider did not report any. */
+    cachedTokens?: number;
+    /** Tokens written to a prompt cache. Omitted when the provider did not report any. */
+    cacheWriteTokens?: number;
+}
 interface AiDispatcherResponse extends RuntimeResponse {
     /** Provider-exposed reasoning text. Omitted when the provider did not return any. */
     reasoningText?: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
+    usage?: AiDispatcherUsage;
 }
 interface ProviderCallOptions {
     finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
     extractStreamReasoning?: (event: unknown) => string | undefined;
     suppressNestedReasoningFallback?: boolean;
+    /** Set by preparation for the Cloudflare adapter. Callers do not set this. */
+    cloudflare?: CloudflareCallContext;
 }
 interface AiProviderAdapter {
     run(request: RuntimeRequest, call?: ProviderCallOptions): Promise<RuntimeResponse>;
@@ -161,4 +311,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 AiProviderAdapter, type AiProviderId, type CompiledAiRequest, type CompiledOpenAiRequest, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };
+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, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };

package/dist/index.d.ts

@@ -1,16 +1,83 @@
 import * as _x12i_openrouter_runtime from '@x12i/openrouter-runtime';
-import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
-export { CompiledOpenRouterRequest, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent } from '@x12i/openrouter-runtime';
+import { RuntimeToolExecutor, RuntimeLogger, RuntimeRequest, RuntimeResponse, RuntimeUsage, RuntimeStreamEvent, CompiledOpenRouterRequest, OpenRouterRuntimeOptions } from '@x12i/openrouter-runtime';
+export { CompiledOpenRouterRequest, OpenRouterRuntimeOptions, RuntimeDefaults, RuntimeLogger, RuntimeMessage, RuntimeRequest, RuntimeResponse, RuntimeServerToolsPolicy, RuntimeStreamEvent, decodeProviderMetadata } from '@x12i/openrouter-runtime';
 import { ReasoningEffort, ReasoningOutcome } from '@x12i/ai-profiles';
 export { ReasoningEffort, ReasoningOutcome } from '@x12i/ai-profiles';
 import { CompiledBedrockRequest, BedrockRuntimeOptions } from '@x12i/bedrock-runtime';
 export { BedrockClientLike, BedrockCredentials, BedrockRuntimeOptions, CompiledBedrockRequest } from '@x12i/bedrock-runtime';
 
-type AiProviderId = "openrouter" | "openai" | "anthropic" | "google" | "azure" | "bedrock" | "groq" | "mistral" | "cohere" | "together" | "fireworks" | "xai" | "deepseek" | "custom";
-declare const IMPLEMENTED_AI_PROVIDERS: readonly ["openrouter", "bedrock", "openai"];
+type AiProviderId = "openrouter" | "openai" | "anthropic" | "google" | "azure" | "bedrock" | "groq" | "mistral" | "cohere" | "together" | "fireworks" | "xai" | "deepseek" | "cloudflare" | "custom";
+declare const IMPLEMENTED_AI_PROVIDERS: readonly ["openrouter", "bedrock", "openai", "cloudflare"];
 type ImplementedAiProvider = (typeof IMPLEMENTED_AI_PROVIDERS)[number];
 declare function isImplementedAiProvider(provider: string): provider is ImplementedAiProvider;
 
+/** Concrete Cloudflare AI REST endpoint. */
+type CloudflareEndpoint = "chat" | "responses" | "messages" | "run";
+/** `auto` picks chat, responses, or messages from the model id. */
+type CloudflareEndpointChoice = CloudflareEndpoint | "auto";
+type CloudflareBackoff = "constant" | "linear" | "exponential";
+type CloudflareWebhookFormat = "raw" | "chat";
+/** Per-request AI Gateway headers (`cf-aig-*`). */
+interface CloudflareGatewayControls {
+    skipCache?: boolean;
+    /** Seconds. Sent as `cf-aig-cache-ttl`. */
+    cacheTtlSeconds?: number;
+    cacheKey?: string;
+    collectLog?: boolean;
+    requestTimeoutMs?: number;
+    /** Sent as `cf-aig-max-attempts`. Cloudflare caps this at 5. */
+    maxGatewayAttempts?: number;
+    /** Sent as `cf-aig-retry-delay`. Cloudflare caps this at 60000. */
+    retryDelayMs?: number;
+    backoff?: CloudflareBackoff;
+    /** Merged into `cf-aig-metadata`. Request metadata wins on the same key. */
+    metadata?: Record<string, unknown>;
+}
+/** `/ai/run` background execution. `webhookUrl` requires `background: true`. */
+interface CloudflareRunOptions {
+    background?: boolean;
+    webhookUrl?: string;
+    webhookFormat?: CloudflareWebhookFormat;
+}
+/** Per-request overrides. Credentials stay on dispatcher options. */
+interface CloudflareRequestOptions extends CloudflareGatewayControls {
+    endpoint?: CloudflareEndpointChoice;
+    /** Workers AI (`@cf/`) defaults to `"default"` when this is omitted. */
+    gatewayId?: string;
+    run?: CloudflareRunOptions;
+}
+interface CloudflareRuntimeOptions extends CloudflareRequestOptions {
+    /** Or `CLOUDFLARE_API_TOKEN`. Needs Account > Workers AI > Read. */
+    apiToken?: string;
+    /** Or `CLOUDFLARE_ACCOUNT_ID`. */
+    accountId?: string;
+    /** Defaults to `https://api.cloudflare.com/client/v4`. */
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+    /** HTTP attempts for 429, 408, and 5xx. Defaults to 2. */
+    maxAttempts?: number;
+    fetch?: typeof globalThis.fetch;
+    /** Executors for function tools that do not carry their own `executor`. */
+    tools?: Record<string, RuntimeToolExecutor>;
+    logger?: RuntimeLogger;
+}
+/**
+ * Resolved call settings passed from preparation into the adapter.
+ * Request fields win over dispatcher options. `cache` comes from the dispatcher cache policy.
+ */
+interface CloudflareCallContext {
+    endpoint?: CloudflareEndpoint;
+    gatewayId?: string;
+    run?: CloudflareRunOptions;
+    gateway?: CloudflareGatewayControls;
+    cache?: {
+        skip: boolean;
+        ttlSeconds?: number;
+        key?: string;
+    };
+}
+
 interface OpenAiRuntimeOptions {
     apiKey?: string;
     /** Defaults to `https://api.openai.com/v1`. Requests are sent to `{baseUrl}/responses`. */
@@ -39,8 +106,52 @@ interface ReasoningResolution {
     outcome?: ReasoningOutcome;
     bypassed: boolean;
 }
+/** How a call asks for prompt caching. Omitted `mode` means `explicit`. */
+type CacheMode = "auto" | "explicit" | "disabled";
+/** Normalized cache lifetime. Providers fold this to a supported value. */
+type CacheTtl = "5m" | "30m" | "1h";
+/**
+ * `applied` — the requested caching was written.
+ * `degraded` — a nearby TTL was written and the call still runs.
+ * `ignored` — no cache marker was written and the call still runs.
+ */
+type CacheOutcome = "applied" | "degraded" | "ignored";
+/**
+ * Provider-neutral prompt-cache intent.
+ * One explicit breakpoint is placed at the end of the stable prefix
+ * (`system` or `instructions`) when the model supports it.
+ */
+interface CachePolicy {
+    mode?: CacheMode;
+    /** Stable id for caches that route on a key. Omitted from the wire when the dialect has no key field. */
+    key?: string;
+    ttl?: CacheTtl;
+}
+/** What the dispatcher did with `cache` for one call. */
+interface CacheResolution {
+    mode: CacheMode;
+    target: ImplementedAiProvider;
+    requestedModel: string;
+    effectiveModel: string;
+    outcome: CacheOutcome;
+    /** TTL written on the wire. Omitted when no TTL was sent. */
+    ttl?: CacheTtl;
+    keyPresent: boolean;
+}
 interface AiDispatcherRequest extends RuntimeRequest {
     provider?: AiProviderId;
+    /**
+     * Caller organization id. Stored in the one provider metadata record as `orgId`.
+     */
+    orgId?: string;
+    /**
+     * Caller step id. Stored in the one provider metadata record as `stepId`.
+     */
+    stepId?: string;
+    /**
+     * Caller skill id. Stored in the one provider metadata record as `skillId`.
+     */
+    skillId?: string;
     /**
      * Provider-neutral reasoning intent. The bundled catalog chooses the wire action.
      * An explicit provider control on the same request wins and the catalog is not called.
@@ -59,6 +170,17 @@ interface AiDispatcherRequest extends RuntimeRequest {
      * A string list attaches only those exposed names.
      */
     mcp?: false | string[];
+    /**
+     * Optional prompt-cache intent. Omit it and the compiled body is unchanged.
+     * `explicit` marks the end of `system` or `instructions` when the model supports it.
+     * On Cloudflare this also sets AI Gateway cache headers.
+     */
+    cache?: CachePolicy;
+    /**
+     * Cloudflare AI REST overrides for this call.
+     * `endpoint` wins over `apiMode`. Stripped before the provider request is compiled.
+     */
+    cloudflare?: CloudflareRequestOptions;
 }
 interface DispatcherMcpTool {
     name: string;
@@ -82,13 +204,15 @@ interface DispatcherMcpOptions {
 interface AiDispatcherOptions {
     /**
      * Default provider for run / stream / compile.
-     * Implemented: `"openrouter"` | `"bedrock"` | `"openai"`.
+     * Implemented: `"openrouter"` | `"bedrock"` | `"openai"` | `"cloudflare"`.
      */
     provider?: AiProviderId;
     openrouter?: OpenRouterRuntimeOptions;
     bedrock?: BedrockRuntimeOptions;
     /** Direct OpenAI Responses API. */
     openai?: OpenAiRuntimeOptions;
+    /** Cloudflare AI REST API: Workers AI and third-party models. */
+    cloudflare?: CloudflareRuntimeOptions;
     /** Connected MCP servers. The dispatcher does not open transports. */
     mcp?: DispatcherMcpOptions;
     logger?: RuntimeLogger;
@@ -102,27 +226,53 @@ interface CompiledOpenAiRequest {
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
+}
+interface CompiledCloudflareRequest {
+    provider: "cloudflare";
+    /** REST dialect selected for this call. */
+    endpoint: "chat" | "responses" | "messages" | "run";
+    url: string;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+    warnings: _x12i_openrouter_runtime.RuntimeWarning[];
+    requestedModel: string;
+    effectiveModel: string;
+    reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
 }
 type CompiledAiRequest = (CompiledOpenRouterRequest & {
     provider: "openrouter";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
 }) | (CompiledBedrockRequest & {
     provider: "bedrock";
     requestedModel: string;
     effectiveModel: string;
     reasoningResolution?: ReasoningResolution;
-}) | CompiledOpenAiRequest;
+    cacheResolution?: CacheResolution;
+}) | CompiledOpenAiRequest | CompiledCloudflareRequest;
+interface AiDispatcherUsage extends RuntimeUsage {
+    /** Tokens read from a prompt cache. Omitted when the provider did not report any. */
+    cachedTokens?: number;
+    /** Tokens written to a prompt cache. Omitted when the provider did not report any. */
+    cacheWriteTokens?: number;
+}
 interface AiDispatcherResponse extends RuntimeResponse {
     /** Provider-exposed reasoning text. Omitted when the provider did not return any. */
     reasoningText?: string;
     reasoningResolution?: ReasoningResolution;
+    cacheResolution?: CacheResolution;
+    usage?: AiDispatcherUsage;
 }
 interface ProviderCallOptions {
     finalizeBody?: (body: Record<string, unknown>) => Record<string, unknown>;
     extractStreamReasoning?: (event: unknown) => string | undefined;
     suppressNestedReasoningFallback?: boolean;
+    /** Set by preparation for the Cloudflare adapter. Callers do not set this. */
+    cloudflare?: CloudflareCallContext;
 }
 interface AiProviderAdapter {
     run(request: RuntimeRequest, call?: ProviderCallOptions): Promise<RuntimeResponse>;
@@ -161,4 +311,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 AiProviderAdapter, type AiProviderId, type CompiledAiRequest, type CompiledOpenAiRequest, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };
+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, type DispatcherMcpOptions, type DispatcherMcpServer, type DispatcherMcpTool, IMPLEMENTED_AI_PROVIDERS, type ImplementedAiProvider, type OpenAiRuntimeOptions, type ReasoningResolution, createAiDispatcher, isImplementedAiProvider, providerNotImplemented, resolveProvider, stripReasoningHistoryFields };