Define and support DIAL attachments over the Responses API

[Fedir-Yatsenko]

Name and Version

ai-dial-core=0.46.0

What is the problem this feature will solve?

DIAL's attachment concept is defined for the chat completion format: an Attachment object (type, title, data, url, reference_type, reference_url) placed in custom_content.attachments. The Responses API has its own native file support (input_file, input_image, code_interpreter_call outputs), but it does not cover the same ground, and Core recognizes only a narrow subset of it.

This matters because attachment locations are what drive access granting. Core auto-shares files by walking a fixed list of JSONPaths and writing the results into the per-request API key:

• On the request, CollectRequestAttachmentsFn checks each collected URL and grants READ_ONLY on it to the downstream deployment (attachedFiles / attachedFolders).
• On the response, CollectResponseAttachmentsFn does the reverse for the caller.
• AccessService then resolves reads against exactly those maps.

A file in a location that is not on the list is never collected, so no grant is made. Nothing fails at proxy time — the caller or the application simply gets 403 later when it tries to download the file.

Concrete gaps on the Responses API path:

1. No Attachment equivalent. The Responses path only ever reads bare URL strings, so there is no title, no inline data, no reference_url/reference_type, and no metadata: prefix. The last one means an application can never attach a folder, even though the auto-share logic supports attachedFolders.
2. No slot for a file produced alongside the answer. The only genuinely assistant-side output covered is code_interpreter_call.outputs. The other two covered paths are tool-call inputs — the code itself notes they are included only to follow the OpenAI docs.
3. output_text.annotations[*] is not handled — file_citation, container_file_citation, file_path. This is the standard's own way of pointing at produced files, and it is the direct analog of chat completion's custom_content.annotations[*].body.source.attachment, which is handled. Also unhandled: file_search_call.results, mcp_call outputs.
4. No custom_input equivalent for handing DIAL files to an application out of band.
5. Nothing is documented. There are no Responses API schemas in openapi-generator, and ResponsesApiRequest in docs/open_api_core.yaml is an empty type: object.

Current path coverage

Chat completion response — CollectResponseChatCompletionAttachmentsFn, via readCustomAttachment (Attachment objects):

choices[*].message|delta.custom_content.attachments[*]
choices[*].message|delta.custom_content.stages[*].attachments[*]
choices[*].message|delta.custom_content.annotations[*].body.source.attachment

Responses API response — CollectResponsesApiOutputAttachmentsFn, via readAttachment (bare URL strings):

output[code_interpreter_call].outputs[image].url
output[custom_tool_call_output|function_call_output].output[input_image].image_url
output[custom_tool_call_output|function_call_output].output[input_file].file_url

Responses API request — ResponsesApiRequest.collectAttachments():

input[message].content[input_image].image_url
input[message].content[input_file].file_url
input[custom_tool_call_output|function_call_output].output[input_image].image_url
input[custom_tool_call_output|function_call_output].output[input_file].file_url
input[computer_call_output].output.image_url
tools[image_generation].input_image_mask.image_url

Note also that BaseFunction.fromAnyUrl skips absolute and data: URLs as public resources, so even covered locations are not granted access when the upstream returns an absolute URL.

What is the feature you are proposing to solve the problem?

Define how DIAL attachments are carried over the Responses API and make access granting cover them:

• Decide the mapping between the DIAL Attachment concept and native Responses constructs — which fields the standard already covers, and where the remainder (title, data, reference_url, folder attachments) should live.
• Extend the collected paths in CollectResponsesApiOutputAttachmentsFn and ResponsesApiRequest.collectAttachments() so that every location where a DIAL link can legitimately appear goes through the same permission check and auto-share flow. output_text.annotations[*] is the clearest missing case and has a working chat completion precedent.
• Document it — add Responses API schemas to openapi-generator and fill in ResponsesApiRequest in the OpenAPI document, so application authors know where to put files.

What alternatives have you considered?

• Leave it to applications to use absolute, pre-signed URLs. Bypasses DIAL's permission model entirely and loses per-request scoping.
• Require the chat completion interface whenever attachments are needed. Forces a protocol choice for an unrelated reason.

Related

Companion to #1774, which covers the same gap for stages. Both would extend the same two path lists and want a consistent attachment shape across interfaces.