fix: preserve empty-string content and reject images on FoundationModels

- Message.content now distinguishes "no text part" (nil) from "an empty
  text part" (""), so an empty tool result round-trips unchanged instead
  of collapsing to nil. Mirror the same in OpenAI content encoding.
- FoundationModelsChatProvider now throws a clear invalidConfiguration
  error when a message carries images, instead of silently dropping them
  or surfacing a misleading "No user message found" error.
- Add regression test for empty-string content round-trip.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: JinjunHan

Sources/AgentKit/Conversation/Message.swift

@@ -41,12 +41,14 @@ public struct Message: Sendable, Identifiable {
     /// The text content of the message, if any.
     ///
     /// Returns the concatenated text of all ``ContentPart/text(_:)`` parts, or
-    /// `nil` when the message carries no text (e.g. an image-only or
-    /// tool-call-only message). This mirrors the text-only API that predates
-    /// multimodal support, so existing call sites keep working unchanged.
+    /// `nil` when the message carries no text part at all (e.g. an image-only or
+    /// tool-call-only message). A message that carries an *empty* text part still
+    /// reports `""` rather than `nil`, so an empty tool result round-trips
+    /// unchanged. This mirrors the text-only API that predates multimodal
+    /// support, so existing call sites keep working unchanged.
     public var content: String? {
-        let text = parts.compactMap(\.text).joined()
-        return text.isEmpty ? nil : text
+        let texts = parts.compactMap(\.text)
+        return texts.isEmpty ? nil : texts.joined()
     }
 
     /// The image parts of the message, in order. Empty when there are none.

Sources/AgentKit/Provider/FoundationModels/FoundationModelsChatProvider.swift

@@ -40,6 +40,7 @@ public struct FoundationModelsChatProvider: ChatProvider {
         tools: [any AgentKit.Tool],
         configuration: ProviderConfiguration
     ) async throws(AgentKitError) -> ChatResponse {
+        try Self.assertNoImages(in: messages)
         let session = makeSession(from: messages)
 
         guard let lastUserMessage = messages.last(where: { $0.role == .user }),
@@ -68,6 +69,12 @@ public struct FoundationModelsChatProvider: ChatProvider {
         tools: [any AgentKit.Tool],
         configuration: ProviderConfiguration
     ) -> AsyncThrowingStream<ChatStreamDelta, any Error> {
+        do {
+            try Self.assertNoImages(in: messages)
+        } catch {
+            return AsyncThrowingStream { $0.finish(throwing: error) }
+        }
+
         let session = makeSession(from: messages)
 
         guard let lastUserMessage = messages.last(where: { $0.role == .user }),
@@ -109,6 +116,19 @@ public struct FoundationModelsChatProvider: ChatProvider {
 
     // MARK: - Private
 
+    /// Rejects any message carrying image content.
+    ///
+    /// Apple's on-device Foundation Models framework is text-only, so silently
+    /// dropping images would produce confusing results. Fail loudly instead.
+    private static func assertNoImages(in messages: [Message]) throws(AgentKitError) {
+        if messages.contains(where: { !$0.images.isEmpty }) {
+            throw .invalidConfiguration(
+                "FoundationModelsChatProvider is text-only and does not support image input. "
+                + "Use OpenAIChatProvider or ClaudeChatProvider for multimodal messages."
+            )
+        }
+    }
+
     private func makeSession(from messages: [Message]) -> LanguageModelSession {
         let systemInstructions = messages
             .filter { $0.role == .system }

Sources/AgentKit/Provider/OpenAI/OpenAIChatProvider.swift

@@ -292,8 +292,9 @@ public struct OpenAIChatProvider: ChatProvider {
 
         let hasImage = parts.contains { $0.image != nil }
         if !hasImage {
-            let text = parts.compactMap(\.text).joined()
-            return text.isEmpty ? nil : .text(text)
+            // Preserve an empty text part (e.g. an empty tool result) as "".
+            let texts = parts.compactMap(\.text)
+            return texts.isEmpty ? nil : .text(texts.joined())
         }
 
         let requestParts: [OpenAIChatRequest.RequestContentPart] = parts.compactMap { part in

Tests/AgentKitTests/MultimodalTests.swift

@@ -23,6 +23,12 @@ final class MultimodalTests: XCTestCase {
         XCTAssertTrue(message.parts.isEmpty)
     }
 
+    func testEmptyStringContentRoundTrips() {
+        // An empty tool result ("") must stay "" rather than collapsing to nil.
+        let message = Message.tool(callID: "call_1", content: "")
+        XCTAssertEqual(message.content, "")
+    }
+
     func testMultimodalUserMessageOrdersTextBeforeImages() {
         let image = ImageContent.base64("QUJD", mediaType: "image/png")
         let message = Message.user(text: "describe", images: [image])