feat: parses OpenAI Web Tool and GPT-5 responses (envoyproxy#1076)

**Description**

This parses OpenAI Web Tool requests and obfuscation used in gpt-5. As a
part of this, we re-record all the affected requests.

**Related Issues/PRs (if applicable)**

envoyproxy#1068

---------

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

internal/apischema/openai/openai.go

@@ -33,15 +33,18 @@ const (
 
 // Model names for testing.
 const (
-	// ModelGPT41Nano is the cheapest model usable with /chat/completions.
-	ModelGPT41Nano = "gpt-4.1-nano"
+	// ModelGPT5Nano is the cheapest model usable with /chat/completions.
+	ModelGPT5Nano = "gpt-5-nano"
 	// ModelO3Mini is the cheapest reasoning model usable with /chat/completions.
 	ModelO3Mini = "o3-mini"
 	// ModelGPT4oMiniAudioPreview is the cheapest audio synthesis model usable with /chat/completions.
 	ModelGPT4oMiniAudioPreview = "gpt-4o-mini-audio-preview"
-	// ModelGPT4oAudioPreview s the cheapest audio transcription model usable with /chat/completions.
+	// ModelGPT4oAudioPreview is the cheapest audio transcription model usable with /chat/completions.
 	// Note: gpt-4o-mini-transcribe is NOT a chat model, so cannot be used with /v1/chat/completions.
 	ModelGPT4oAudioPreview = "gpt-4o-audio-preview"
+	// ModelGPT4oMiniSearchPreview is the cheapest web search model usable with /chat/completions.
+	// Note: gpt-5 series supports web search, but only in the /responses API.
+	ModelGPT4oMiniSearchPreview = "gpt-4o-mini-search-preview"
 )
 
 // ChatCompletionContentPartRefusalType The type of the content part.
@@ -567,6 +570,44 @@ type PredictionContent struct {
 	Content StringOrArray `json:"content"`
 }
 
+// WebSearchContextSize represents the context size for web search.
+type WebSearchContextSize string
+
+const (
+	// WebSearchContextSizeLow provides minimal context from search results.
+	WebSearchContextSizeLow WebSearchContextSize = "low"
+	// WebSearchContextSizeMedium provides moderate context from search results.
+	WebSearchContextSizeMedium WebSearchContextSize = "medium"
+	// WebSearchContextSizeHigh provides maximum context from search results.
+	WebSearchContextSizeHigh WebSearchContextSize = "high"
+)
+
+// WebSearchOptions configures the web search tool behavior.
+type WebSearchOptions struct {
+	// UserLocation provides approximate location parameters for the search.
+	UserLocation *WebSearchUserLocation `json:"user_location,omitempty"` //nolint:tagliatelle //follow openai api
+	// SearchContextSize controls how much context to include from search results.
+	SearchContextSize WebSearchContextSize `json:"search_context_size,omitempty"` //nolint:tagliatelle //follow openai api
+}
+
+// WebSearchUserLocation represents approximate location for web search.
+type WebSearchUserLocation struct {
+	// Type is the type of location approximation. Always "approximate".
+	Type string `json:"type"`
+	// Approximate contains the approximate location details.
+	Approximate WebSearchLocation `json:"approximate"`
+}
+
+// WebSearchLocation contains location details for web search.
+type WebSearchLocation struct {
+	// City is the approximate city name.
+	City string `json:"city,omitempty"`
+	// Region is the approximate region or state.
+	Region string `json:"region,omitempty"`
+	// Country is the approximate country.
+	Country string `json:"country,omitempty"`
+}
+
 type ChatCompletionRequest struct {
 	// Messages: A list of messages comprising the conversation so far.
 	// Depending on the model you use, different message types (modalities) are supported,
@@ -702,6 +743,11 @@ type ChatCompletionRequest struct {
 	// PredictionContent provides configuration for a Predicted Output, which can greatly improve response times when large parts of the model response are known ahead of time.
 	PredictionContent *PredictionContent `json:"prediction,omitempty"`
 
+	// WebSearchOptions configures web search tool for models that support it.
+	// This tool searches the web for relevant results to use in a response.
+	// Docs: https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat
+	WebSearchOptions *WebSearchOptions `json:"web_search_options,omitempty"` //nolint:tagliatelle //follow openai api
+
 	*GCPVertexAIVendorFields `json:",inline,omitempty"`
 	*AnthropicVendorFields   `json:",inline,omitempty"`
 }
@@ -837,6 +883,11 @@ type ChatCompletionResponse struct {
 	// Usage is described in the OpenAI API documentation:
 	// https://platform.openai.com/docs/api-reference/chat/object#chat/object-usage
 	Usage ChatCompletionResponseUsage `json:"usage,omitzero"`
+
+	// Obfuscation are random characters that normalize payload sizes as a
+	// mitigation to certain side-channel attacks.
+	// https://platform.openai.com/docs/api-reference/responses/get#responses_get-include_obfuscation
+	Obfuscation string `json:"obfuscation,omitempty"`
 }
 
 // ChatCompletionChoicesFinishReason The reason the model stopped generating tokens. This will be `stop` if the model
@@ -924,6 +975,43 @@ type ChatCompletionResponseChoiceMessage struct {
 
 	// The tool calls generated by the model, such as function calls.
 	ToolCalls []ChatCompletionMessageToolCallParam `json:"tool_calls,omitempty"`
+
+	// Annotations for the message, when applicable, as when using the web search tool.
+	Annotations []Annotation `json:"annotations,omitempty"`
+
+	// Audio is the audio response generated by the model, if applicable.
+	Audio *ChatCompletionResponseChoiceMessageAudio `json:"audio,omitempty"`
+}
+
+// URLCitation contains citation information for web search results.
+// Docs: https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat
+type URLCitation struct {
+	// EndIndex is the index of the last character of the URL citation in the message.
+	EndIndex int `json:"end_index"`
+	// StartIndex is the index of the first character of the URL citation in the message.
+	StartIndex int `json:"start_index"`
+	// URL is the URL of the web resource.
+	URL string `json:"url"`
+	// Title is the title of the web resource.
+	Title string `json:"title"`
+}
+
+// Annotation represents a URL citation when using web search.
+// The annotation appears in message content when the model cites web sources.
+// Docs: https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat
+type Annotation struct {
+	// Type is the type of the annotation. Always "url_citation" for web search.
+	Type string `json:"type"`
+	// URLCitation contains the citation details when type is "url_citation".
+	URLCitation *URLCitation `json:"url_citation,omitempty"` //nolint:tagliatelle //follow openai api
+}
+
+// ChatCompletionResponseChoiceMessageAudio is described in the OpenAI API documentation.
+type ChatCompletionResponseChoiceMessageAudio struct {
+	Data       string `json:"data"`
+	ExpiresAt  int64  `json:"expires_at"`
+	ID         string `json:"id"`
+	Transcript string `json:"transcript"`
 }
 
 // ChatCompletionResponseUsage is described in the OpenAI API documentation:
@@ -941,6 +1029,10 @@ type ChatCompletionResponseUsage struct {
 
 // CompletionTokensDetails breakdown of tokens used in a completion.
 type CompletionTokensDetails struct {
+	// Text input tokens present in the prompt.
+	TextTokens int `json:"text_tokens,omitzero"`
+	// ^^  TODO: no idea why this is undocumented on the official OpenAI API docs.
+
 	// When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion.
 	AcceptedPredictionTokens int `json:"accepted_prediction_tokens,omitzero"`
 	// Audio input tokens generated by the model.
@@ -955,6 +1047,10 @@ type CompletionTokensDetails struct {
 
 // PromptTokensDetails breakdown of tokens used in the prompt.
 type PromptTokensDetails struct {
+	// Text input tokens present in the prompt.
+	TextTokens int `json:"text_tokens,omitzero"`
+	// ^^  TODO: no idea why this is undocumented on the official OpenAI API docs.
+
 	// Audio input tokens present in the prompt.
 	AudioTokens int `json:"audio_tokens,omitzero"`
 	// Cached tokens present in the prompt.
@@ -989,6 +1085,11 @@ type ChatCompletionResponseChunk struct {
 	// Usage is described in the OpenAI API documentation:
 	// https://platform.openai.com/docs/api-reference/chat/streaming#chat/streaming-usage
 	Usage *ChatCompletionResponseUsage `json:"usage,omitempty"`
+
+	// Obfuscation are random characters that normalize payload sizes as a
+	// mitigation to certain side-channel attacks.
+	// https://platform.openai.com/docs/api-reference/responses/get#responses_get-include_obfuscation
+	Obfuscation string `json:"obfuscation,omitempty"`
 }
 
 // String implements fmt.Stringer.
@@ -1009,9 +1110,10 @@ type ChatCompletionResponseChunkChoice struct {
 // ChatCompletionResponseChunkChoiceDelta is described in the OpenAI API documentation:
 // https://platform.openai.com/docs/api-reference/chat/streaming#chat/streaming-choices
 type ChatCompletionResponseChunkChoiceDelta struct {
-	Content   *string                              `json:"content,omitempty"`
-	Role      string                               `json:"role,omitempty"`
-	ToolCalls []ChatCompletionMessageToolCallParam `json:"tool_calls,omitempty"`
+	Content     *string                              `json:"content,omitempty"`
+	Role        string                               `json:"role,omitempty"`
+	ToolCalls   []ChatCompletionMessageToolCallParam `json:"tool_calls,omitempty"`
+	Annotations []Annotation                         `json:"annotations,omitempty"`
 }
 
 // Error is described in the OpenAI API documentation