@zuplo/cli 6.71.21 → 6.71.22

package/node_modules/@zuplo/runtime/out/types/index.d.ts

@@ -6,6 +6,22 @@ import { RequestGeneric as RequestGeneric_2 } from "../../request.js";
 import type { ValidateFunction } from "ajv";
 import { z } from "zod/v4";
 
+/**
+ * The request/response **schema dialect** a policy is dealing with — named after
+ * the schema, not the provider or the URL path. `openai-chat` is the OpenAI Chat
+ * Completions schema regardless of the downstream provider (Zuplo translates
+ * chat↔provider underneath); `openai-responses` and `anthropic-messages` are
+ * pass-through schemas whose native shape reaches the provider unchanged.
+ *
+ * Determined by the route, never sniffed from the body. New dialects
+ * (`openai-embeddings`, `openai-images`, …) extend this union.
+ * @public
+ */
+export declare type AiFormat =
+  | "openai-chat"
+  | "openai-responses"
+  | "anthropic-messages";
+
 /**
  * Converts Anthropic Messages API format requests to OpenAI Chat Completions format.
  * This policy translates between the two formats to allow seamless routing to different providers.
@@ -333,6 +349,47 @@ export declare function AIGatewaySemanticCacheOutboundPolicy(
  */
 export declare interface AIGatewaySemanticCacheOutboundPolicyOptions {}
 
+/**
+ * AI Gateway Semantic Cache policy (AI Gateway v2). A single inbound policy that
+ * looks up the semantic cache on entry and, on a miss, registers a
+ * response-sending hook to write the upstream response back into the cache —
+ * matching the firewall's single-policy shape (no separate outbound policy).
+ *
+ * Caching parameters (semanticTolerance, expirationSecondsTtl, namespace) come
+ * from the policy options — the policy reads nothing from
+ * `request.user.configuration` to decide whether to cache, and presence in the
+ * route's chain is what enables it. `namespace` defaults to the AI Gateway
+ * configuration id when omitted so caching stays scoped per tenant.
+ *
+ * @title AI Gateway Semantic Cache (v2)
+ * @product ai-gateway
+ * @hidden
+ * @requiresAI
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Request or a Response
+ */
+export declare function AIGatewaySemanticCacheV2InboundPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: AIGatewaySemanticCacheV2InboundPolicyOptions,
+  policyName: string
+): Promise<Response | ZuploRequest<RequestGeneric_2>>;
+
+/**
+ * Options for the AI Gateway Semantic Cache (v2) policy. Configured inline in policies.json; the policy reads nothing from the AI Gateway configuration to decide whether to cache.
+ * @public
+ */
+export declare interface AIGatewaySemanticCacheV2InboundPolicyOptions {
+  semanticTolerance?: SemanticTolerance;
+  expirationSecondsTtl?: CacheTTLSeconds;
+  namespace?: CacheNamespace;
+  endpoints?: ApplicableEndpoints;
+  onUnknownShape?: OnUnknownShape;
+}
+
 /**
  * The options for this policy.
  * @public
@@ -381,6 +438,96 @@ export declare function AIGatewayUsageTrackerPolicy(
   _policyName: string
 ): Promise<Response>;
 
+/**
+ * Common options every AI Gateway policy understands for scoping itself across
+ * the multi-endpoint surface. A policy reads these from its own `options`.
+ * @public
+ */
+export declare interface AiPolicyScopeOptions {
+  /**
+   * The endpoint shapes this policy applies to. When set, the policy is inert on
+   * any other shape. Omit to apply to all shapes.
+   */
+  endpoints?: AiFormat[];
+  /**
+   * What to do when the policy meets a shape it cannot read. `skip` (the default
+   * for observers) passes through; guardrails MUST use `deny` so uninspectable
+   * content is never served.
+   */
+  onUnknownShape?: "deny" | "skip";
+}
+
+/**
+ * The request body for an AI Gateway endpoint, discriminated by {@link AiFormat}.
+ * A policy reads `getFormat(request)` and then narrows to the matching member —
+ * no field is normalized away, so tool calls, content blocks, images, and
+ * thinking are all preserved.
+ * @public
+ */
+export declare type AiRequestBody =
+  | {
+      format: "openai-chat";
+      body: ChatCompletionRequest;
+    }
+  | {
+      format: "openai-responses";
+      body: ResponsesRequest;
+    }
+  | {
+      format: "anthropic-messages";
+      body: AnthropicMessagesRequest;
+    };
+
+/**
+ * The response body for an AI Gateway endpoint, discriminated by {@link AiFormat}.
+ * For the Anthropic Messages pass-through the native response is returned as an
+ * opaque record (the runtime has no dedicated Anthropic response interface).
+ * @public
+ */
+export declare type AiResponseBody =
+  | {
+      format: "openai-chat";
+      body: ChatCompletionResponse;
+    }
+  | {
+      format: "openai-responses";
+      body: ResponsesResponse;
+    }
+  | {
+      format: "anthropic-messages";
+      body: Record<string, unknown>;
+    };
+
+/**
+ * A decoded streaming event, normalized just enough for an observer or guardrail
+ * to act without re-implementing per-dialect SSE parsing. `textDelta` is the
+ * incremental text in this event (if any); `usage` appears on the terminal
+ * event(s); `done` marks the end of the stream.
+ * @public
+ */
+export declare interface AiStreamEvent {
+  /** The raw SSE `data:` payload, parsed from JSON when possible. */
+  raw: unknown;
+  /** Incremental assistant text carried by this event, if any. */
+  textDelta?: string;
+  /** Usage totals, present on the terminal event(s) for the shape. */
+  usage?: AiUsage;
+  /** True for the stream-terminating event (`[DONE]` or shape equivalent). */
+  done?: boolean;
+}
+
+/**
+ * A normalized usage record. Consolidates the per-shape token field names
+ * (`prompt_tokens`/`completion_tokens` for chat, `input_tokens`/`output_tokens`
+ * for responses and Anthropic) into one set.
+ * @public
+ */
+export declare interface AiUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
 /**
  * Akamai AI Firewall Inbound Policy
  * @title Akamai AI Firewall
@@ -418,6 +565,48 @@ export declare interface AkamaiAIFirewallPolicyOptions {
   streamingAccumulation?: StreamingAccumulationSettings;
 }
 
+/**
+ * Akamai AI Firewall Inbound Policy (AI Gateway v2)
+ * @title Akamai AI Firewall (v2)
+ * @product ai-gateway
+ * @hidden
+ * @requiresAI
+ *
+ * Detects and blocks malicious AI inputs and outputs via Akamai's AI Firewall
+ * service. Settings come from the policy options (configurationId, api-key,
+ * applicationId, streamingAccumulation) — the policy reads nothing from
+ * `request.user.configuration`, and presence in the route's `inbound[]` chain is
+ * what enables it.
+ *
+ * For streaming responses it uses a transform stream that can block content
+ * mid-stream if harmful content is detected.
+ *
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Request or a Response
+ */
+export declare function AkamaiAIFirewallV2InboundPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: AkamaiAIFirewallV2PolicyOptions,
+  _policyName: string
+): Promise<ZuploRequest | Response>;
+
+/**
+ * The options for the Akamai AI Firewall policy.
+ * @public
+ */
+export declare interface AkamaiAIFirewallV2PolicyOptions {
+  configurationId: ConfigurationID_2;
+  "api-key": APIKey_2;
+  applicationId?: ApplicationID_2;
+  streamingAccumulation?: StreamingAccumulationSettings_2;
+  endpoints?: ApplicableEndpoints_2;
+  onUnknownShape?: OnUnknownShape_2;
+}
+
 /**
  * Entry format for Akamai API Security logger
  * @public
@@ -697,6 +886,30 @@ declare interface AmberfloMeteringProperties extends Omit<
   customerId: string;
 }
 
+declare interface AnthropicMessage {
+  role: "user" | "assistant";
+  content:
+    | string
+    | Array<{
+        type: "text" | "image";
+        text?: string;
+        source?: unknown;
+      }>;
+}
+
+declare interface AnthropicMessagesRequest {
+  model: string;
+  messages: AnthropicMessage[];
+  max_tokens: number;
+  system?: string;
+  temperature?: number;
+  top_p?: number;
+  stop_sequences?: string[];
+  stream?: boolean;
+  metadata?: Record<string, unknown>;
+  tools?: unknown[];
+}
+
 /**
  * Authenticates requests based on API Keys using Zuplo API Management.
  *
@@ -733,6 +946,12 @@ export declare interface ApiAuthKeyInboundPolicyOptions {
  */
 declare type APIKey = string;
 
+/**
+ * The API key for the AI Firewall.
+ * @public
+ */
+declare type APIKey_2 = string;
+
 /**
  * Represents a consumer in the API Key service.
  * @public
@@ -976,12 +1195,58 @@ declare interface APITokenCredentialConfig {
   headerValuePrefix?: string;
 }
 
+/**
+ * The endpoint shapes to cache. Defaults to ['openai-chat'] — the cache keys off chat `messages` and skips other shapes.
+ * @public
+ */
+declare type ApplicableEndpoints = (
+  | "openai-chat"
+  | "openai-responses"
+  | "anthropic-messages"
+)[];
+
+/**
+ * The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).
+ * @public
+ */
+declare type ApplicableEndpoints_2 = (
+  | "openai-chat"
+  | "openai-responses"
+  | "anthropic-messages"
+)[];
+
+/**
+ * The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).
+ * @public
+ */
+declare type ApplicableEndpoints_3 = (
+  | "openai-chat"
+  | "openai-responses"
+  | "anthropic-messages"
+)[];
+
+/**
+ * The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).
+ * @public
+ */
+declare type ApplicableEndpoints_4 = (
+  | "openai-chat"
+  | "openai-responses"
+  | "anthropic-messages"
+)[];
+
 /**
  * The application ID to identify this usage of the AI Firewall (optional).
  * @public
  */
 declare type ApplicationID = string;
 
+/**
+ * The application ID to identify this usage of the AI Firewall (optional).
+ * @public
+ */
+declare type ApplicationID_2 = string;
+
 /**
  * A list of attributes that will be included in the authorization request.
  * @public
@@ -1948,6 +2213,12 @@ declare interface BuildRouteConfiguration {
   /* Excluded from this release type: raw */
 }
 
+/**
+ * Partitions the cache. Omit to default to the AI Gateway configuration id, which keeps caching scoped per tenant.
+ * @public
+ */
+declare type CacheNamespace = string;
+
 /**
  * Internal
  */
@@ -1955,6 +2226,12 @@ declare interface CacheOptions {
   logger?: Logger;
 }
 
+/**
+ * How long a cached response lives, in seconds. Defaults to 3600 (1 hour).
+ * @public
+ */
+declare type CacheTTLSeconds = number;
+
 /**
  * Respond to matched incoming requests with cached content
  *
@@ -2099,12 +2376,112 @@ export declare interface ChangeMethodInboundPolicyOptions {
   method: string;
 }
 
+declare interface ChatCompletionChoice {
+  index: number;
+  message: ChatCompletionMessage;
+  logprobs?: {
+    content: Array<{
+      token: string;
+      logprob: number;
+      bytes?: number[];
+      top_logprobs?: Array<{
+        token: string;
+        logprob: number;
+        bytes?: number[];
+      }>;
+    }> | null;
+  } | null;
+  finish_reason:
+    | "stop"
+    | "length"
+    | "function_call"
+    | "tool_calls"
+    | "content_filter";
+}
+
+declare interface ChatCompletionMessage {
+  role: "system" | "user" | "assistant" | "function" | "tool";
+  content: string;
+  name?: string;
+  function_call?: {
+    name: string;
+    arguments: string;
+  };
+  tool_calls?: Array<{
+    id: string;
+    type: "function";
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+  tool_call_id?: string;
+}
+
+declare interface ChatCompletionRequest {
+  model: string;
+  messages: ChatCompletionMessage[];
+  temperature?: number;
+  top_p?: number;
+  n?: number;
+  stream?: boolean;
+  stop?: string | string[];
+  max_tokens?: number;
+  presence_penalty?: number;
+  frequency_penalty?: number;
+  user?: string;
+  seed?: number;
+  functions?: FunctionDefinition[];
+  function_call?:
+    | string
+    | {
+        name: string;
+      };
+  tools?: ToolDefinition[];
+  tool_choice?: string | ToolChoice;
+  parallel_tool_calls?: boolean;
+  response_format?: {
+    type: "text" | "json_object" | "json_schema";
+    json_schema?: {
+      name: string;
+      strict?: boolean;
+      schema: Record<string, unknown>;
+    };
+  };
+  logit_bias?: Record<string, number>;
+  logprobs?: boolean;
+  top_logprobs?: number;
+  max_completion_tokens?: number;
+  service_tier?: "auto" | "default";
+  stream_options?: {
+    include_usage?: boolean;
+  };
+}
+
+declare interface ChatCompletionResponse {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  system_fingerprint?: string;
+  choices: ChatCompletionChoice[];
+  usage: Usage;
+  service_tier?: string;
+  provider?: string;
+}
+
 /**
  * Time interval in milliseconds for periodic checks (alternative to chunk count).
  * @public
  */
 declare type CheckIntervalMs = number;
 
+/**
+ * Time interval in milliseconds for periodic checks (alternative to chunk count).
+ * @public
+ */
+declare type CheckIntervalMs_2 = number;
+
 /**
  * Removes all headers from the incoming request except for those in the exclude list.
  *
@@ -2215,6 +2592,19 @@ declare interface ClientCredentialsConfig {
   apiAudience?: string;
 }
 
+/**
+ * Code interpreter tool
+ */
+declare interface CodeInterpreterTool {
+  type: "code_interpreter";
+  container:
+    | string
+    | {
+        type: "auto";
+        file_ids?: string[];
+      };
+}
+
 /**
  * Authenticate requests with JWT tokens issued by AWS Cognito.
  *
@@ -2301,6 +2691,61 @@ export declare interface CometOpikTracingPolicyOptions {
   baseUrl?: string;
 }
 
+/**
+ * Comet Opik Tracing Inbound Policy (AI Gateway v2)
+ * @title Comet Opik Tracing (v2)
+ * @product ai-gateway
+ * @hidden
+ * @requiresAI
+ *
+ * Traces both streaming and non-streaming AI Gateway responses to Comet Opik,
+ * creating traces when requests start and spans when responses complete.
+ * Credentials (apiKey, projectName, workspace, baseUrl) come from the policy
+ * options — the policy reads nothing from `request.user.configuration` to decide
+ * whether to run, and presence in the route's chain is what enables it.
+ *
+ * For streaming responses, it clones the response stream and processes it in
+ * the background using `waitUntil`, allowing the original stream to pass through
+ * unmodified while still capturing the complete content for tracing.
+ *
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Request or a Response
+ */
+export declare function CometOpikTracingV2InboundPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: CometOpikTracingV2PolicyOptions,
+  _policyName: string
+): Promise<ZuploRequest | Response>;
+
+/**
+ * Track AI Gateway requests and responses using Comet Opik's LLM observability platform.
+ * @public
+ */
+export declare interface CometOpikTracingV2PolicyOptions {
+  /**
+   * The Comet Opik API key for authentication.
+   */
+  apiKey: string;
+  /**
+   * The Comet Opik project name for organizing traces.
+   */
+  projectName: string;
+  /**
+   * The Comet Opik workspace name.
+   */
+  workspace: string;
+  /**
+   * The base URL for the Comet Opik API (optional, defaults to https://www.comet.com/opik/api).
+   */
+  baseUrl?: string;
+  endpoints?: ApplicableEndpoints_3;
+  onUnknownShape?: OnUnknownShape_3;
+}
+
 /**
  * The compatibility date on which to run the gateway
  */
@@ -2519,6 +2964,16 @@ export declare interface CompositeOutboundPolicyOptions {
   policies?: string[];
 }
 
+/**
+ * Computer use tool (preview)
+ */
+declare interface ComputerUseTool {
+  type: "computer_use_preview";
+  display_height: number;
+  display_width: number;
+  environment: "windows" | "mac" | "linux" | "ubuntu" | "browser";
+}
+
 /**
  * Errors caused by invalid user configuration such as invalid parameters on policies,
  * handlers that are not functions, or missing required configuration values.
@@ -2556,6 +3011,12 @@ export declare class ConfigurationError extends RuntimeError {
  */
 declare type ConfigurationID = string;
 
+/**
+ * The configuration ID of the AI Firewall.
+ * @public
+ */
+declare type ConfigurationID_2 = string;
+
 /* Excluded from this release type: ContentTypes */
 
 /**
@@ -2848,6 +3309,16 @@ declare interface CustomRateLimitDetailsBase {
 export declare type CustomRateLimitFunction =
   RateLimitFunction<CustomRateLimitDetails>;
 
+/**
+ * Custom tool
+ */
+declare interface CustomTool {
+  name: string;
+  type: "custom";
+  description?: string;
+  format?: Record<string, unknown>;
+}
+
 declare interface DataDogLoggingOptions {
   url?: string;
   apiKey: string;
@@ -3295,6 +3766,12 @@ export declare class DynatraceMetricsPlugin extends MetricsPlugin {
  */
 declare type EnableStreamingAccumulation = boolean;
 
+/**
+ * Enable accumulation and validation of streaming responses.
+ * @public
+ */
+declare type EnableStreamingAccumulation_2 = boolean;
+
 /**
  * @beta
  * Object exposing environment variables
@@ -3318,6 +3795,12 @@ export declare interface ErrorHandler {
  */
 declare type EventsInterval = number;
 
+/**
+ * Number of SSE events to accumulate before checking with Akamai (default: 5).
+ * @public
+ */
+declare type EventsInterval_2 = number;
+
 declare const EventType: {
   readonly AI_GATEWAY_COST_SUM: "ai_gateway_cost_sum";
   readonly AI_GATEWAY_REQUEST_COUNT: "ai_gateway_request_count";
@@ -3357,6 +3840,16 @@ declare const EventType: {
 
 declare type EventType = (typeof EventType)[keyof typeof EventType];
 
+/**
+ * Best-effort flatten of ALL human/assistant text in a request OR response body,
+ * across every shape — the one sanctioned cross-shape helper. Intended for
+ * guardrails that just need "all the text to scan/moderate"; it is deliberately
+ * lossy (drops roles, structure, tool calls). Everything else should read the
+ * typed body via {@link getRequestBody} / {@link getResponseBody}.
+ * @public
+ */
+export declare function extractAllText(body: unknown): string;
+
 /**
  * Parse a response body and extract its GraphQL `errors[]`, including
  * across an Apollo-style batched (array) response.
@@ -3376,6 +3869,20 @@ declare interface FetchOptions<T> {
   headers?: Record<string, string>;
 }
 
+/**
+ * File search tool
+ */
+declare interface FileSearchTool {
+  type: "file_search";
+  vector_store_ids: string[];
+  filters?: Record<string, unknown> | null;
+  max_num_results?: number;
+  ranking_options?: {
+    ranker?: "auto" | "default-2024-11-15";
+    score_threshold?: number;
+  };
+}
+
 /**
  * Authenticate users using Firebase issued JWT tokens.
  *
@@ -3409,6 +3916,17 @@ export declare interface FirebaseJwtInboundPolicyOptions {
   oAuthResourceMetadataEnabled?: boolean;
 }
 
+/**
+ * Flatten a single message's `content` field to plain text. Content may be a
+ * string (OpenAI chat / simple Anthropic) or an array of content blocks
+ * (Anthropic Messages, OpenAI multi-modal vision, Responses input items). Use
+ * this anywhere a policy needs the text of one message without assuming the
+ * content is a string — a bare `${msg.content}` stringifies array content to
+ * `[object Object]`.
+ * @public
+ */
+export declare function flattenMessageContent(content: unknown): string;
+
 /**
  * Converts form data in the incoming request to JSON.
  *
@@ -3438,6 +3956,23 @@ export declare interface FormDataToJsonInboundPolicyOptions {
   optionalHoneypotName?: string;
 }
 
+declare interface FunctionDefinition {
+  name: string;
+  description?: string;
+  parameters: Record<string, unknown>;
+}
+
+/**
+ * Function tool for Responses API
+ */
+declare interface FunctionTool {
+  name: string;
+  type: "function";
+  parameters: Record<string, unknown> | null;
+  strict: boolean | null;
+  description?: string | null;
+}
+
 /**
  * Galileo Tracing Inbound Policy
  * @title Galileo Tracing
@@ -3487,6 +4022,62 @@ export declare interface GalileoTracingPolicyOptions {
   baseUrl?: string;
 }
 
+/**
+ * Galileo Tracing Inbound Policy (AI Gateway v2)
+ * @title Galileo Tracing (v2)
+ * @product ai-gateway
+ * @hidden
+ * @requiresAI
+ *
+ * Traces both streaming and non-streaming AI Gateway responses to Galileo's LLM
+ * observability platform, creating complete traces with workflow and LLM spans
+ * when responses complete. Credentials (apiKey, projectId, logStreamId, baseUrl)
+ * come from the policy options — the policy reads nothing from
+ * `request.user.configuration` to decide whether to run, and presence in the
+ * route's chain is what enables it.
+ *
+ * For streaming responses, it clones the response stream and processes it in
+ * the background using `waitUntil`, allowing the original stream to pass through
+ * unmodified while still capturing the complete content for tracing.
+ *
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Request or a Response
+ */
+export declare function GalileoTracingV2InboundPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: GalileoTracingV2PolicyOptions,
+  _policyName: string
+): Promise<ZuploRequest | Response>;
+
+/**
+ * Track AI Gateway requests and responses using Galileo's LLM observability platform.
+ * @public
+ */
+export declare interface GalileoTracingV2PolicyOptions {
+  /**
+   * The Galileo API key for authentication.
+   */
+  apiKey: string;
+  /**
+   * The Galileo project ID (UUID) for organizing traces.
+   */
+  projectId: string;
+  /**
+   * The Galileo log stream ID (UUID) for organizing traces.
+   */
+  logStreamId: string;
+  /**
+   * The base URL for the Galileo API (optional, defaults to https://api.galileo.ai).
+   */
+  baseUrl?: string;
+  endpoints?: ApplicableEndpoints_4;
+  onUnknownShape?: OnUnknownShape_4;
+}
+
 /**
  * Function to generate request logger entries
  * @public
@@ -3542,6 +4133,18 @@ declare interface GeoSpec {
   asns?: string;
 }
 
+/**
+ * Resolve the AI shape for a request from its endpoint. Mirrors the handler's
+ * base-path resolution so routes mounted under a prefix
+ * (`/{prefix}/v1/chat/completions`) classify the same as the bare path. Returns
+ * `null` for an endpoint that carries no AI body shape (e.g. `/v1/embeddings`).
+ *
+ * The shape is NEVER sniffed from the body — sniffing `!!body.input` misclassifies
+ * an Anthropic body as chat.
+ * @public
+ */
+export declare function getFormat(request: ZuploRequest): AiFormat | null;
+
 /* Excluded from this release type: getIdForParameterSchema */
 
 /* Excluded from this release type: getIdForRefSchema */
@@ -3576,6 +4179,49 @@ declare interface GetQuotaResult {
 
 /* Excluded from this release type: getRawOperationDataIdentifierName */
 
+/**
+ * Read the request body, typed and discriminated by endpoint shape. Returns
+ * `null` for a non-AI endpoint. The body is the native shape — no field is
+ * flattened away.
+ * @public
+ */
+export declare function getRequestBody(
+  request: ZuploRequest
+): Promise<AiRequestBody | null>;
+
+/**
+ * Read the response body, typed and discriminated by endpoint shape. Returns
+ * `null` for a non-AI endpoint or an unparseable body.
+ * @public
+ */
+export declare function getResponseBody(
+  request: ZuploRequest,
+  response: Response
+): Promise<AiResponseBody | null>;
+
+/**
+ * Decode a streamed AI response into normalized {@link AiStreamEvent}s, hiding
+ * the per-shape SSE dialect. A `post_call`-style streaming hook reads
+ * `textDelta` / `usage` / `done` without re-writing SSE parsing per endpoint.
+ * Reads a `clone()` of the response, so the original stream is untouched (the
+ * caller can still return/pipe `response` as-is) — the same observe-via-clone
+ * pattern the tracing policies use.
+ * @public
+ */
+export declare function getStreamEvents(
+  request: ZuploRequest,
+  response: Response
+): AsyncIterable<AiStreamEvent>;
+
+/**
+ * Normalize the usage record from a (non-streaming) response body, regardless of
+ * shape. Chat reports `prompt_tokens`/`completion_tokens`; responses and
+ * Anthropic report `input_tokens`/`output_tokens`. Returns `undefined` when no
+ * usage is present.
+ * @public
+ */
+export declare function getUsage(body: unknown): AiUsage | undefined;
+
 declare interface GoogleCloudLoggingOptions {
   serviceAccountJson: string;
   logName: string;
@@ -5318,6 +5964,26 @@ export declare interface HydrolixRequestLoggerPluginOptions<T> {
   batchPeriodSeconds?: number;
 }
 
+/**
+ * Image generation tool
+ */
+declare interface ImageGenerationTool {
+  type: "image_generation";
+  model?: "gpt-image-1" | "gpt-image-1-mini";
+  background?: "transparent" | "opaque" | "auto";
+  input_fidelity?: "high" | "low" | null;
+  input_image_mask?: {
+    file_id?: string;
+    image_url?: string;
+  };
+  moderation?: "auto" | "low";
+  output_compression?: number;
+  output_format?: "png" | "webp" | "jpeg";
+  partial_images?: number;
+  quality?: "low" | "medium" | "high" | "auto";
+  size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto";
+}
+
 /**
  * A policy that can modify the incoming HTTP request before it is sent to
  * the handler. If a response is returned, the request is short-circuited and
@@ -5942,6 +6608,13 @@ export declare const legacyDevPortalHandler: (
   context: ZuploContext
 ) => Response | Promise<Response>;
 
+/**
+ * Local shell tool
+ */
+declare interface LocalShellTool {
+  type: "local_shell";
+}
+
 /**
  * @beta
  */
@@ -7256,6 +7929,29 @@ export declare function mcpServerHandler(
   context: ZuploContext
 ): Promise<Response>;
 
+/**
+ * MCP (Model Context Protocol) tool
+ */
+declare interface McpTool {
+  server_label: string;
+  type: "mcp";
+  allowed_tools?: string[] | Record<string, unknown> | null;
+  authorization?: string;
+  connector_id?:
+    | "connector_dropbox"
+    | "connector_gmail"
+    | "connector_googlecalendar"
+    | "connector_googledrive"
+    | "connector_microsoftteams"
+    | "connector_outlookcalendar"
+    | "connector_outlookemail"
+    | "connector_sharepoint";
+  headers?: Record<string, string> | null;
+  require_approval?: Record<string, unknown> | "always" | "never" | null;
+  server_description?: string;
+  server_url?: string;
+}
+
 /**
  * Authenticate MCP gateway requests using a gateway-issued OAuth access token,
  * with browser login delegated to WorkOS.
@@ -8055,6 +8751,30 @@ declare interface OnSendingAwsLambdaEventHook {
   ): Promise<AwsLambdaEventV1 | AwsLambdaEventV2>;
 }
 
+/**
+ * Unused by the cache (a cache miss is never unsafe, so it always fails open). Present for interface consistency.
+ * @public
+ */
+declare type OnUnknownShape = "deny" | "skip";
+
+/**
+ * What to do when the request shape cannot be inspected. As a guardrail, this policy defaults to 'deny' (fail closed) so uninspectable content is never served.
+ * @public
+ */
+declare type OnUnknownShape_2 = "deny" | "skip";
+
+/**
+ * What to do on a shape the policy cannot read. As an observer this defaults to 'skip' (fail open — pass through untraced).
+ * @public
+ */
+declare type OnUnknownShape_3 = "deny" | "skip";
+
+/**
+ * What to do on a shape the policy cannot read. As an observer this defaults to 'skip' (fail open — pass through untraced).
+ * @public
+ */
+declare type OnUnknownShape_4 = "deny" | "skip";
+
 /**
  * Handler that serves OpenAPI specification files.
  * Use this to expose your API documentation in a standard format that can be
@@ -10187,6 +10907,43 @@ export declare function responseHasGraphqlErrors(
   maxScanBytes?: number
 ): Promise<boolean>;
 
+declare interface ResponseInputItem {
+  type?: "message";
+  role: "user" | "assistant" | "system" | "developer";
+  content:
+    | string
+    | Array<{
+        type: "text" | "image_url" | "audio";
+        text?: string;
+        image_url?: {
+          url: string;
+        };
+        audio?: {
+          data: string;
+          format: string;
+        };
+      }>;
+}
+
+declare interface ResponsesChoice {
+  index: number;
+  id?: string;
+  type?: "message";
+  role?: "assistant";
+  content?: Array<{
+    type: "output_text";
+    text: string;
+    annotations?: Array<unknown>;
+  }>;
+  status?: string | null;
+  finish_reason?:
+    | "stop"
+    | "length"
+    | "function_call"
+    | "tool_calls"
+    | "content_filter";
+}
+
 /**
  * Definition of responses for a route
  * @public
@@ -10223,6 +10980,115 @@ export declare class ResponseSentEvent extends Event {
   readonly response: Response;
 }
 
+declare interface ResponsesRequest {
+  input?: string | ResponseInputItem[];
+  model?: string;
+  instructions?: string;
+  previous_response_id?: string;
+  temperature?: number;
+  top_p?: number;
+  stream?: boolean;
+  max_output_tokens?: number;
+  tools?: ResponsesToolDefinition[];
+  tool_choice?: ResponsesToolChoice;
+  parallel_tool_calls?: boolean;
+  reasoning?: {
+    effort: "low" | "medium" | "high";
+  };
+  service_tier?: "auto" | "default" | "flex" | "scale" | "priority";
+  stream_options?: {
+    include_usage?: boolean;
+  };
+  background?: boolean;
+  conversation?: string;
+  include?: string[];
+  metadata?: Record<string, unknown>;
+  store?: boolean;
+  truncation?: "auto" | "disabled";
+  prompt_cache_key?: string;
+  safety_identifier?: string;
+}
+
+declare interface ResponsesResponse {
+  id: string;
+  object: "response";
+  created: number;
+  model: string;
+  status:
+    | "queued"
+    | "in_progress"
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "incomplete";
+  system_fingerprint?: string;
+  output?: ResponsesChoice[];
+  usage?: ResponsesUsage;
+  error?: {
+    type: string;
+    message: string;
+  };
+  service_tier?: string;
+  provider?: string;
+}
+
+declare type ResponsesToolChoice =
+  | "none"
+  | "auto"
+  | "required"
+  | {
+      mode: "auto" | "required";
+      tools: Array<Record<string, unknown>>;
+      type: "allowed_tools";
+    }
+  | {
+      name: string;
+      type: "custom";
+    }
+  | {
+      name: string;
+      type: "function";
+    }
+  | {
+      server_label: string;
+      type: "mcp";
+      name?: string | null;
+    }
+  | {
+      type:
+        | "file_search"
+        | "web_search_preview"
+        | "computer_use_preview"
+        | "web_search_preview_2025_03_11"
+        | "image_generation"
+        | "code_interpreter"
+        | "mcp";
+    };
+
+declare type ResponsesToolDefinition =
+  | FunctionTool
+  | WebSearchTool
+  | WebSearchPreviewTool
+  | CodeInterpreterTool
+  | FileSearchTool
+  | ComputerUseTool
+  | ImageGenerationTool
+  | LocalShellTool
+  | CustomTool
+  | McpTool;
+
+declare interface ResponsesUsage {
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+  input_tokens_details?: {
+    cached_tokens?: number;
+  };
+  output_tokens_details?: {
+    reasoning_tokens?: number;
+  };
+}
+
 /**
  * @public
  */
@@ -10500,6 +11366,12 @@ export declare type SemanticCacheInboundPolicyOptions = {
   cacheStatusHeaderName?: string;
 };
 
+/**
+ * Similarity threshold (0-1) for a cache hit. Higher values require closer semantic matches. Defaults to 0.8.
+ * @public
+ */
+declare type SemanticTolerance = number;
+
 /* Excluded from this release type: serialize */
 
 /**
@@ -10823,6 +11695,16 @@ declare interface StreamingAccumulationSettings {
   checkIntervalMs?: CheckIntervalMs;
 }
 
+/**
+ * Configuration for accumulating and validating streaming responses.
+ * @public
+ */
+declare interface StreamingAccumulationSettings_2 {
+  enabled?: EnableStreamingAccumulation_2;
+  eventsInterval?: EventsInterval_2;
+  checkIntervalMs?: CheckIntervalMs_2;
+}
+
 /**
  * A specialized zone cache for storing and retrieving ReadableStreams.
  * Unlike regular ZoneCache which serializes to JSON, this cache stores raw stream data,
@@ -11048,6 +11930,18 @@ export declare abstract class TelemetryPlugin extends RuntimePlugin {
   /* Excluded from this release type: instrument */
 }
 
+declare interface ToolChoice {
+  type: "function";
+  function: {
+    name: string;
+  };
+}
+
+declare interface ToolDefinition {
+  type: "function";
+  function: FunctionDefinition;
+}
+
 /* Excluded from this release type: trackFeature */
 
 /**
@@ -11622,6 +12516,22 @@ export declare function urlRewriteHandler(
   context: ZuploContext
 ): Promise<Response>;
 
+declare interface Usage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+    audio_tokens?: number;
+  };
+  completion_tokens_details?: {
+    reasoning_tokens?: number;
+    audio_tokens?: number;
+    accepted_prediction_tokens?: number;
+    rejected_prediction_tokens?: number;
+  };
+}
+
 declare type UserDataDefault = any;
 
 declare type ValidatedAuth0OAuthOptions = z.infer<
@@ -11788,6 +12698,38 @@ export declare interface WebBotAuthInboundPolicyOptions {
   directoryUrl?: string;
 }
 
+/**
+ * Web search tool (preview version)
+ */
+declare interface WebSearchPreviewTool {
+  type: "web_search_preview" | "web_search_preview_2025_03_11";
+  search_context_size?: "low" | "medium" | "high";
+  user_location?: {
+    type: "approximate";
+    city?: string | null;
+    country?: string | null;
+    region?: string | null;
+    timezone?: string | null;
+  } | null;
+}
+
+/**
+ * Web search tool (stable version)
+ */
+declare interface WebSearchTool {
+  type: "web_search" | "web_search_2025_08_26";
+  filters?: {
+    allowed_domains?: string[] | null;
+  } | null;
+  search_context_size?: "low" | "medium" | "high";
+  user_location?: {
+    city?: string | null;
+    country?: string | null;
+    region?: string | null;
+    timezone?: string | null;
+  } | null;
+}
+
 /**
  * Handler that proxies WebSocket connections to a different URL.
  * Enables WebSocket support in your API gateway for real-time communication.