fix(api): document message responses as serialized contracts

2026-06-26 23:01:11 +08:00 · 2026-06-26 03:15:46 +09:00 · 2026-06-26 03:15:46 +09:00 · ebf85810c2
commit ebf85810c2
parent a045cd1fc0
9 changed files with 21 additions and 30 deletions
--- a/api/controllers/console/app/message.py
+++ b/api/controllers/console/app/message.py
@ -167,12 +167,16 @@ register_schema_models(
    ChatMessagesQuery,
    MessageFeedbackPayload,
    FeedbackExportQuery,
+)
+register_response_schema_models(
+    console_ns,
    AnnotationCountResponse,
    SuggestedQuestionsResponse,
    MessageDetailResponse,
    MessageInfiniteScrollPaginationResponse,
+    SimpleResultResponse,
+    TextFileResponse,
 )
-register_response_schema_models(console_ns, SimpleResultResponse, TextFileResponse)


@console_ns.route("/apps/<uuid:app_id>/chat-messages")
--- a/api/openapi/markdown/console-openapi.md
+++ b/api/openapi/markdown/console-openapi.md
@ -13429,7 +13429,6 @@ Soft lifecycle state for Agent records.
 | created_at | integer |  | No |
 | files | [ string ] |  | Yes |
 | id | string |  | Yes |
-| message_chain_id | string |  | No |
 | message_id | string |  | Yes |
 | observation | string |  | No |
 | position | integer |  | Yes |
@ -14540,8 +14539,8 @@ Enum class for configurate method of provider model.
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
 | annotation_create_account | [SimpleAccount](#simpleaccount) |  | No |
+| annotation_id | string |  | Yes |
 | created_at | integer |  | No |
-| id | string |  | Yes |

 #### ConversationDetail

@ -17079,6 +17078,7 @@ Enum class for large language model mode.
 | agent_thoughts | [ [AgentThought](#agentthought) ] |  | No |
 | annotation | [ConversationAnnotation](#conversationannotation) |  | No |
 | annotation_hit_history | [ConversationAnnotationHitHistory](#conversationannotationhithistory) |  | No |
+| answer | string |  | Yes |
 | answer_tokens | integer |  | No |
 | conversation_id | string |  | Yes |
 | created_at | integer |  | No |
@ -17092,12 +17092,11 @@ Enum class for large language model mode.
 | inputs | object |  | Yes |
 | message | [JSONValue](#jsonvalue) |  | No |
 | message_files | [ [MessageFile](#messagefile) ] |  | No |
-| message_metadata_dict | [JSONValue](#jsonvalue) |  | No |
 | message_tokens | integer |  | No |
+| metadata | [JSONValue](#jsonvalue) |  | No |
 | parent_message_id | string |  | No |
 | provider_response_latency | number |  | No |
 | query | string |  | Yes |
-| re_sign_file_url_answer | string |  | Yes |
 | status | string |  | Yes |
 | workflow_run_id | string |  | No |

--- a/packages/contracts/generated/api/console/agent/types.gen.ts
+++ b/packages/contracts/generated/api/console/agent/types.gen.ts
@ -269,6 +269,7 @@ export type MessageDetailResponse = {
  agent_thoughts?: Array<AgentThought>
  annotation?: ConversationAnnotation | null
  annotation_hit_history?: ConversationAnnotationHitHistory | null
+  answer: string
  answer_tokens?: number | null
  conversation_id: string
  created_at?: number | null
@ -284,12 +285,11 @@ export type MessageDetailResponse = {
  }
  message?: JsonValue | null
  message_files?: Array<MessageFile>
-  message_metadata_dict?: JsonValue | null
  message_tokens?: number | null
+  metadata?: JsonValue | null
  parent_message_id?: string | null
  provider_response_latency?: number | null
  query: string
-  re_sign_file_url_answer: string
  status: string
  workflow_run_id?: string | null
 }
@ -723,7 +723,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
@ -743,8 +742,8 @@ export type ConversationAnnotation = {

 export type ConversationAnnotationHitHistory = {
  annotation_create_account?: SimpleAccount | null
+  annotation_id: string
  created_at?: number | null
-  id: string
 }

 export type HumanInputContent = {
--- a/packages/contracts/generated/api/console/agent/zod.gen.ts
+++ b/packages/contracts/generated/api/console/agent/zod.gen.ts
@ -570,7 +570,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),
@ -1056,8 +1055,8 @@ export const zConversationAnnotation = z.object({
 */
 export const zConversationAnnotationHitHistory = z.object({
  annotation_create_account: zSimpleAccount.nullish(),
+  annotation_id: z.string(),
  created_at: z.int().nullish(),
-  id: z.string(),
 })

 /**
@ -2035,6 +2034,7 @@ export const zMessageDetailResponse = z.object({
  agent_thoughts: z.array(zAgentThought).optional(),
  annotation: zConversationAnnotation.nullish(),
  annotation_hit_history: zConversationAnnotationHitHistory.nullish(),
+  answer: z.string(),
  answer_tokens: z.int().nullish(),
  conversation_id: z.string(),
  created_at: z.int().nullish(),
@ -2048,12 +2048,11 @@ export const zMessageDetailResponse = z.object({
  inputs: z.record(z.string(), zJsonValue),
  message: zJsonValue.nullish(),
  message_files: z.array(zMessageFile).optional(),
-  message_metadata_dict: zJsonValue.nullish(),
  message_tokens: z.int().nullish(),
+  metadata: zJsonValue.nullish(),
  parent_message_id: z.string().nullish(),
  provider_response_latency: z.number().nullish(),
  query: z.string(),
-  re_sign_file_url_answer: z.string(),
  status: z.string(),
  workflow_run_id: z.string().nullish(),
 })
--- a/packages/contracts/generated/api/console/apps/types.gen.ts
+++ b/packages/contracts/generated/api/console/apps/types.gen.ts
@ -472,6 +472,7 @@ export type MessageDetailResponse = {
  agent_thoughts?: Array<AgentThought>
  annotation?: ConversationAnnotation | null
  annotation_hit_history?: ConversationAnnotationHitHistory | null
+  answer: string
  answer_tokens?: number | null
  conversation_id: string
  created_at?: number | null
@ -487,12 +488,11 @@ export type MessageDetailResponse = {
  }
  message?: JsonValue | null
  message_files?: Array<MessageFile>
-  message_metadata_dict?: JsonValue | null
  message_tokens?: number | null
+  metadata?: JsonValue | null
  parent_message_id?: string | null
  provider_response_latency?: number | null
  query: string
-  re_sign_file_url_answer: string
  status: string
  workflow_run_id?: string | null
 }
@ -1500,7 +1500,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
@ -1520,8 +1519,8 @@ export type ConversationAnnotation = {

 export type ConversationAnnotationHitHistory = {
  annotation_create_account?: SimpleAccount | null
+  annotation_id: string
  created_at?: number | null
-  id: string
 }

 export type HumanInputContent = {
--- a/packages/contracts/generated/api/console/apps/zod.gen.ts
+++ b/packages/contracts/generated/api/console/apps/zod.gen.ts
@ -1152,7 +1152,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),
@ -2351,8 +2350,8 @@ export const zConversationPagination = z.object({
 */
 export const zConversationAnnotationHitHistory = z.object({
  annotation_create_account: zSimpleAccount.nullish(),
+  annotation_id: z.string(),
  created_at: z.int().nullish(),
-  id: z.string(),
 })

 /**
@ -3466,6 +3465,7 @@ export const zMessageDetailResponse = z.object({
  agent_thoughts: z.array(zAgentThought).optional(),
  annotation: zConversationAnnotation.nullish(),
  annotation_hit_history: zConversationAnnotationHitHistory.nullish(),
+  answer: z.string(),
  answer_tokens: z.int().nullish(),
  conversation_id: z.string(),
  created_at: z.int().nullish(),
@ -3479,12 +3479,11 @@ export const zMessageDetailResponse = z.object({
  inputs: z.record(z.string(), zJsonValue),
  message: zJsonValue.nullish(),
  message_files: z.array(zMessageFile).optional(),
-  message_metadata_dict: zJsonValue.nullish(),
  message_tokens: z.int().nullish(),
+  metadata: zJsonValue.nullish(),
  parent_message_id: z.string().nullish(),
  provider_response_latency: z.number().nullish(),
  query: z.string(),
-  re_sign_file_url_answer: z.string(),
  status: z.string(),
  workflow_run_id: z.string().nullish(),
 })
--- a/packages/contracts/generated/api/console/installed-apps/types.gen.ts
+++ b/packages/contracts/generated/api/console/installed-apps/types.gen.ts
@ -246,7 +246,6 @@ export type AgentThought = {
  created_at?: number | null
  files: Array<string>
  id: string
-  message_chain_id?: string | null
  message_id: string
  observation?: string | null
  position: number
--- a/packages/contracts/generated/api/console/installed-apps/zod.gen.ts
+++ b/packages/contracts/generated/api/console/installed-apps/zod.gen.ts
@ -266,7 +266,6 @@ export const zAgentThought = z.object({
  created_at: z.int().nullish(),
  files: z.array(z.string()),
  id: z.string(),
-  message_chain_id: z.string().nullish(),
  message_id: z.string(),
  observation: z.string().nullish(),
  position: z.int(),
--- a/web/features/agent-v2/agent-detail/configure/components/preview/chat.tsx
+++ b/web/features/agent-v2/agent-detail/configure/components/preview/chat.tsx
@ -217,14 +217,8 @@ const toFeedback = (feedback: NonNullable<MessageDetailResponse['feedbacks']>[nu
  }
 }

-type AgentDebugMessageWithLegacyAnswer = MessageDetailResponse & {
-  answer?: string | null
-}
-
 const getAgentDebugMessageAnswer = (message: MessageDetailResponse) => {
-  const legacyAnswer = (message as AgentDebugMessageWithLegacyAnswer).answer
-
-  return message.re_sign_file_url_answer ?? legacyAnswer ?? ''
+  return message.answer ?? ''
 }

 function getFormattedAgentDebugChatTree(messages: MessageDetailResponse[]): ChatItemInTree[] {