feat(core): add metadata field to ResponseItem (#28355)

## Description

This PR adds an optional `metadata` field to `ResponseItem` for
Responses API calls. Only mechanical plumbing, no actual values
populated and sent yet. Turns out just adding a new field to
`ResponseItem` has quite a large blast radius already.

This change is backwards compatible because `metadata` is optional and
omitted when absent, so existing response items and rollout history
without it still deserialize and requests that do not set it keep the
same wire shape. For provider compatibility, we strip out `metadata`
before non-OpenAI Responses requests so Azure and AWS Bedrock never see
this field.

My followup PR here will actually make use of it to start storing and
passing along `turn_id`: https://github.com/openai/codex/pull/28360

## What changed

- Added `ResponseItemMetadata` with optional `turn_id`, plus optional
`metadata` on Responses API item variants and inter-agent communication.
- Preserved item metadata through response-item rewrites such as
truncation, missing tool-output synthesis, compaction history
rebuilding, visible-history conversion, rollout/resume, and generated
app-server schemas/types.
- Strip item metadata from non-OpenAI Responses requests while
preserving it for OpenAI-shaped requests.
- Updated the mechanical fixture/test construction churn required by the
new optional field.
This commit is contained in:
Owen Lin
2026-06-15 15:05:28 -07:00
committed by GitHub
Unverified
parent bef99f861b
commit 040dafa32d
85 changed files with 1637 additions and 92 deletions
@@ -2285,6 +2285,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"phase": {
"anyOf": [
{
@@ -2325,6 +2335,16 @@
},
"type": "array"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"recipient": {
"type": "string"
},
@@ -2363,6 +2383,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"summary": {
"items": {
"$ref": "#/definitions/ReasoningItemReasoningSummary"
@@ -2404,6 +2434,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"$ref": "#/definitions/LocalShellStatus"
},
@@ -2438,6 +2478,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -2483,6 +2533,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -2510,6 +2570,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"output": {
"$ref": "#/definitions/FunctionCallOutputBody"
},
@@ -2544,6 +2614,16 @@
"input": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -2575,6 +2655,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@@ -2611,6 +2701,16 @@
"execution": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
@@ -2654,6 +2754,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -2679,6 +2789,16 @@
"id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"result": {
"type": "string"
},
@@ -2713,6 +2833,16 @@
"encrypted_content": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction"
@@ -2730,6 +2860,16 @@
},
{
"properties": {
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction_trigger"
@@ -2752,6 +2892,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"context_compaction"
@@ -2784,6 +2934,17 @@
}
]
},
"ResponseItemMetadata": {
"properties": {
"turn_id": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"ResponsesApiWebSearchAction": {
"oneOf": [
{
@@ -14639,6 +14639,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"phase": {
"anyOf": [
{
@@ -14679,6 +14689,16 @@
},
"type": "array"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"recipient": {
"type": "string"
},
@@ -14717,6 +14737,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"summary": {
"items": {
"$ref": "#/definitions/v2/ReasoningItemReasoningSummary"
@@ -14758,6 +14788,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"$ref": "#/definitions/v2/LocalShellStatus"
},
@@ -14792,6 +14832,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -14837,6 +14887,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -14864,6 +14924,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"output": {
"$ref": "#/definitions/v2/FunctionCallOutputBody"
},
@@ -14898,6 +14968,16 @@
"input": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -14929,6 +15009,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@@ -14965,6 +15055,16 @@
"execution": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
@@ -15008,6 +15108,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -15033,6 +15143,16 @@
"id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"result": {
"type": "string"
},
@@ -15067,6 +15187,16 @@
"encrypted_content": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction"
@@ -15084,6 +15214,16 @@
},
{
"properties": {
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction_trigger"
@@ -15106,6 +15246,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/v2/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"context_compaction"
@@ -15138,6 +15288,17 @@
}
]
},
"ResponseItemMetadata": {
"properties": {
"turn_id": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"ResponsesApiWebSearchAction": {
"oneOf": [
{
@@ -11112,6 +11112,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"phase": {
"anyOf": [
{
@@ -11152,6 +11162,16 @@
},
"type": "array"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"recipient": {
"type": "string"
},
@@ -11190,6 +11210,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"summary": {
"items": {
"$ref": "#/definitions/ReasoningItemReasoningSummary"
@@ -11231,6 +11261,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"$ref": "#/definitions/LocalShellStatus"
},
@@ -11265,6 +11305,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -11310,6 +11360,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -11337,6 +11397,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"output": {
"$ref": "#/definitions/FunctionCallOutputBody"
},
@@ -11371,6 +11441,16 @@
"input": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -11402,6 +11482,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@@ -11438,6 +11528,16 @@
"execution": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
@@ -11481,6 +11581,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -11506,6 +11616,16 @@
"id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"result": {
"type": "string"
},
@@ -11540,6 +11660,16 @@
"encrypted_content": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction"
@@ -11557,6 +11687,16 @@
},
{
"properties": {
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction_trigger"
@@ -11579,6 +11719,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"context_compaction"
@@ -11611,6 +11761,17 @@
}
]
},
"ResponseItemMetadata": {
"properties": {
"turn_id": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"ResponsesApiWebSearchAction": {
"oneOf": [
{
@@ -384,6 +384,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"phase": {
"anyOf": [
{
@@ -424,6 +434,16 @@
},
"type": "array"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"recipient": {
"type": "string"
},
@@ -462,6 +482,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"summary": {
"items": {
"$ref": "#/definitions/ReasoningItemReasoningSummary"
@@ -503,6 +533,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"$ref": "#/definitions/LocalShellStatus"
},
@@ -537,6 +577,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -582,6 +632,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -609,6 +669,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"output": {
"$ref": "#/definitions/FunctionCallOutputBody"
},
@@ -643,6 +713,16 @@
"input": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -674,6 +754,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@@ -710,6 +800,16 @@
"execution": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
@@ -753,6 +853,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -778,6 +888,16 @@
"id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"result": {
"type": "string"
},
@@ -812,6 +932,16 @@
"encrypted_content": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction"
@@ -829,6 +959,16 @@
},
{
"properties": {
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction_trigger"
@@ -851,6 +991,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"context_compaction"
@@ -883,6 +1033,17 @@
}
]
},
"ResponseItemMetadata": {
"properties": {
"turn_id": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"ResponsesApiWebSearchAction": {
"oneOf": [
{
@@ -455,6 +455,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"phase": {
"anyOf": [
{
@@ -495,6 +505,16 @@
},
"type": "array"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"recipient": {
"type": "string"
},
@@ -533,6 +553,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"summary": {
"items": {
"$ref": "#/definitions/ReasoningItemReasoningSummary"
@@ -574,6 +604,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"$ref": "#/definitions/LocalShellStatus"
},
@@ -608,6 +648,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -653,6 +703,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -680,6 +740,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"output": {
"$ref": "#/definitions/FunctionCallOutputBody"
},
@@ -714,6 +784,16 @@
"input": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
@@ -745,6 +825,16 @@
"call_id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
@@ -781,6 +871,16 @@
"execution": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
@@ -824,6 +924,16 @@
],
"writeOnly": true
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"status": {
"type": [
"string",
@@ -849,6 +959,16 @@
"id": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"result": {
"type": "string"
},
@@ -883,6 +1003,16 @@
"encrypted_content": {
"type": "string"
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction"
@@ -900,6 +1030,16 @@
},
{
"properties": {
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"compaction_trigger"
@@ -922,6 +1062,16 @@
"null"
]
},
"metadata": {
"anyOf": [
{
"$ref": "#/definitions/ResponseItemMetadata"
},
{
"type": "null"
}
]
},
"type": {
"enum": [
"context_compaction"
@@ -954,6 +1104,17 @@
}
]
},
"ResponseItemMetadata": {
"properties": {
"turn_id": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"ResponsesApiWebSearchAction": {
"oneOf": [
{