Swift SDK: support message attachments (image + file) for agent snapshots

[willwashburn]

Summary

The Swift SDK's messaging API (Channel.post, AgentClient.post(to:message:), AgentClient.dm(to:message:)) only accepts text. There is no way to attach binary/image data or a file to a message.

Native apps that want to send agents a visual snapshot of their state can't do it cleanly. The Whiteboard macOS app, for example, needs to send the agent a board snapshot = a PNG render + a scene.json scene graph alongside the user's text.

Request

Add attachment support to the Swift SDK send paths, e.g.:

try await agent.dm(
    to: "designer",
    message: "match the logo color",
    attachments: [
        .image(data: pngData, filename: "board.png"),
        .text(sceneJSON, filename: "scene.json")
    ]
)

and surface attachments on the inbound/observer side so receiving agents can read them.

Notes / open questions

• How should attachments be transported — inline (base64 in payload), or uploaded to a blob store with a URL/handle in the message (cf. relayfile)? A size threshold that switches between the two would be ideal.
• Should the TS and Python SDKs get the same surface for parity?
• For headless CLI-backed agents (codex/claude), delivering attachments as readable file paths in the workspace may be the most useful form.

Motivation

Agent perception in Whiteboard = PNG snapshot + JSON scene graph. Without attachment support we either inline base64 (bloats messages) or write files out-of-band and pass paths. First-class attachment support would make agent perception a one-call operation.

[willwashburn]

Closing as resolved-by-strategy: AgentRelaySDK (the relay-owned Swift facade this issue targeted) is being retired — it was always a thin wrapper over relaycast's official Swift SDK, and that SDK already implements attachments natively.

Relaycast's Relaycast product provides AgentFilesService on Relaycast.AgentClient (agent.files.upload(...), .complete(fileID:), .get(fileID:), .delete(fileID:), .list(...)), and message attachments via SendMessageOptions.attachments: [String]? on agent.send(...) / agent.post(...).

Swift consumers needing hosted-workspace participation should depend on relaycast's Relaycast product directly (https://github.com/AgentWorkforce/relaycast.git) going forward instead of AgentRelaySDK, which no longer ships from this repo.

---

Generated by Claude Code

[willwashburn]

Reopening: course reversal on PR #1259. Rather than retiring AgentRelaySDK and pointing consumers at relaycast's SDK directly, we're rebuilding it as a real sidecar matching @agent-relay/sdk's TS facade (relay-specific abstractions on top of relaycast, not just a rename-and-delegate wrapper) — same model the TS SDK already uses. This issue's ask will be implemented directly rather than closed by strategy.

---

Generated by Claude Code

[willwashburn]

Implemented in the shipped AgentRelaySDK (v10.2.0). AgentClient.post(to:message:attachments:) and dm(to:message:attachments:) accept [RelayAttachmentInput], and AgentClient.files.upload(...) provides the upload path for stored file ids — see packages/sdk-swift/Sources/AgentRelaySDK/AgentRelayClient.swift and RelayFacadeTypes.swift (tagged #1144). Closing as completed.

---

Generated by Claude Code