From 563d747fff0370d16e5cffff5a11e8e02e17bb8b Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Mon, 30 Mar 2026 22:45:03 +0000
Subject: [PATCH] feat(api): add phase field to conversation messages

---
 .stats.yml                    |  4 ++--
 conversations/conversation.go | 19 +++++++++++++++++++
 conversations/item.go         |  3 +++
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 102ccb9..f77b897 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 139
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-2fab88288cbbe872f5d61d1d47da2286662a123b4312bc7fc36addba6607cd67.yml
-openapi_spec_hash: a7ee80374e409ed9ecc8ea2e3cd31071
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-89e54b8e2c185d30e869f73e7798308d56a6a835a675d54628dd86836f147879.yml
+openapi_spec_hash: 85b0dd465aa1a034f2764b0758671f21
 config_hash: 5635033cdc8c930255f8b529a78de722
diff --git a/conversations/conversation.go b/conversations/conversation.go
index 05ffe28..f016e69 100644
--- a/conversations/conversation.go
+++ b/conversations/conversation.go
@@ -200,6 +200,13 @@ type Message struct {
 	Status MessageStatus `json:"status" api:"required"`
 	// The type of the message. Always set to `message`.
 	Type constant.Message `json:"type" default:"message"`
+	// Labels an `assistant` message as intermediate commentary (`commentary`) or the
+	// final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when
+	// sending follow-up requests, preserve and resend phase on all assistant messages
+	// — dropping it can degrade performance. Not used for user messages.
+	//
+	// Any of "commentary", "final_answer".
+	Phase MessagePhase `json:"phase" api:"nullable"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
 	JSON struct {
 		ID          respjson.Field
@@ -207,6 +214,7 @@ type Message struct {
 		Role        respjson.Field
 		Status      respjson.Field
 		Type        respjson.Field
+		Phase       respjson.Field
 		ExtraFields map[string]respjson.Field
 		raw         string
 	} `json:"-"`
@@ -411,6 +419,17 @@ const (
 	MessageStatusIncomplete MessageStatus = "incomplete"
 )
 
+// Labels an `assistant` message as intermediate commentary (`commentary`) or the
+// final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when
+// sending follow-up requests, preserve and resend phase on all assistant messages
+// — dropping it can degrade performance. Not used for user messages.
+type MessagePhase string
+
+const (
+	MessagePhaseCommentary  MessagePhase = "commentary"
+	MessagePhaseFinalAnswer MessagePhase = "final_answer"
+)
+
 // A summary text from the model.
 type SummaryTextContent struct {
 	// A summary of the reasoning output from the model so far.
diff --git a/conversations/item.go b/conversations/item.go
index 1b7708c..0ce05a8 100644
--- a/conversations/item.go
+++ b/conversations/item.go
@@ -152,6 +152,8 @@ type ConversationItemUnion struct {
 	// "mcp_approval_request", "mcp_approval_response", "mcp_call", "custom_tool_call",
 	// "custom_tool_call_output".
 	Type string `json:"type"`
+	// This field is from variant [Message].
+	Phase MessagePhase `json:"phase"`
 	// This field is a union of [string], [any], [string], [string]
 	Arguments ConversationItemUnionArguments `json:"arguments"`
 	CallID    string                         `json:"call_id"`
@@ -215,6 +217,7 @@ type ConversationItemUnion struct {
 		Role                     respjson.Field
 		Status                   respjson.Field
 		Type                     respjson.Field
+		Phase                    respjson.Field
 		Arguments                respjson.Field
 		CallID                   respjson.Field
 		Name                     respjson.Field