Document attachments in tool outputs

[qoli]

Summary

• extend the prompt-attachment example to an ordinary Tool output
• state that text and image ordering and image orientation survive Tool output lowering
• document the Compatibility SPI used by back-deployment provider adapters
• narrow the remaining unsupported attachment forms

Stack

The prompt-attachment foundation from #310 landed through #321. This documentation PR now contains the current #312 head and depends only on #312; compared with that branch, its change remains README-only.

Verification

• final README diff reviewed with git diff --check
• referenced Attachment initializers and Tool.makeOutputSegments(from:) verified against source
• no application code changed

[Copilot]

🟡 Changes recommended

Empty builders now produce zero-segment prompts that provider adapters may reject.

1 open finding

• Preserve empty-text component for empty prompts · New

What changed in this PR

Adds Foundation Models 27-style image attachments to prompts and tool outputs, including transcript/provider bridging and documentation.

Changes:

• Preserves ordered text and image prompt segments.
• Bridges attachments through Foundation Models and Gemini tool responses.
• Documents attachment support and the compatibility SPI.

File	Description
README.md	Documents attachments and compatibility behavior.
Sources/​AnyLanguageModel/​Attachment.swift	Adds typed image attachments.
Sources/​AnyLanguageModel/​Prompt.swift	Stores and lowers ordered prompt components.
Sources/​AnyLanguageModel/​Tool.swift	Preserves segments in tool outputs.
Sources/​AnyLanguageModel/​LanguageModelSession.swift	Records attachment-bearing prompts.
Sources/​AnyLanguageModel/​Models/​SystemLanguageModel.swift	Bridges attachments to Foundation Models.
Sources/​AnyLanguageModel/​Models/​FoundationLanguageModel.swift	Handles throwing prompt conversion.
Sources/​AnyLanguageModel/​Models/​GeminiLanguageModel.swift	Serializes image tool responses.
Tests/​AnyLanguageModelTests/​PromptAttachmentTests.swift	Tests attachment preservation and bridging.
Tests/​AnyLanguageModelTests/​GeminiThoughtSignatureTests.swift	Tests Gemini image tool responses.
Tests/​AnyLanguageModelTests/​ToolExecutionDelegateTests.swift	Imports the compatibility SPI.
Tests/​AnyLanguageModelTests/​DynamicInstructionsTests.swift	Imports the compatibility SPI.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The implementation consistently preserves attachment content across lowering and provider bridges with focused regression coverage.

0 open findings

1 resolved since last review

• Preserve empty-text component for empty prompts

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

The included platform-gated native bridge and provider payload changes warrant human validation despite no identified blocking defects.

0 open findings

🧠 Review effort: Balanced