ios: add Agent attachments and shared transcript fade

docs/api/rest.md

@@ -23,6 +23,8 @@ Chat upload limits:
 
 ### `GET /v1/auth/session`
 - Response: `{ "authenticated": true, "mode": "open" | "token" }`
+- In token mode, a missing bearer token returns `401` (`missing bearer token`); an incorrect token returns `403` (`invalid bearer token`).
+- Web clients show a neutral sign-in form when the initial check has no token, and an error when a supplied token is rejected. Open development servers authenticate automatically; the sign-in form has no tokenless bypass.
 
 ## Models
 
@@ -606,7 +608,7 @@ messages.
 ### `POST /v1/agent/messages`
 
 Body: `{ "content": "Check the oven", "requestId": "client-generated-uuid" }`.
-Content must contain non-whitespace text and is limited to 40,000 characters;
+Content is limited to 40,000 characters; it must contain non-whitespace text unless attachment IDs are included;
 `requestId` is required (1–256 characters). Preserve the ID when retrying uncertain
 network results. The proxy fixes `channel: "sybil"`, `whenBusy: "followUp"`, and
 `wait: false`.
@@ -614,9 +616,9 @@ network results. The proxy fixes `channel: "sybil"`, `whenBusy: "followUp"`, and
 Returns the agent's `202 Accepted` receipt, including `id` (submission ID), `status`, and
 `messageId` such as `inbound:sybil:client-generated-uuid`. This is admission, not
 completion: watch the room for answers, including unsolicited later replies.
-Multiple requests can be accepted while the agent works. Attachments are not yet supported.
+Multiple requests can be accepted while the agent works. Optional `attachments: [{"id":"att_…"}]` accepts uploaded files as specified below; no client paths or inline file bytes are accepted.
 The proxy verifies successful receipts contain a positive submission ID, a known
-status (`queued`, `placed`, `done`, or `unanswered`), and the expected `messageId`.
+status (`queued`, `placed`, `done`, or `unanswered`), and the expected `messageId`. Attached sends also require matching ordered `attachmentIds` in the receipt.
 Invalid receipts return 502; delivery remains uncertain, so retry using the original
 `requestId` to avoid creating a duplicate message.
 
@@ -632,3 +634,55 @@ after showing the corresponding history; poll it to reconcile unread indicators
 across clients. Agent REST responses use `Cache-Control: no-store`.
 
 See the persistent Agent WebSocket section in `streaming-chat.md` for live updates.
+
+### Agent attachments (v1)
+
+`POST /v1/agent/attachments`: multipart/form-data with exactly one `file` part (original UTF-8 filename in Content-Disposition) and one `uploadId` field (client-generated UUID, stable across retries). Either part order is accepted. Request limit 8 MiB + 64 KiB. 201 new / 200 identical retry:
+
+```json
+{"attachment":{"id":"att_12345678-1234-4234-8234-123456789abc","kind":"text","filename":"notes.txt","mimeType":"text/plain","sizeBytes":12,"sha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","workspacePath":"/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/notes.txt"}}
+```
+
+`workspacePath` is OPTIONAL for clients, canonical absolute runtime path when supplied. Never a host path, URL, or request parameter. Descriptors must retain filename/mimeType/sizeBytes/sha256. `kind` is `image`, `text`, or `file`. IDs are opaque. UUID retries must match normalized filename, effective MIME type and bytes, otherwise 409 `idempotency_conflict`. Filename is NFC normalized, 1–255 UTF-8 bytes, no slash/backslash/control characters, not `.`/`..`. A leading dot becomes `_` in the on-disk basename only; display filename remains unchanged.
+
+`POST /v1/agent/messages`:
+
+```json
+{"content":"Read these notes","requestId":"client-stable-id","attachments":[{"id":"att_12345678-1234-4234-8234-123456789abc"}]}
+```
+
+`content` is required, <=40,000 characters; empty/whitespace is allowed with attachments. `requestId` is 1–256 characters and must survive retries. Omit attachments for text-only requests. At most 8 distinct references, 32 MiB total original bytes. References contain ONLY `id`; filenames, paths, URLs, base64 and forged workspacePath are rejected. Root delivery uses channel sybil, followUp and wait=false. 202 receipt:
+
+```json
+{"id":123,"status":"queued","messageId":"inbound:sybil:client-stable-id","attachmentIds":["att_12345678-1234-4234-8234-123456789abc"]}
+```
+
+Receipt status also permits placed/done/unanswered. `attachmentIds` is present for attached input, in request order, and MUST be checked before treating delivery as acknowledged. Caption + ordered IDs are durably bound to requestId; conflicting replay 409. Native admission atomically stores the input payload, binding, quota charge and worker eligibility; a competing text-only input cannot falsely acknowledge attachment IDs. Network errors may be retried with the same request/upload IDs. Never auto-create a fresh ID on ambiguous failure.
+
+History, replay and queued activity use the existing public message schema with `metadata.agentAttachments` containing these descriptors. `content` is the original caption, or `Attached: notes.txt.` for a file-only message. No model-only manifest, text preview or base64 is inserted into public message content. Ordinary chat's `metadata.attachments` schema is unchanged. Raw tool rows stay in the protocol; client transcript filters stay unchanged.
+
+`GET /v1/agent/attachments/:id/content`: authenticated original bytes, Content-Length, Content-Disposition attachment (safe ASCII filename and UTF-8 filename*), Cache-Control private/no-store and nosniff. No URLs containing tokens, public static mount, redirects or inline serving. Browser previews use authenticated fetch + revocable blob URL. Native downloads hold one of four slots through response finish/close/error, with a 30-second outbound timeout and disconnect cleanup. Raster types retain their validated MIME type; text downloads use text/plain; other files application/octet-stream. Clients can display/copy workspacePath as text.
+
+### Attachment capability and errors
+
+Optional `GET /v1/agent` field:
+
+```json
+{"capabilities":{"attachments":{"version":1,"maxCount":8,"maxTotalBytes":33554432,"maxImageBytes":6291456,"maxFileBytes":8388608,"imageMimeTypes":["image/png","image/jpeg","image/gif","image/webp"],"maxImagePixels":50000000,"maxImageDimension":16384,"quotaBytes":1073741824,"usedBytes":0,"remainingBytes":1073741824,"maxConcurrentUploads":2,"maxConcurrentDecodes":1}}}
+```
+
+Quota values are a snapshot, not a reservation. Absence disables attachment selection and sending. Backend rejects attachments against an old/unsafe upstream rather than allowing dropped references. Sybil also requires ADMIN_TOKEN for attachments; text-only open development behavior remains compatible.
+
+Errors: `{ "error": true, "message": "...", "statusCode": 507, "code": "attachment_quota_exceeded", "quotaBytes": 1073741824, "remainingBytes": 1200, "requiredBytes": 20000 }`. Quota numbers are included for 507; no host filesystem information. 400 invalid_upload/invalid_attachment; 401 authentication; 404 attachment_not_found; 409 idempotency_conflict; 413 attachment_limit_exceeded; 415 unsupported_media_type; 422 invalid_image/image_model_unsupported; 429 attachments_busy with Retry-After: 2; 503 attachments_unavailable; 507 attachment_quota_exceeded; 502 unavailable/invalid upstream at proxy. Clients show message and retain retry identity. Remove from composer does not delete completed durable uploads.
+
+### Runtime access and release requirements
+
+The runtime resolves IDs to persistent `WORKSPACE_DIR/uploads/<id>/<safe-original-basename>` files (default `/data/workspace/uploads/...`), backed by the existing `/data` mount. Images are native model image blocks, never remote links: supported PNG/JPEG/GIF/WebP originals are at most 6 MiB and are prepared as a bounded static first frame (orientation corrected, at most 2000×2000 and 4.5 MiB base64, further limited by the actual model). Reject unsupported image models; no arbitrary document/file provider blocks. Other files are at most 8 MiB and are available through actual workspace read/bash tools. Valid recognized UTF-8 text receives a bounded preview of 16,000 Unicode characters per file / 64,000 per input. PDF/archive/binary files are paths plus metadata. Original hash, size and confinement are validated during resolution. Root and workers share the same workspace; explicit `subagent` spawn/send `attachmentIds` persist in durable Reporter tasks and use the same resolver. Preparation saturation retries through a durable checkpoint after two seconds using the same Reporter request ID. Permanent admission failures, including quota exhaustion, reach the parent through the durable worker-report path. Uploads never auto-execute.
+
+Global `SYBIL_AGENT_ATTACHMENT_QUOTA_BYTES` defaults to 1 GiB. Concurrent reservations cover originals, static renditions, staging, metadata and conservative attachment input copies. Quota is conservative accounting, not free disk space. No complete upload expiry or delete endpoint is enabled. Removed composer files stay stored; crashed/uncertain reservations stay charged across restart until deliberate operator reconciliation. Ordinary authorized workspace tool writes and unrelated conversation history are outside attachment-ingestion accounting. Runtime uploads default to two concurrently (`SYBIL_AGENT_ATTACHMENT_UPLOADS`, max8), image decodes one (`SYBIL_AGENT_ATTACHMENT_DECODES`, max4); bounded input preparation and proxy transfers return429 when saturated. Disconnected proxy transfers cancel upstream work and release slots.
+
+Release requires native `SYBIL_AGENT_AUTH_MODE=token` with nonempty `SYBIL_AGENT_API_KEY`, plus backend `ADMIN_TOKEN` and matching server-side `SYBIL_AGENT_API_KEY` / `SYBIL_AGENT_BASE_URL`. Native open mode cannot advertise/store/download attachments. A runtime containing attachment records/files refuses open startup; raw/model APIs and sockets are protected in token mode. An open Sybil proxy also refuses access to an attachment-capable native runtime, rather than exposing its history through a private server credential. Explicit text-only open development remains supported with an open/legacy runtime lacking attachment capability. Native keys never enter browser/iOS payloads. No insecure development opt-in is enabled.
+
+The runtime source is built into its container: rebuild it with pinned busboy/sharp dependencies for the target Node/Linux platform before release. The deployed open auth mode must be changed separately; no deployed config or mount is modified by this implementation. Backend and web must be upgraded with runtime capability/auth configured before clients advertise uploads.
+
+Browser drafts retain upload IDs and completed descriptors across pane changes and reload. Incomplete uploads require reselection of the original filename/type/size and, once network delivery has begun, matching SHA-256 bytes; retries reuse uploadId. Sending persists the attachment-bearing outbox before clearing the draft. Message confirmation requires the same ordered attachment IDs in receipts and canonical echoes. Mismatched echoes must retain local attachments and delivery errors; they are not acknowledgement of a file submission.

docs/api/streaming-chat.md

@@ -15,6 +15,7 @@ Transport:
 
 Authentication:
 - Same as REST endpoints (`Authorization: Bearer <token>` when token mode is enabled)
+- The web client checks [`GET /v1/auth/session`](rest.md#get-v1authsession) before opening streams. An initial missing-token response prompts sign-in without an error; an incorrect supplied token is an authentication failure. The web sign-in form has no tokenless bypass; open development servers still authenticate automatically. Stream authorization requirements are unchanged.
 
 ## Chat Completion Request Body
 
@@ -335,3 +336,40 @@ cursor. Missing agent configuration closes with 4503.
 The proxy closes upstream sockets when browsers leave or Sybil shuts down.
 History remains durable in Sybil Agent. Shared read position is separate from delivery:
 update `GET`/`PUT /v1/agent/read-state` only when messages have actually been viewed.
+
+### Agent attachment history, queued activity and replay
+
+Uploads and attached sends use REST, as specified in [rest.md](./rest.md#agent-attachments-v1). WebSocket authentication, event types, stable message IDs, cursor semantics and raw tool rows are unchanged. Capability discovery is optional `GET /v1/agent` → `capabilities.attachments.version: 1`; absence disables new attachment sends. Upgrade/authenticate the native runtime and backend before advertising it.
+
+Both `messages.messages[]` and `activity.activity.queuedMessages[]` carry attachment descriptors under **`metadata.agentAttachments`**, distinct from ordinary chat's inline `metadata.attachments`:
+
+```json
+{
+  "id": "inbound:sybil:client-stable-id",
+  "role": "user",
+  "content": "Read these notes",
+  "createdAt": "2026-10-14T18:00:00.000Z",
+  "metadata": {
+    "kind": "message",
+    "channel": "sybil",
+    "status": "queued",
+    "agentAttachments": [{
+      "id": "att_12345678-1234-4234-8234-123456789abc",
+      "kind": "text",
+      "filename": "notes.txt",
+      "mimeType": "text/plain",
+      "sizeBytes": 12,
+      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "workspacePath": "/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/notes.txt"
+    }]
+  }
+}
+```
+
+`workspacePath` is optional, authoritative runtime text for display/copy, never a download URL or send parameter. Only `attachments:[{id}]` goes into POST messages. Committed/replayed messages retain the same ordered descriptors and original caption; file-only content is `Attached: notes.txt.`. Internal model manifests/previews and native base64 are excluded from public user message content. Root/worker native inputs and raw authorized model endpoints may contain the real image blocks; native token auth must protect all of them.
+
+Merge queued and committed messages by stable message ID. A matching ID alone does not confirm an attachment-bearing optimistic message: compare the ordered `metadata.agentAttachments[].id` against its local IDs as well. Retain descriptors, error and retry identity on a mismatch or uncertain receipt; show the error inline for touch clients. Matching canonical echoes can acknowledge delivery even if HTTP was lost. Preserve raw tool rows/cursors in client room state and existing transcript filtering. Old clients can ignore the additive metadata and still see a meaningful caption.
+
+Retrieve bytes using authenticated `GET /v1/agent/attachments/:id/content`; fetch with an Authorization header and use/revoke browser blob URLs for previews. Never add credentials to URLs or use a public file route. Persist completed descriptors and pending upload IDs with the composer/outbox; navigation cannot silently turn an attached draft into a text-only send. Incomplete reloaded uploads require verified file reselection or explicit removal, per the REST contract.
+
+Attached input admission and its request binding are atomic. Replay verifies the durable accepted payload, including the ordered attachment IDs, before acknowledging it. Queued attachment metadata survives restart even if placement did not run before the crash; normal queue recovery places the original input without duplicate charge or delivery. Worker preparation saturation retries through durable Reporter checkpoints; permanent admission failures appear through the existing worker-report path.

ios/Packages/Sybil/Sources/Sybil/SybilAPIClient.swift

@@ -1,4 +1,5 @@
 import Foundation
+import CryptoKit
 
 struct APIConfiguration: Sendable {
     var baseURL: URL
@@ -41,10 +42,11 @@ actor SybilAPIClient: SybilAPIClienting, AgentAPIClienting {
     }
 
     func agentDescriptor() async throws -> AgentDescriptor {
-        let value = try await request("/v1/agent", method: "GET", responseType: AgentDescriptor.self)
+        var value = try await request("/v1/agent", method: "GET", responseType: AgentDescriptor.self)
         guard value.type == "persistent-agent", value.protocol == "pi-room.v1" else {
             throw AgentFailure(message: "Unsupported Agent room protocol.")
         }
+        if configuration.authToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty != false { value.capabilities?.attachments = nil }
         return value
     }
 
@@ -72,6 +74,72 @@ actor SybilAPIClient: SybilAPIClienting, AgentAPIClienting {
         return receipt
     }
 
+    func agentSubmit(_ submission: AgentSubmission) async throws -> AgentReceipt {
+        if !submission.attachmentIDs.isEmpty {
+            guard let limits = try await agentDescriptor().capabilities?.attachments, limits.supported else { throw AgentAttachmentIssue.unavailable }
+            guard submission.attachmentIDs.count <= limits.countLimit else { throw AgentAttachmentIssue.local("Too many attachments for this Agent.", code: "attachment_limit_exceeded") }
+        }
+        let receipt = try await request("/v1/agent/messages", method: "POST", body: AnyEncodable(submission), responseType: AgentReceipt.self)
+        try receipt.validate(requestID: submission.requestId, attachmentIDs: submission.attachmentIDs)
+        return receipt
+    }
+
+    func agentUpload(file: AgentPreparedAttachment, uploadID: String) async throws -> AgentAttachment {
+        guard let limits = try await agentDescriptor().capabilities?.attachments, limits.supported else { throw AgentAttachmentIssue.unavailable }
+        let prepared = try AgentAttachmentPreparation.prepare(file.data, filename: file.filename, mimeType: file.mimeType, limits: limits)
+        let multipart = try AgentMultipart(file: prepared, uploadID: uploadID)
+        var request = try makeRequest(path: "/v1/agent/attachments", method: "POST", body: nil, acceptsSSE: false)
+        request.timeoutInterval = 120
+        request.setValue("multipart/form-data; boundary=\(multipart.boundary)", forHTTPHeaderField: "Content-Type")
+        request.httpBody = multipart.body
+        let (data, status, retryAfter) = try await attachmentBytes(request, maximum: 64 * 1024)
+        guard status == 200 || status == 201 else { throw AgentAttachmentIssue.response(data, status: status, retryAfter: retryAfter) }
+        struct UploadResponse: Decodable { var attachment: AgentAttachment }
+        guard let response = try? JSONDecoder().decode(UploadResponse.self, from: data) else {
+            throw AgentAttachmentIssue.local("Invalid attachment upload receipt. Retry to confirm.", code: "invalid_upstream_response")
+        }
+        let attachment = response.attachment
+        try attachment.validate()
+        guard attachment.filename == prepared.filename, attachment.mimeType == prepared.mimeType,
+              attachment.sizeBytes == prepared.data.count, attachment.sha256 == prepared.sha256 else {
+            throw AgentAttachmentIssue.local("The upload receipt does not match the selected file.", code: "invalid_upstream_response")
+        }
+        return attachment
+    }
+
+    func agentDownload(_ attachment: AgentAttachment) async throws -> Data {
+        try attachment.validate()
+        guard configuration.authToken?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false else { throw AgentAttachmentIssue.unavailable }
+        var request = try makeRequest(path: "/v1/agent/attachments", method: "GET", body: nil, acceptsSSE: false)
+        request.url = try configuration.agentAttachmentContentURL(id: attachment.id)
+        request.setValue("application/octet-stream", forHTTPHeaderField: "Accept")
+        let (data, status, retryAfter) = try await attachmentBytes(request, maximum: attachment.sizeBytes)
+        guard status == 200 else { throw AgentAttachmentIssue.response(data, status: status, retryAfter: retryAfter) }
+        guard data.count == attachment.sizeBytes,
+              SHA256.hash(data: data).map({ String(format: "%02x", $0) }).joined() == attachment.sha256 else {
+            throw AgentAttachmentIssue.local("The downloaded original failed its size or checksum check. Retry the download.", code: "invalid_upstream_response")
+        }
+        return data
+    }
+
+    private func attachmentBytes(_ request: URLRequest, maximum: Int) async throws -> (Data, Int, String?) {
+        let (stream, response) = try await session.bytes(for: request, delegate: AgentAttachmentRedirectPolicy())
+        defer { stream.task.cancel() }
+        guard let response = response as? HTTPURLResponse else { throw APIError.invalidResponse }
+        let success = (200...299).contains(response.statusCode)
+        let limit = success ? maximum : 64 * 1024
+        guard response.expectedContentLength <= Int64(limit) else {
+            throw AgentAttachmentIssue.local("The attachment response exceeds its size limit.", code: "invalid_upstream_response")
+        }
+        var data = Data()
+        for try await byte in stream {
+            try Task.checkCancellation()
+            guard data.count < limit else { throw AgentAttachmentIssue.local("The attachment response exceeds its size limit.", code: "invalid_upstream_response") }
+            data.append(byte)
+        }
+        return (data, response.statusCode, response.value(forHTTPHeaderField: "Retry-After"))
+    }
+
     func agentSocket(after: String) async throws -> any AgentSocket {
         let task = session.webSocketTask(with: try configuration.agentWebSocketURL())
         task.maximumMessageSize = 8 * 1024 * 1024
@@ -355,7 +423,7 @@ actor SybilAPIClient: SybilAPIClienting, AgentAPIClienting {
         let response: URLResponse
 
         do {
-            (data, response) = try await session.data(for: request)
+            (data, response) = try await session.data(for: request, delegate: path.hasPrefix("/v1/agent") ? AgentAttachmentRedirectPolicy() : nil)
         } catch {
             if let urlError = error as? URLError, urlError.code == .cancelled {
                 SybilLog.debug(
@@ -369,6 +437,10 @@ actor SybilAPIClient: SybilAPIClienting, AgentAPIClienting {
             throw wrapped
         }
 
+        if path.hasPrefix("/v1/agent"), let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode),
+           (try? JSONDecoder().decode(JSONValue.self, from: data))?.objectValue?["code"]?.stringValue != nil {
+            throw AgentAttachmentIssue.response(data, status: http.statusCode, retryAfter: http.value(forHTTPHeaderField: "Retry-After"))
+        }
         try validate(response: response, data: data)
 
         do {

ios/Packages/Sybil/Sources/Sybil/SybilAgentAttachmentDownloads.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+// At most two authenticated downloads per room. Cache only verified bytes, bounded to 16 MiB,
+// and replace the entire actor when API configuration changes. No credential-bearing disk cache.
+actor AgentAttachmentDownloads {
+    private var active = 0
+    private var invalidated = false
+    private var transfers: [UUID: Task<Data, any Error>] = [:]
+    private var waiters: [(UUID, CheckedContinuation<Void, any Error>)] = []
+    private var cache: [AgentAttachment: Data] = [:]
+    private var order: [AgentAttachment] = []
+    private var byteCount = 0
+
+    func data(for attachment: AgentAttachment, client: any AgentAPIClienting) async throws -> Data {
+        try Task.checkCancellation()
+        guard !invalidated else { throw CancellationError() }
+        if let value = cache[attachment] { return value }
+        try await acquire()
+        defer { release() }
+        try Task.checkCancellation()
+        if let value = cache[attachment] { return value }
+        guard !invalidated else { throw CancellationError() }
+        let id = UUID()
+        let transfer = Task { try await client.agentDownload(attachment) }
+        transfers[id] = transfer
+        defer { transfers[id] = nil }
+        let value = try await withTaskCancellationHandler { try await transfer.value } onCancel: { transfer.cancel() }
+        try Task.checkCancellation()
+        guard !invalidated else { throw CancellationError() }
+        while byteCount + value.count > 16 * 1024 * 1024, !order.isEmpty {
+            let oldest = order.removeFirst()
+            byteCount -= cache.removeValue(forKey: oldest)?.count ?? 0
+        }
+        if cache[attachment] == nil { cache[attachment] = value; order.append(attachment); byteCount += value.count }
+        return value
+    }
+    func invalidate() {
+        invalidated = true
+        transfers.values.forEach { $0.cancel() }
+        for waiter in waiters { waiter.1.resume(throwing: CancellationError()) }
+        waiters = []; cache = [:]; order = []; byteCount = 0
+    }
+    private func acquire() async throws {
+        guard !invalidated else { throw CancellationError() }
+        if active < 2 { active += 1; return }
+        let id = UUID()
+        try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, any Error>) in
+                if Task.isCancelled { continuation.resume(throwing: CancellationError()) }
+                else { waiters.append((id, continuation)) }
+            }
+        } onCancel: { Task { await self.cancel(id) } }
+    }
+    private func cancel(_ id: UUID) {
+        guard let index = waiters.firstIndex(where: { $0.0 == id }) else { return }
+        waiters.remove(at: index).1.resume(throwing: CancellationError())
+    }
+    private func release() {
+        if waiters.isEmpty { active -= 1 }
+        else { waiters.removeFirst().1.resume() }
+    }
+}

ios/Packages/Sybil/Sources/Sybil/SybilAgentAttachmentDraft.swift

@@ -0,0 +1,219 @@
+import CryptoKit
+import Foundation
+import Observation
+
+struct AgentDraftItem: Codable, Equatable, Identifiable, Sendable {
+    enum State: String, Codable, Sendable { case loading, uploading, ready, failed }
+    var id: String = UUID().uuidString // Stable multipart uploadId, including across relaunch.
+    var filename: String
+    var mimeType: String?
+    var sizeBytes: Int?
+    var state: State = .loading
+    var attachment: AgentAttachment?
+    var issue: AgentAttachmentIssue?
+}
+struct AgentDraftSnapshot: Codable, Sendable {
+    var caption = ""
+    var items: [AgentDraftItem] = []
+    var id: String? = nil // Optional for drafts saved before durable outbox handoff tracking.
+}
+struct AgentDraftStorage: Sendable {
+    var read: @Sendable () throws -> AgentDraftSnapshot
+    var write: @Sendable (AgentDraftSnapshot) throws -> Void
+    var stage: @Sendable (String, Data) throws -> Void
+    var bytes: @Sendable (String) throws -> Data
+    var remove: @Sendable (String) -> Void
+
+    static func file(baseURL: URL, root: URL = .applicationSupportDirectory) -> Self {
+        let key = SHA256.hash(data: Data(baseURL.absoluteString.utf8)).map { String(format: "%02x", $0) }.joined()
+        let directory = root.appendingPathComponent("AgentAttachmentDrafts/\(key)", isDirectory: true)
+        let manifest = directory.appendingPathComponent("draft.json")
+        let file: @Sendable (String) throws -> URL = { id in
+            guard UUID(uuidString: id) != nil else { throw AgentAttachmentIssue.local("Invalid staged upload identity.") }
+            return directory.appendingPathComponent(id + ".bytes")
+        }
+        let write: @Sendable (Data, URL) throws -> Void = { data, destination in
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            try data.write(to: destination, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])
+        }
+        return Self(read: {
+            guard FileManager.default.fileExists(atPath: manifest.path) else { return AgentDraftSnapshot() }
+            let data = try Data(contentsOf: manifest)
+            guard data.count <= 2 * 1024 * 1024 else { throw AgentAttachmentIssue.local("The saved attachment draft is too large.") }
+            let snapshot = try JSONDecoder().decode(AgentDraftSnapshot.self, from: data)
+            guard snapshot.items.count <= 8, Set(snapshot.items.map(\.id)).count == snapshot.items.count,
+                  snapshot.items.allSatisfy({ UUID(uuidString: $0.id) != nil }) else { throw AgentAttachmentIssue.local("The saved attachment draft is invalid.") }
+            return snapshot
+        }, write: { snapshot in
+            let data = try JSONEncoder().encode(snapshot)
+            guard data.count <= 2 * 1024 * 1024 else { throw AgentAttachmentIssue.local("The saved attachment draft is too large.") }
+            try write(data, manifest)
+        }, stage: { id, data in
+            guard data.count <= 8 * 1024 * 1024 else { throw AgentAttachmentIssue.local("The staged file exceeds the size limit.") }
+            try write(data, file(id))
+        }, bytes: { id in
+            let url = try file(id)
+            let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? Int.max
+            guard size <= 8 * 1024 * 1024 else { throw AgentAttachmentIssue.local("The staged file exceeds the size limit.") }
+            return try Data(contentsOf: url)
+        }, remove: { id in if let url = try? file(id) { try? FileManager.default.removeItem(at: url) } })
+    }
+}
+
+@MainActor @Observable
+final class AgentAttachmentDraft {
+    private(set) var id = UUID().uuidString
+    var caption = "" { didSet { save() } }
+    private(set) var items: [AgentDraftItem] = []
+    private(set) var capability: AgentAttachmentCapabilities?
+    private(set) var error: String?
+    private(set) var persistenceAvailable = true
+    @ObservationIgnored private var client: (any AgentAPIClienting)?
+    @ObservationIgnored private var storage: AgentDraftStorage?
+    @ObservationIgnored private var prepared: [String: AgentPreparedAttachment] = [:]
+    @ObservationIgnored private var loaders: [String: @Sendable () async throws -> AgentPreparedAttachment] = [:]
+    @ObservationIgnored private var worker: Task<Void, Never>?
+    @ObservationIgnored private var generation = UUID()
+    @ObservationIgnored private var restoring = false
+    @ObservationIgnored private var active = true
+    var supportsAttachments: Bool { capability?.supported == true && persistenceAvailable }
+    var ready: [AgentAttachment] { items.compactMap(\.attachment) }
+    var canSend: Bool {
+        caption.utf16.count <= 40_000 && (!caption.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || !items.isEmpty)
+            && (items.isEmpty || (supportsAttachments && items.allSatisfy { $0.state == .ready && $0.attachment != nil }))
+            && persistenceAvailable
+    }
+
+    func configure(client: any AgentAPIClienting, storage: AgentDraftStorage?) {
+        suspend()
+        self.client = client; self.storage = storage
+        prepared = [:]; loaders = [:]; capability = nil; error = nil; persistenceAvailable = true
+        restoring = true
+        defer { restoring = false; active = true }
+        do {
+            let saved = try storage?.read() ?? AgentDraftSnapshot()
+            id = saved.id ?? UUID().uuidString
+            caption = saved.caption
+            items = saved.items.map { item in
+                var item = item
+                if item.state != .ready {
+                    item.state = .failed
+                    item.issue = .local("Upload interrupted. Retry with the same upload ID. If selection did not finish, remove and select the file again.", code: "upload_interrupted")
+                }
+                return item
+            }
+        } catch {
+            caption = ""; items = []; persistenceAvailable = false
+            self.error = "Could not restore attachment draft: \(error.localizedDescription)"
+        }
+    }
+    func updateCapability(_ value: AgentAttachmentCapabilities?) {
+        capability = value?.supported == true ? value : nil
+        if capability == nil { suspend(); active = true }
+    }
+    func resume() { active = true; pump() }
+    func suspend() {
+        active = false; generation = UUID(); worker?.cancel(); worker = nil
+        for index in items.indices where items[index].state == .loading || items[index].state == .uploading {
+            items[index].state = .failed
+            items[index].issue = .local("Transfer interrupted. Retry to continue.", code: "upload_interrupted")
+        }
+        save()
+    }
+    @discardableResult
+    func add(filename: String, load: @escaping @Sendable () async throws -> AgentPreparedAttachment) -> String? {
+        guard supportsAttachments, let capability else { error = AgentAttachmentIssue.unavailable.localizedDescription; return nil }
+        guard items.count < capability.countLimit else { error = "You can attach up to \(capability.countLimit) files."; return nil }
+        let item = AgentDraftItem(filename: filename)
+        items.append(item); loaders[item.id] = load; error = nil
+        save(); pump()
+        return item.id
+    }
+    func remove(_ id: String) {
+        // Restart the serial worker; completion from the old generation can never reinsert a removed item.
+        let interrupted = items.filter { $0.state == .loading || $0.state == .uploading }.map(\.id)
+        generation = UUID(); worker?.cancel(); worker = nil
+        items.removeAll { $0.id == id }; loaders[id] = nil; prepared[id] = nil
+        save()
+        if persistenceAvailable { storage?.remove(id) }
+        for other in interrupted where other != id {
+            if let index = items.firstIndex(where: { $0.id == other }) { items[index].state = .loading }
+        }
+        pump()
+    }
+    func retry(_ id: String) {
+        guard supportsAttachments else { error = AgentAttachmentIssue.unavailable.localizedDescription; return }
+        guard let index = items.firstIndex(where: { $0.id == id }), items[index].state == .failed else { return }
+        items[index].state = .loading; items[index].issue = nil; error = nil
+        save(); pump()
+    }
+    func validateReady() throws -> [AgentAttachment] {
+        guard items.isEmpty || supportsAttachments else { throw AgentAttachmentIssue.unavailable }
+        guard items.allSatisfy({ $0.state == .ready && $0.attachment != nil }) else { throw AgentAttachmentIssue.local("Wait for every attachment to finish, or retry/remove failed files.") }
+        if let capability { try capability.validate(ready) }
+        return ready
+    }
+    @discardableResult func clearAfterSubmission() -> Bool {
+        guard persistenceAvailable else { return false }
+        let nextID = UUID().uuidString
+        do { try storage?.write(AgentDraftSnapshot(id: nextID)) }
+        catch {
+            persistenceAvailable = false
+            self.error = "Message is saved in the outbox, but its draft could not be cleared. Reconnect before retrying: \(error.localizedDescription)"
+            return false
+        }
+        let ids = items.map(\.id)
+        generation = UUID(); worker?.cancel(); worker = nil
+        restoring = true; caption = ""; items = []; id = nextID; restoring = false
+        prepared = [:]; loaders = [:]
+        ids.forEach { storage?.remove($0) }
+        return true
+    }
+    func save() {
+        guard !restoring, persistenceAvailable else { return }
+        do { try storage?.write(AgentDraftSnapshot(caption: caption, items: items, id: id)) }
+        catch { persistenceAvailable = false; self.error = "Could not save attachment draft: \(error.localizedDescription)" }
+    }
+    private func pump() {
+        guard active, supportsAttachments, let client, let limits = capability, worker == nil,
+              let item = items.first(where: { $0.state == .loading }) else { return }
+        let run = generation
+        worker = Task { [weak self] in
+            guard let self else { return }
+            defer { if self.generation == run { self.worker = nil; self.pump() } }
+            do {
+                let file: AgentPreparedAttachment
+                if let existing = self.prepared[item.id] { file = existing }
+                else if let mime = item.mimeType, let storage = self.storage {
+                    file = try AgentAttachmentPreparation.prepare(storage.bytes(item.id), filename: item.filename, mimeType: mime, limits: limits)
+                } else if let loader = self.loaders[item.id] { file = try await loader() }
+                else { throw AgentAttachmentIssue.local("Selection did not finish before the app closed. Remove this item and select it again.", code: "selection_unavailable") }
+                try Task.checkCancellation()
+                guard self.generation == run, let index = self.items.firstIndex(where: { $0.id == item.id }) else { return }
+                let otherBytes = self.items.filter { $0.id != item.id }.reduce(0) { $0 + ($1.sizeBytes ?? 0) }
+                guard otherBytes + file.data.count <= limits.totalLimit else { throw AgentAttachmentIssue.local("Attachments exceed the total message size limit.", code: "attachment_limit_exceeded") }
+                self.prepared[item.id] = file
+                try self.storage?.stage(item.id, file.data)
+                self.items[index].filename = file.filename; self.items[index].mimeType = file.mimeType
+                self.items[index].sizeBytes = file.data.count; self.items[index].state = .uploading
+                self.save()
+                guard self.persistenceAvailable else { throw AgentAttachmentIssue.local("Save failed. Reconnect before uploading.") }
+                let attachment = try await client.agentUpload(file: file, uploadID: item.id)
+                try attachment.validate()
+                guard attachment.filename == file.filename, attachment.mimeType == file.mimeType,
+                      attachment.sizeBytes == file.data.count, attachment.sha256 == file.sha256 else {
+                    throw AgentAttachmentIssue.local("Upload receipt does not match the original file. Retry to confirm.", code: "invalid_upstream_response")
+                }
+                try Task.checkCancellation()
+                guard self.generation == run, let index = self.items.firstIndex(where: { $0.id == item.id }) else { return }
+                self.items[index].attachment = attachment; self.items[index].state = .ready; self.items[index].issue = nil
+                self.save()
+                self.loaders[item.id] = nil; self.prepared[item.id] = nil
+                // Keep staged bytes until the message is durably handed to the outbox.
+            } catch {
+                guard self.generation == run, let index = self.items.firstIndex(where: { $0.id == item.id }) else { return }
+                self.items[index].state = .failed; self.items[index].issue = .wrapping(error); self.save()
+            }
+        }
+    }
+}

ios/Packages/Sybil/Sources/Sybil/SybilAgentAttachmentViews.swift

@@ -0,0 +1,239 @@
+import Foundation
+import ImageIO
+import PhotosUI
+import SwiftUI
+import UniformTypeIdentifiers
+import UIKit
+
+// FileTransferRepresentation keeps Photo Library imports file-backed and bounded while reading.
+// PhotosPicker does not expose the original PHAsset filename without broader library access.
+struct AgentPickedPhoto: Transferable, Sendable {
+    var data: Data
+    var filename: String?
+    var mimeType: String?
+    static var transferRepresentation: some TransferRepresentation {
+        FileRepresentation(importedContentType: .image) { received in
+            let url = received.file
+            let size = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? Int.max
+            guard size <= 32 * 1024 * 1024 else { throw AgentAttachmentIssue.local("This photo is too large to prepare. Select its original in Files.", code: "attachment_limit_exceeded") }
+            let handle = try FileHandle(forReadingFrom: url)
+            defer { try? handle.close() }
+            var data = Data()
+            while let chunk = try handle.read(upToCount: 64 * 1024), !chunk.isEmpty {
+                try Task.checkCancellation()
+                guard data.count + chunk.count <= 32 * 1024 * 1024 else {
+                    throw AgentAttachmentIssue.local("This photo is too large to prepare. Select its original in Files.", code: "attachment_limit_exceeded")
+                }
+                data.append(chunk)
+            }
+            let type = CGImageSourceCreateWithData(data as CFData, nil).flatMap { CGImageSourceGetType($0) }.flatMap { UTType($0 as String) }
+            return Self(data: data, filename: url.lastPathComponent.isEmpty ? nil : url.lastPathComponent, mimeType: type?.preferredMIMEType)
+        }
+    }
+}
+
+struct AgentAttachmentComposer: View {
+    @Bindable var room: SybilAgentRoom
+    @State private var modalID = UUID()
+    @State private var pickerSession: UUID?
+    @State private var showChoices = false
+    @State private var showFiles = false
+    @State private var showPhotos = false
+    @State private var photos: [PhotosPickerItem] = []
+    private var modal: Bool { showChoices || showFiles || showPhotos }
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            if !room.attachmentDraft.items.isEmpty {
+                ScrollView(.horizontal) {
+                    HStack(alignment: .top, spacing: 8) {
+                        ForEach(room.attachmentDraft.items) { item in
+                            VStack(alignment: .leading, spacing: 6) {
+                                HStack {
+                                    Text(item.filename).lineLimit(1)
+                                    Button { room.attachmentDraft.remove(item.id) } label: { Image(systemName: "xmark.circle") }
+                                        .accessibilityLabel("Remove \(item.filename)")
+                                }
+                                if let attachment = item.attachment {
+                                    AgentAttachmentDetails(attachment: attachment)
+                                } else {
+                                    Text(item.state == .uploading ? "Uploading…" : item.state == .loading ? "Loading…" : "Upload failed")
+                                        .foregroundStyle(SybilTheme.textMuted)
+                                    if item.state == .uploading || item.state == .loading { ProgressView().controlSize(.small) }
+                                }
+                                if let issue = item.issue {
+                                    Text(issue.localizedDescription).foregroundStyle(SybilTheme.danger).fixedSize(horizontal: false, vertical: true)
+                                    Button("Retry upload") { room.attachmentDraft.retry(item.id) }
+                                        .accessibilityIdentifier("agent-upload-retry")
+                                }
+                            }
+                            .font(.sybil(.caption)).padding(10).frame(width: 260, alignment: .leading)
+                            .background(SybilTheme.surfaceStrong, in: RoundedRectangle(cornerRadius: 12))
+                        }
+                    }
+                }.frame(maxHeight: 190)
+            }
+            if let error = room.attachmentDraft.error {
+                Text(error).font(.sybil(.caption)).foregroundStyle(SybilTheme.danger)
+            }
+            if !room.attachmentDraft.supportsAttachments && !room.attachmentDraft.items.isEmpty {
+                Text(AgentAttachmentIssue.unavailable.localizedDescription).font(.sybil(.caption)).foregroundStyle(SybilTheme.danger)
+            }
+            if room.attachmentDraft.supportsAttachments {
+                Button { pickerSession = room.attachmentSessionID; showChoices = true } label: { Label("Attach", systemImage: "paperclip") }
+                    .font(.sybil(.caption, weight: .semibold)).accessibilityIdentifier("agent-attach")
+                    .disabled(room.attachmentDraft.items.count >= (room.attachmentDraft.capability?.countLimit ?? 0))
+            }
+        }
+        .confirmationDialog("Add attachment", isPresented: $showChoices) {
+            Button("Photo Library") { showPhotos = true }
+            Button("Files") { showFiles = true }
+            Button("Cancel", role: .cancel) {}
+        }
+        .photosPicker(isPresented: $showPhotos, selection: $photos,
+                      maxSelectionCount: max(1, (room.attachmentDraft.capability?.countLimit ?? 1) - room.attachmentDraft.items.count),
+                      selectionBehavior: .ordered, matching: .images)
+        .fileImporter(isPresented: $showFiles, allowedContentTypes: [.item], allowsMultipleSelection: true) { result in
+            guard pickerSession == room.attachmentSessionID, room.isSelected, let limits = room.attachmentDraft.capability else { return }
+            switch result {
+            case let .success(urls):
+                for url in urls {
+                    room.attachmentDraft.add(filename: url.lastPathComponent) {
+                        try await AgentAttachmentPreparation.offMain { try AgentAttachmentPreparation.file(url, limits: limits) }
+                    }
+                }
+            case let .failure(error):
+                if (error as NSError).code != NSUserCancelledError {
+                    room.attachmentDraft.add(filename: "File selection") { throw AgentAttachmentIssue.wrapping(error) }
+                }
+            }
+        }
+        .onChange(of: photos) { _, selected in
+            guard pickerSession == room.attachmentSessionID, room.isSelected, let limits = room.attachmentDraft.capability else { photos = []; return }
+            for item in selected {
+                room.attachmentDraft.add(filename: "Photo") {
+                    guard let photo = try await item.loadTransferable(type: AgentPickedPhoto.self) else {
+                        throw AgentAttachmentIssue.local("The selected photo could not be loaded.")
+                    }
+                    return try await AgentAttachmentPreparation.offMain {
+                        try AgentAttachmentPreparation.photo(photo.data, filename: photo.filename, mimeType: photo.mimeType, limits: limits)
+                    }
+                }
+            }
+            photos = []
+        }
+        .onChange(of: room.attachmentSessionID) { _, _ in showChoices = false; showFiles = false; showPhotos = false; photos = []; pickerSession = nil }
+        .onChange(of: modal) { _, value in room.setAttachmentModal(modalID, presented: value) }
+        .onDisappear { room.setAttachmentModal(modalID, presented: false) }
+    }
+}
+
+struct AgentAttachmentDetails: View {
+    var attachment: AgentAttachment
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Text("\(attachment.mimeType) · \(ByteCountFormatter.string(fromByteCount: Int64(attachment.sizeBytes), countStyle: .file))")
+                .foregroundStyle(SybilTheme.textMuted)
+            if let path = attachment.workspacePath {
+                Button {
+                    UIPasteboard.general.string = path
+                } label: {
+                    Label(path, systemImage: "doc.on.doc").lineLimit(2).multilineTextAlignment(.leading)
+                }
+                .buttonStyle(.plain).accessibilityLabel("Copy workspace path: \(path)")
+            }
+        }.font(.sybil(.caption2))
+    }
+}
+
+struct AgentAttachmentCard: View {
+    var attachment: AgentAttachment
+    var room: SybilAgentRoom
+    @Environment(\.scenePhase) private var scenePhase
+    @State private var image: UIImage?
+    @State private var text: String?
+    @State private var issue: String?
+    @State private var loading = false
+    @State private var wantsDownload = false
+    @State private var revision = 0
+    @State private var exportURL: URL?
+    @State private var showShare = false
+    @State private var modalID = UUID()
+    private var loadKey: String { "\(room.attachmentSessionID):\(attachment.id):\(attachment.sha256):\(revision):\(scenePhase == .active)" }
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text(attachment.filename).font(.sybil(.footnote, weight: .medium)).lineLimit(2)
+            AgentAttachmentDetails(attachment: attachment)
+            if attachment.kind == .image {
+                ZStack {
+                    SybilTheme.surface
+                    if let image { Image(uiImage: image).resizable().scaledToFit() }
+                    else { Image(systemName: "photo").foregroundStyle(SybilTheme.textMuted) }
+                }.frame(height: 180).clipped()
+            }
+            if let text {
+                Text(text).font(.system(.caption, design: .monospaced)).lineLimit(6)
+                    .frame(height: 100, alignment: .topLeading).textSelection(.enabled)
+            }
+            if loading { ProgressView("Loading original…").font(.sybil(.caption)) }
+            if let issue { Text(issue).font(.sybil(.caption)).foregroundStyle(SybilTheme.danger) }
+            HStack {
+                if exportURL != nil {
+                    Button { showShare = true } label: { Label("Save or share original", systemImage: "square.and.arrow.up") }
+                } else if !loading {
+                    Button(issue == nil ? "Download original" : "Retry download") { wantsDownload = true; revision += 1 }
+                        .accessibilityIdentifier("agent-download")
+                }
+                if loading { Button("Cancel") { wantsDownload = false; revision += 1 } }
+            }.font(.sybil(.caption))
+        }
+        .padding(12).frame(maxWidth: 340, alignment: .leading)
+        .background(SybilTheme.surfaceStrong, in: RoundedRectangle(cornerRadius: 12))
+        .task(id: loadKey) {
+            // Each view owns its transfer; configuration and foreground changes cancel it.
+            guard scenePhase == .active, wantsDownload || (attachment.kind == .image && revision == 0) else { loading = false; return }
+            loading = true; issue = nil
+            let session = room.attachmentSessionID
+            do {
+                let data = try await room.downloadAttachment(attachment)
+                try Task.checkCancellation()
+                guard session == room.attachmentSessionID else { return }
+                if attachment.kind == .image {
+                    let bitmap = try await AgentAttachmentPreparation.offMain { try AgentAttachmentPreparation.raster(data, mime: attachment.mimeType) }
+                    try Task.checkCancellation()
+                    image = UIImage(cgImage: bitmap)
+                } else if attachment.kind == .text, let decoded = String(data: data, encoding: .utf8), !decoded.contains("\u{0000}") {
+                    text = String(decoded.prefix(1000)) // Plain text only, including HTML/SVG.
+                }
+                if wantsDownload {
+                    let directory = FileManager.default.temporaryDirectory.appendingPathComponent("AgentOriginal-" + UUID().uuidString, isDirectory: true)
+                    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+                    let destination = directory.appendingPathComponent(try AgentAttachmentPreparation.filename(attachment.filename))
+                    try data.write(to: destination, options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication])
+                    exportURL = destination
+                }
+                loading = false
+            } catch {
+                if !Task.isCancelled { issue = error.localizedDescription; loading = false }
+            }
+        }
+        .sheet(isPresented: $showShare) {
+            if let exportURL { AgentOriginalShare(url: exportURL) }
+        }
+        .onChange(of: showShare) { _, value in room.setAttachmentModal(modalID, presented: value) }
+        .onChange(of: room.attachmentSessionID) { _, _ in showShare = false; reset() }
+        .onDisappear { room.setAttachmentModal(modalID, presented: false); reset() }
+    }
+    private func reset() {
+        image = nil; text = nil
+        if let exportURL { try? FileManager.default.removeItem(at: exportURL.deletingLastPathComponent()) }
+        exportURL = nil
+    }
+}
+
+private struct AgentOriginalShare: UIViewControllerRepresentable {
+    var url: URL
+    func makeUIViewController(context: Context) -> UIActivityViewController {
+        UIActivityViewController(activityItems: [url], applicationActivities: nil)
+    }
+    func updateUIViewController(_ controller: UIActivityViewController, context: Context) {}
+}

ios/Packages/Sybil/Sources/Sybil/SybilAgentAttachments.swift

@@ -0,0 +1,269 @@
+import CryptoKit
+import Foundation
+import ImageIO
+import UniformTypeIdentifiers
+import UIKit
+
+struct AgentAttachmentCapabilities: Codable, Equatable, Sendable {
+    var version: Int
+    var maxCount: Int
+    var maxTotalBytes: Int
+    var maxImageBytes: Int
+    var maxFileBytes: Int
+    var imageMimeTypes: [String]
+    var maxImagePixels: Int
+    var maxImageDimension: Int
+    var quotaBytes: Int64? = nil
+    var usedBytes: Int64? = nil
+    var remainingBytes: Int64? = nil
+    var maxConcurrentUploads: Int? = nil
+    var maxConcurrentDecodes: Int? = nil
+
+    var supported: Bool {
+        version == 1 && maxCount > 0 && maxTotalBytes > 0 && maxImageBytes > 0 && maxFileBytes > 0
+            && maxImagePixels > 0 && maxImageDimension > 0
+    }
+    var countLimit: Int { min(maxCount, 8) }
+    var totalLimit: Int { min(maxTotalBytes, 32 * 1024 * 1024) }
+    var imageLimit: Int { min(maxImageBytes, 6 * 1024 * 1024) }
+    var fileLimit: Int { min(maxFileBytes, 8 * 1024 * 1024) }
+    var pixelLimit: Int { min(maxImagePixels, 50_000_000) }
+    var dimensionLimit: Int { min(maxImageDimension, 16_384) }
+    func validate(_ attachments: [AgentAttachment]) throws {
+        guard supported else { throw AgentAttachmentIssue.unavailable }
+        for attachment in attachments { try attachment.validate() }
+        guard attachments.count <= countLimit, attachments.reduce(0, { $0 + $1.sizeBytes }) <= totalLimit else {
+            throw AgentAttachmentIssue.local("Attachments exceed the advertised message limit.", code: "attachment_limit_exceeded")
+        }
+        for attachment in attachments {
+            guard attachment.sizeBytes <= (attachment.kind == .image ? imageLimit : fileLimit),
+                  attachment.kind != .image || imageMimeTypes.contains(attachment.mimeType) else {
+                throw AgentAttachmentIssue.local("An attachment exceeds the current Agent limits or uses an unavailable image format.", code: "attachment_limit_exceeded")
+            }
+        }
+    }
+}
+
+struct AgentCapabilities: Decodable, Sendable {
+    var attachments: AgentAttachmentCapabilities?
+    init(attachments: AgentAttachmentCapabilities? = nil) { self.attachments = attachments }
+    private enum CodingKeys: String, CodingKey { case attachments }
+    init(from decoder: Decoder) throws {
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        // Unknown versions or malformed future capabilities must not break text chat.
+        attachments = try? values.decode(AgentAttachmentCapabilities.self, forKey: .attachments)
+    }
+}
+
+struct AgentAttachment: Codable, Hashable, Identifiable, Sendable {
+    enum Kind: String, Codable, Sendable { case image, text, file }
+    var id: String
+    var kind: Kind
+    var filename: String
+    var mimeType: String
+    var sizeBytes: Int
+    var sha256: String
+    var workspacePath: String? = nil
+
+    func validate() throws {
+        guard !id.isEmpty, id.utf8.count <= 1024, !id.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains),
+              try AgentAttachmentPreparation.filename(filename) == filename,
+              sizeBytes >= 0, sizeBytes <= 8 * 1024 * 1024,
+              sha256.count == 64, sha256.utf8.allSatisfy({ (48...57).contains($0) || (97...102).contains($0) }),
+              try AgentAttachmentPreparation.mime(mimeType) == mimeType else {
+            throw AgentAttachmentIssue.local("The Agent returned an invalid attachment descriptor.", code: "invalid_upstream_response")
+        }
+        guard (kind == .image) == AgentAttachmentPreparation.nativeMIMEs.contains(mimeType),
+              kind != .image || sizeBytes <= 6 * 1024 * 1024 else {
+            throw AgentAttachmentIssue.local("Invalid image attachment descriptor.", code: "invalid_upstream_response")
+        }
+        if let workspacePath {
+            guard workspacePath.hasPrefix("/"), !workspacePath.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) else {
+                throw AgentAttachmentIssue.local("The Agent returned an invalid workspace path.", code: "invalid_upstream_response")
+            }
+        }
+    }
+    var metadataValue: JSONValue {
+        // All stored fields are JSON-compatible; this also keeps optional future fields separate from ChatAttachment.
+        (try? JSONDecoder().decode(JSONValue.self, from: JSONEncoder().encode(self))) ?? .null
+    }
+}
+
+extension Message {
+    var agentAttachments: [AgentAttachment] {
+        guard let entries = metadata?.objectValue?["agentAttachments"]?.arrayValue else { return [] }
+        return entries.compactMap {
+            guard let data = try? JSONEncoder().encode($0),
+                  let attachment = try? JSONDecoder().decode(AgentAttachment.self, from: data),
+                  (try? attachment.validate()) != nil else { return nil }
+            return attachment
+        }
+    }
+}
+
+struct AgentSubmission: Encodable, Sendable {
+    struct Reference: Encodable, Sendable { let id: String }
+    let requestId: String
+    let content: String
+    let attachments: [Reference]?
+    init(content: String, requestID: String, attachments: [AgentAttachment] = []) throws {
+        guard !requestID.isEmpty, requestID.utf16.count <= 256, content.utf16.count <= 40_000,
+              !content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || !attachments.isEmpty,
+              attachments.count <= 8, Set(attachments.map(\.id)).count == attachments.count else {
+            throw AgentAttachmentIssue.local("Enter a message of at most 40,000 characters or attach files.", code: "invalid_attachment")
+        }
+        for attachment in attachments { try attachment.validate() }
+        guard attachments.reduce(0, { $0 + $1.sizeBytes }) <= 32 * 1024 * 1024 else {
+            throw AgentAttachmentIssue.local("Attachments exceed the total message size limit.", code: "attachment_limit_exceeded")
+        }
+        self.content = content; requestId = requestID
+        self.attachments = attachments.isEmpty ? nil : attachments.map { Reference(id: $0.id) }
+    }
+    var attachmentIDs: [String] { attachments?.map(\.id) ?? [] }
+}
+
+struct AgentAttachmentIssue: Error, LocalizedError, Codable, Equatable, Sendable {
+    var message: String
+    var code: String
+    var statusCode: Int?
+    // Preserve additive quota information without inventing field names.
+    var details: [String: JSONValue] = [:]
+    var retryAfter: String? = nil
+    var errorDescription: String? {
+        var result = "\(message) [\(code)]"
+        if code == "attachment_quota_exceeded" {
+            let numbers = ["requiredBytes", "remainingBytes", "quotaBytes"].compactMap { key -> String? in
+                guard let number = details[key]?.numberValue, number.isFinite, number >= 0, number < Double(Int64.max) else { return nil }
+                return "\(key): \(ByteCountFormatter.string(fromByteCount: Int64(number), countStyle: .file))"
+            }
+            if !numbers.isEmpty { result += " " + numbers.joined(separator: ", ") }
+        }
+        if let retryAfter { result += " Retry-After: \(retryAfter)." }
+        return result
+    }
+    static func local(_ message: String, code: String = "invalid_attachment") -> Self { Self(message: message, code: code) }
+    static let unavailable = Self.local("Attachments are unavailable on this Agent. Reconnect to check support, or remove the files to send text.", code: "attachments_unavailable")
+    static func wrapping(_ error: any Error) -> Self {
+        error as? Self ?? .local(error.localizedDescription, code: "attachment_transfer_failed")
+    }
+    static func response(_ data: Data, status: Int, retryAfter: String? = nil) -> Self {
+        let fields = (try? JSONDecoder().decode(JSONValue.self, from: data))?.objectValue ?? [:]
+        return Self(message: fields["message"]?.stringValue ?? fields["error"]?.stringValue ?? "Attachment request failed (HTTP \(status)).",
+                    code: fields["code"]?.stringValue ?? "attachment_request_failed", statusCode: status, details: fields, retryAfter: retryAfter)
+    }
+}
+
+struct AgentPreparedAttachment: Sendable {
+    var filename: String
+    var mimeType: String
+    var data: Data
+    var sha256: String { SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() }
+}
+
+enum AgentAttachmentPreparation {
+    static func offMain<T: Sendable>(_ operation: @escaping @Sendable () throws -> T) async throws -> T {
+        let task = Task.detached(operation: operation)
+        return try await withTaskCancellationHandler { try await task.value } onCancel: { task.cancel() }
+    }
+    static let nativeMIMEs: Set<String> = ["image/png", "image/jpeg", "image/gif", "image/webp"]
+    static func filename(_ value: String) throws -> String {
+        let value = value.precomposedStringWithCanonicalMapping
+        guard !value.isEmpty, value.utf8.count <= 255, value != ".", value != "..",
+              !value.contains("/"), !value.contains("\\"),
+              !value.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains) else {
+            throw AgentAttachmentIssue.local("The filename must be a safe basename of 1–255 UTF-8 bytes.")
+        }
+        return value
+    }
+    static func mime(_ value: String) throws -> String {
+        let value = value.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)
+        let parts = value.split(separator: "/", omittingEmptySubsequences: false)
+        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789!#$%&'*+-.^_`|~")
+        guard parts.count == 2, parts.allSatisfy({ !$0.isEmpty && $0.unicodeScalars.allSatisfy(allowed.contains) }), value.utf8.count <= 255 else {
+            throw AgentAttachmentIssue.local("The selected file has an invalid media type.")
+        }
+        return value
+    }
+    static func file(_ url: URL, limits: AgentAttachmentCapabilities) throws -> AgentPreparedAttachment {
+        let accessed = url.startAccessingSecurityScopedResource()
+        defer { if accessed { url.stopAccessingSecurityScopedResource() } }
+        let name = try filename(url.lastPathComponent)
+        let type = (try? url.resourceValues(forKeys: [.contentTypeKey]))?.contentType ?? UTType(filenameExtension: url.pathExtension)
+        let media = try mime(type?.preferredMIMEType ?? "application/octet-stream")
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        var data = Data()
+        while let chunk = try handle.read(upToCount: 64 * 1024), !chunk.isEmpty {
+            try Task.checkCancellation()
+            guard data.count + chunk.count <= (nativeMIMEs.contains(media) ? limits.imageLimit : limits.fileLimit) else {
+                throw AgentAttachmentIssue.local("\(name) exceeds the file size limit.", code: "attachment_limit_exceeded")
+            }
+            data.append(chunk)
+        }
+        return try prepare(data, filename: name, mimeType: media, limits: limits)
+    }
+    static func prepare(_ data: Data, filename name: String, mimeType: String, limits: AgentAttachmentCapabilities) throws -> AgentPreparedAttachment {
+        guard limits.supported else { throw AgentAttachmentIssue.unavailable }
+        let name = try filename(name), media = try mime(mimeType)
+        guard data.count <= (nativeMIMEs.contains(media) ? limits.imageLimit : limits.fileLimit) else { throw AgentAttachmentIssue.local("\(name) exceeds the file size limit.", code: "attachment_limit_exceeded") }
+        if nativeMIMEs.contains(media) {
+            guard limits.imageMimeTypes.contains(media), data.count <= limits.imageLimit else {
+                throw AgentAttachmentIssue.local("\(name) exceeds the image limit or uses an unavailable image format.", code: "attachment_limit_exceeded")
+            }
+            _ = try raster(data, mime: media, pixels: limits.pixelLimit, dimension: limits.dimensionLimit)
+        }
+        return AgentPreparedAttachment(filename: name, mimeType: media, data: data)
+    }
+    static func raster(_ data: Data, mime: String, pixels: Int = 50_000_000, dimension: Int = 16_384) throws -> CGImage {
+        guard nativeMIMEs.contains(mime), let source = CGImageSourceCreateWithData(data as CFData, nil),
+              let type = CGImageSourceGetType(source), UTType(type as String)?.preferredMIMEType == mime,
+              CGImageSourceGetStatus(source) == .statusComplete,
+              let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any],
+              let width = properties[kCGImagePropertyPixelWidth] as? Int, let height = properties[kCGImagePropertyPixelHeight] as? Int,
+              width > 0, height > 0, width <= dimension, height <= dimension, width <= pixels / height,
+              let image = CGImageSourceCreateThumbnailAtIndex(source, 0, [kCGImageSourceCreateThumbnailFromImageAlways: true,
+                    kCGImageSourceThumbnailMaxPixelSize: 600, kCGImageSourceCreateThumbnailWithTransform: true] as CFDictionary) else {
+            throw AgentAttachmentIssue.local("The image is invalid, has a mismatched media type, or exceeds the dimension/pixel limit.", code: "invalid_image")
+        }
+        return image
+    }
+    static func photo(_ data: Data, filename originalName: String?, mimeType: String?, limits: AgentAttachmentCapabilities) throws -> AgentPreparedAttachment {
+        let media = mimeType ?? "application/octet-stream"
+        if nativeMIMEs.contains(media) {
+            return try prepare(data, filename: originalName ?? "photo.\(UTType(mimeType: media)?.preferredFilenameExtension ?? "jpg")", mimeType: media, limits: limits)
+        }
+        // Photo Library is an explicit visual-input selection. Convert HEIC/HEIF with bounded decoding.
+        guard let source = CGImageSourceCreateWithData(data as CFData, nil), let sourceType = CGImageSourceGetType(source),
+              ["public.heic", "public.heif"].contains(sourceType as String), limits.imageMimeTypes.contains("image/jpeg"),
+              let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any],
+              let width = properties[kCGImagePropertyPixelWidth] as? Int, let height = properties[kCGImagePropertyPixelHeight] as? Int,
+              width > 0, height > 0, width <= limits.dimensionLimit, height <= limits.dimensionLimit, width <= limits.pixelLimit / height,
+              let image = CGImageSourceCreateThumbnailAtIndex(source, 0, [kCGImageSourceCreateThumbnailFromImageAlways: true,
+                    kCGImageSourceThumbnailMaxPixelSize: min(2000, limits.dimensionLimit), kCGImageSourceCreateThumbnailWithTransform: true] as CFDictionary),
+              let jpeg = UIImage(cgImage: image).jpegData(compressionQuality: 0.88) else {
+            throw AgentAttachmentIssue.local("This photo could not be prepared as a supported image. Select its original in Files to upload it as a file.", code: "invalid_image")
+        }
+        let safe = try filename(originalName ?? "photo.heic")
+        let stem = (safe as NSString).deletingPathExtension
+        return try prepare(jpeg, filename: stem + ".jpg", mimeType: "image/jpeg", limits: limits)
+    }
+}
+
+struct AgentMultipart: Sendable {
+    let boundary: String
+    let body: Data
+    init(file: AgentPreparedAttachment, uploadID: String) throws {
+        guard UUID(uuidString: uploadID) != nil else { throw AgentAttachmentIssue.local("Invalid upload identity.") }
+        let name = try AgentAttachmentPreparation.filename(file.filename)
+        let media = try AgentAttachmentPreparation.mime(file.mimeType)
+        var boundary: String
+        repeat { boundary = "Sybil-" + UUID().uuidString } while file.data.range(of: Data(boundary.utf8)) != nil
+        self.boundary = boundary
+        let quoted = name.replacingOccurrences(of: "\"", with: "\\\"")
+        var bytes = Data("--\(boundary)\r\nContent-Disposition: form-data; name=\"uploadId\"\r\n\r\n\(uploadID)\r\n--\(boundary)\r\nContent-Disposition: form-data; name=\"file\"; filename=\"\(quoted)\"\r\nContent-Type: \(media)\r\n\r\n".utf8)
+        bytes.append(file.data)
+        bytes.append(Data("\r\n--\(boundary)--\r\n".utf8))
+        guard bytes.count <= 8 * 1024 * 1024 + 64 * 1024 else { throw AgentAttachmentIssue.local("The upload exceeds the request size limit.", code: "attachment_limit_exceeded") }
+        body = bytes
+    }
+}

ios/Packages/Sybil/Sources/Sybil/SybilAgentModels.swift

@@ -53,6 +53,7 @@ struct AgentDescriptor: Decodable, Sendable {
     var `protocol`: String
     var activity: AgentActivity
     var websocket: String
+    var capabilities: AgentCapabilities? = nil
 }
 struct AgentPage: Codable, Sendable {
     var conversationId: String
@@ -77,12 +78,16 @@ struct AgentReceipt: Codable, Sendable {
     var id: Int64
     var status: String
     var messageId: String
-    func validate(requestID: String) throws {
+    var attachmentIds: [String]? = nil
+    func validate(requestID: String, attachmentIDs: [String] = []) throws {
         guard id > 0, id <= 9_007_199_254_740_991,
               ["queued", "placed", "done", "unanswered"].contains(status),
               messageId == "inbound:sybil:\(requestID)" else {
             throw AgentFailure(message: "Invalid Agent receipt. Retry to confirm delivery.")
         }
+        if !attachmentIDs.isEmpty, attachmentIds != attachmentIDs {
+            throw AgentAttachmentIssue.local("Agent receipt did not confirm the exact ordered attachments. Retry this message to confirm delivery.", code: "invalid_upstream_response")
+        }
     }
 }
 
@@ -203,6 +208,23 @@ struct AgentRoomState: Equatable, Sendable {
     }
 }
 
+// Filter only the transcript projection, before windowing. Keep the room's raw
+// messages and cursors intact for upserts, replay, unread state and activity.
+struct AgentTranscript {
+    let messages: [Message]
+    let startIndex: Int
+    var displayed: [Message] { Array(messages.dropFirst(startIndex)) }
+
+    init(messages: [Message], startID: String? = nil, limit: Int = 100) {
+        let visible = messages.filter {
+            $0.role != .tool && $0.metadata?.objectValue?["kind"]?.stringValue != "tool_call"
+        }
+        self.messages = visible
+        startIndex = startID.flatMap { id in visible.firstIndex(where: { $0.id == id }) }
+            ?? max(0, visible.count - limit)
+    }
+}
+
 // The transcript latch is independent of the truthful sidebar/worker activity.
 struct AgentPresentation {
     private(set) var suppressed = false

ios/Packages/Sybil/Sources/Sybil/SybilAgentOutbox.swift

@@ -9,10 +9,13 @@ struct AgentOutboxRow: Codable, Equatable, Sendable {
     var seenOnServer = false
     var confirmed = false
     var error: String?
+    var attachments: [AgentAttachment]? = nil // Optional for legacy text-only outboxes.
+    var draftID: String? = nil // Recovers a crash between outbox persistence and clearing the composer.
     var id: String { "inbound:sybil:\(requestID)" }
     var message: Message {
         var info: [String: JSONValue] = ["kind": .string("message"), "status": .string(status), "requestId": .string(requestID)]
         if let error { info["error"] = .string(error) }
+        if let attachments, !attachments.isEmpty { info["agentAttachments"] = .array(attachments.map(\.metadataValue)) }
         return Message(id: id, createdAt: createdAt, role: .user, content: content, metadata: .object(info))
     }
 }

ios/Packages/Sybil/Sources/Sybil/SybilAgentRoom.swift

@@ -16,12 +16,23 @@ final class SybilAgentRoom {
     private(set) var error: String?
     private(set) var isLoading = false
     private(set) var outbox: [AgentOutboxRow] = []
-    var composer = ""
+    let attachmentDraft = AgentAttachmentDraft()
+    private(set) var attachmentSessionID = UUID()
+    private var attachmentModals: Set<UUID> = []
+    var isAttachmentModalPresented: Bool { !attachmentModals.isEmpty }
+    func setAttachmentModal(_ id: UUID, presented: Bool) {
+        if presented { attachmentModals.insert(id) } else { attachmentModals.remove(id) }
+    }
+    var composer: String {
+        get { attachmentDraft.caption }
+        set { attachmentDraft.caption = newValue }
+    }
     var isObscured = false
     var isModalPresented = false
     var isSelected = false
     private(set) var isActive = true
 
+    @ObservationIgnored private var attachmentDownloads = AgentAttachmentDownloads()
     @ObservationIgnored private var client: (any AgentAPIClienting)?
     @ObservationIgnored private var storage: AgentOutboxStorage?
     @ObservationIgnored private var storageReadable = true
@@ -56,6 +67,10 @@ final class SybilAgentRoom {
                 messages[index].createdAt = row.createdAt
                 if !row.confirmed {
                     var info = messages[index].metadata?.objectValue ?? [:]
+                    if let attachments = row.attachments, messages[index].agentAttachments.map(\.id) != attachments.map(\.id) {
+                        info["agentAttachments"] = .array(attachments.map(\.metadataValue))
+                        messages[index].content = row.content
+                    }
                     info["status"] = .string(row.status)
                     if let error = row.error { info["error"] = .string(error) }
                     messages[index].metadata = .object(info)
@@ -65,12 +80,17 @@ final class SybilAgentRoom {
         return AgentRoomState.merge([], messages)
     }
 
-    func configure(client: any AgentAPIClienting, storage: AgentOutboxStorage) {
+    func configure(client: any AgentAPIClienting, storage: AgentOutboxStorage, draftStorage: AgentDraftStorage? = nil) {
         stop()
         self.client = client
         self.storage = storage
+        attachmentSessionID = UUID()
+        let oldDownloads = attachmentDownloads
+        Task { await oldDownloads.invalidate() }
+        attachmentDownloads = AgentAttachmentDownloads()
+        attachmentDraft.configure(client: client, storage: draftStorage)
         pending = AgentRoomState(); snapshot = Snapshot(); presenter = AgentPresentation()
-        desiredRead = "0"; acknowledgedRead = "0"; hasLoaded = false; composer = ""
+        desiredRead = "0"; acknowledgedRead = "0"; hasLoaded = false
         error = nil; storageReadable = true
         do {
             outbox = try storage.read().map { row in
@@ -81,6 +101,9 @@ final class SybilAgentRoom {
                 }
                 return restored
             }
+            if outbox.contains(where: { $0.draftID == attachmentDraft.id }) {
+                attachmentDraft.clearAfterSubmission()
+            }
         } catch {
             outbox = []; storageReadable = false
             self.error = "Could not restore pending messages: \(error.localizedDescription)"
@@ -91,9 +114,15 @@ final class SybilAgentRoom {
     func disconnect() {
         stop()
         client = nil
+        attachmentDraft.updateCapability(nil)
+        attachmentSessionID = UUID()
+        let oldDownloads = attachmentDownloads
+        Task { await oldDownloads.invalidate() }
+        attachmentDownloads = AgentAttachmentDownloads()
     }
 
     func stop() {
+        attachmentDraft.suspend()
         generation = UUID()
         connectionTask?.cancel(); connectionTask = nil
         maintenanceTask?.cancel(); maintenanceTask = nil
@@ -117,7 +146,7 @@ final class SybilAgentRoom {
     func setActive(_ active: Bool) {
         guard isActive != active else { return }
         isActive = active
-        if active { start() }
+        if active { attachmentDraft.resume(); start() }
         else {
             // Publish successfully merged input before cancelling; replay resumes here.
             flush()
@@ -151,6 +180,8 @@ final class SybilAgentRoom {
                 do {
                     let descriptor = try await client.agentDescriptor()
                     guard self.generation == run else { return }
+                    self.attachmentDraft.updateCapability(descriptor.capabilities?.attachments)
+                    self.attachmentDraft.resume()
                     try self.receive(.activity(descriptor.id, descriptor.activity), replay: !self.hasLoaded)
                     try await self.refreshRead(client: client, run: run)
                     try await self.catchUp(client: client, run: run, replay: !self.hasLoaded)
@@ -176,7 +207,11 @@ final class SybilAgentRoom {
                     guard self.generation == run, !Task.isCancelled else { return }
                     self.socket = nil
                     self.isLoading = false
-                    self.error = code == 4401 ? "Agent authentication failed. Check your Sybil token in Settings." : error.localizedDescription
+                    let attachmentsUnavailable = code == 4503 || (error as? AgentAttachmentIssue)?.code == "attachments_unavailable"
+                    if attachmentsUnavailable { self.attachmentDraft.updateCapability(nil) }
+                    self.error = code == 4401 ? "Agent authentication failed. Check your Sybil token in Settings."
+                        : code == 4503 ? "Agent attachments are unavailable. The server requires a safely authenticated Agent connection. [attachments_unavailable, 4503]"
+                        : error.localizedDescription
                     self.connection = code == 4401 ? "Offline" : "Reconnecting"
                     if code == 4401 { return }
                 }
@@ -285,7 +320,7 @@ final class SybilAgentRoom {
         schedulePublish()
     }
     func markRead(renderedCursor: String) {
-        guard hasLoaded, isActive, isSelected, !isObscured, !isModalPresented else { return }
+        guard hasLoaded, isActive, isSelected, !isObscured, !isModalPresented, !isAttachmentModalPresented else { return }
         do { desiredRead = try AgentCursor.advance(desiredRead, renderedCursor); flushRead() }
         catch { self.error = error.localizedDescription }
     }
@@ -309,17 +344,51 @@ final class SybilAgentRoom {
         }
     }
 
+    func downloadAttachment(_ attachment: AgentAttachment) async throws -> Data {
+        guard let client else { throw AgentAttachmentIssue.unavailable }
+        let session = attachmentSessionID
+        let data = try await attachmentDownloads.data(for: attachment, client: client)
+        try Task.checkCancellation()
+        guard attachmentSessionID == session else { throw CancellationError() }
+        return data
+    }
+
     @discardableResult
-    func send(_ content: String) -> Bool {
+    func sendComposer() -> Bool {
-        guard !content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty, content.utf16.count <= 40_000 else {
+        do {
-            error = "Enter a message of at most 40,000 characters."; return false
+            let attachments = try attachmentDraft.validateReady()
-        }
+            guard attachmentDraft.canSend, send(composer, attachments: attachments, draftID: attachmentDraft.id) else { return false }
+            return true
+        } catch { self.error = error.localizedDescription; return false }
+    }
+
+    @discardableResult
+    func send(_ content: String, attachments: [AgentAttachment] = [], draftID: String? = nil) -> Bool {
+        do {
+            _ = try AgentSubmission(content: content, requestID: UUID().uuidString, attachments: attachments)
+            if !attachments.isEmpty {
+                guard let limits = attachmentDraft.capability, attachmentDraft.supportsAttachments else { throw AgentAttachmentIssue.unavailable }
+                try limits.validate(attachments)
+            }
+        } catch { self.error = error.localizedDescription; return false }
         guard storageReadable, client != nil else { error = "Pending messages could not be restored. Reconnect before sending."; return false }
-        let row = AgentOutboxRow(requestID: UUID().uuidString, content: content, createdAt: Date())
+        let row = AgentOutboxRow(requestID: UUID().uuidString, content: content, createdAt: Date(), attachments: attachments.isEmpty ? nil : attachments, draftID: draftID)
         outbox.append(row)
+        do { if !attachments.isEmpty || draftID != nil { try persist() } }
+        catch {
+            outbox.removeAll { $0.id == row.id }
+            self.error = "Could not save message: \(error.localizedDescription)"
+            return false // Keep the entire draft when durable handoff fails.
+        }
         pendingEntrances.insert(row.id)
         presenter.sent(now: Date(), activity: pending.activity)
         flush()
+        if draftID == attachmentDraft.id, !attachmentDraft.clearAfterSubmission() {
+            outbox[outbox.count - 1].status = "failed"
+            outbox[outbox.count - 1].error = attachmentDraft.error
+            try? persist()
+            return false
+        }
         dispatch(row.id)
         return true
     }
@@ -330,6 +399,7 @@ final class SybilAgentRoom {
     }
     private func dispatch(_ id: String) {
         guard let client, sends[id] == nil, let index = outbox.firstIndex(where: { $0.id == id }), !outbox[index].seenOnServer else { return }
+        if outbox[index].draftID == attachmentDraft.id, !attachmentDraft.clearAfterSubmission() { return }
         outbox[index].status = "sending"; outbox[index].error = nil
         do { try persist() }
         catch { outbox[index].status = "failed"; outbox[index].error = "Could not save message: \(error.localizedDescription)"; return }
@@ -338,8 +408,14 @@ final class SybilAgentRoom {
             guard let self else { return }
             defer { if self.generation == run { self.sends[id] = nil } }
             do {
-                let receipt = try await client.agentSubmit(content: row.content, requestID: row.requestID)
+                let attachments = row.attachments ?? []
-                try receipt.validate(requestID: row.requestID)
+                if !attachments.isEmpty {
+                    guard let limits = self.attachmentDraft.capability, self.attachmentDraft.supportsAttachments else { throw AgentAttachmentIssue.unavailable }
+                    try limits.validate(attachments)
+                }
+                let submission = try AgentSubmission(content: row.content, requestID: row.requestID, attachments: attachments)
+                let receipt = try await client.agentSubmit(submission)
+                try receipt.validate(requestID: row.requestID, attachmentIDs: submission.attachmentIDs)
                 guard self.generation == run, let index = self.outbox.firstIndex(where: { $0.id == id }), !self.outbox[index].confirmed else { return }
                 self.outbox[index].seenOnServer = true
                 self.outbox[index].status = receipt.status == "queued" ? "queued" : "complete"
@@ -353,15 +429,19 @@ final class SybilAgentRoom {
         }
     }
     private func reconcileOutbox() {
-        let committed = Set(pending.messages.map(\.id))
+        let committed = pending.messages
-        let queued = Set(pending.activity.queuedMessages.map(\.id))
+        let queued = pending.activity.queuedMessages
         var changed = false
         for index in outbox.indices {
-            if committed.contains(outbox[index].id) {
+            let row = outbox[index]
+            let matches: (Message) -> Bool = { message in
+                message.id == row.id && ((row.attachments ?? []).isEmpty || message.agentAttachments.map(\.id) == row.attachments?.map(\.id))
+            }
+            if committed.contains(where: matches) {
                 if !outbox[index].confirmed { changed = true }
                 outbox[index].confirmed = true; outbox[index].seenOnServer = true
                 outbox[index].status = "complete"; outbox[index].error = nil
-            } else if queued.contains(outbox[index].id), !outbox[index].confirmed {
+            } else if queued.contains(where: matches), !outbox[index].confirmed {
                 changed = true
                 outbox[index].seenOnServer = true; outbox[index].status = "queued"; outbox[index].error = nil
             }

ios/Packages/Sybil/Sources/Sybil/SybilAgentTransport.swift

@@ -13,6 +13,9 @@ protocol AgentAPIClienting: Sendable {
     func agentReadState() async throws -> AgentReadState
     func agentMarkRead(cursor: String) async throws -> AgentReadState
     func agentSubmit(content: String, requestID: String) async throws -> AgentReceipt
+    func agentSubmit(_ submission: AgentSubmission) async throws -> AgentReceipt
+    func agentUpload(file: AgentPreparedAttachment, uploadID: String) async throws -> AgentAttachment
+    func agentDownload(_ attachment: AgentAttachment) async throws -> Data
     func agentSocket(after: String) async throws -> any AgentSocket
 }
 
@@ -54,3 +57,34 @@ extension APIConfiguration {
         return String(decoding: try JSONEncoder().encode(value), as: UTF8.self)
     }
 }
+
+// Text-only test/legacy clients fail closed for the new wire path.
+extension AgentAPIClienting {
+    func agentSubmit(_ submission: AgentSubmission) async throws -> AgentReceipt {
+        guard submission.attachmentIDs.isEmpty else { throw AgentAttachmentIssue.unavailable }
+        return try await agentSubmit(content: submission.content, requestID: submission.requestId)
+    }
+    func agentUpload(file: AgentPreparedAttachment, uploadID: String) async throws -> AgentAttachment { throw AgentAttachmentIssue.unavailable }
+    func agentDownload(_ attachment: AgentAttachment) async throws -> Data { throw AgentAttachmentIssue.unavailable }
+}
+
+final class AgentAttachmentRedirectPolicy: NSObject, URLSessionTaskDelegate, Sendable {
+    // Reject every redirect; attachment credentials are valid only for the configured API.
+    func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse,
+                    newRequest request: URLRequest, completionHandler: @escaping @Sendable (URLRequest?) -> Void) {
+        completionHandler(nil)
+    }
+}
+
+extension APIConfiguration {
+    func agentAttachmentContentURL(id: String) throws -> URL {
+        guard !id.isEmpty, var parts = URLComponents(url: baseURL, resolvingAgainstBaseURL: false),
+              ["http", "https"].contains(parts.scheme), parts.host != nil, parts.user == nil, parts.password == nil,
+              let escaped = id.addingPercentEncoding(withAllowedCharacters: CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_")) else { throw APIError.invalidBaseURL }
+        let base = parts.percentEncodedPath.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+        parts.percentEncodedPath = (base.isEmpty ? "" : "/" + base) + "/v1/agent/attachments/" + escaped + "/content"
+        parts.query = nil; parts.fragment = nil
+        guard let url = parts.url else { throw APIError.invalidBaseURL }
+        return url
+    }
+}

ios/Packages/Sybil/Sources/Sybil/SybilAgentView.swift

@@ -18,21 +18,29 @@ struct SybilAgentView: View {
     private let bottomID = "agent-bottom"
 
     private var readKey: String {
-        "\(room.snapshot.room.cursor):\(atLatest):\(scrollMetrics.atBottom):\(isScrolling):\(room.isObscured):\(room.isModalPresented):\(scenePhase == .active):\(room.isLoading):\(room.snapshot.revision)"
+        "\(room.snapshot.room.cursor):\(atLatest):\(scrollMetrics.atBottom):\(isScrolling):\(room.isObscured):\(room.isModalPresented):\(room.isAttachmentModalPresented):\(scenePhase == .active):\(room.isLoading):\(room.snapshot.revision)"
     }
+    private var visibleReadingAnchor: AgentReadingAnchor? {
+        rowFrames.filter { $0.value.maxY > topInset && $0.value.minY < scrollMetrics.height }
+            .min { $0.value.minY < $1.value.minY }
+            .map { AgentReadingAnchor(id: $0.key, offset: $0.value.minY) }
+    }
+
     var body: some View {
         let rendered = room.snapshot
-        let allMessages = room.messages
+        let transcript = AgentTranscript(messages: room.messages, startID: historyStartID, limit: historyLimit)
-        let startIndex = historyStartID.flatMap { id in allMessages.firstIndex(where: { $0.id == id }) } ?? max(0, allMessages.count - historyLimit)
+        let allMessages = transcript.messages
-        let displayed = Array(allMessages.dropFirst(startIndex))
+        let startIndex = transcript.startIndex
+        let displayed = transcript.displayed
         VStack(spacing: 0) {
             ScrollViewReader { proxy in
                 ScrollView {
                     VStack(alignment: .leading, spacing: 15) {
                         if allMessages.count > displayed.count {
                             Button("Load earlier messages") {
-                                if let anchor = rowFrames.filter({ $0.value.maxY > 0 }).min(by: { $0.value.minY < $1.value.minY }) {
+                                if var anchor = visibleReadingAnchor {
-                                    restoreAnchor = AgentReadingAnchor(id: anchor.key, offset: anchor.value.minY, expectedCount: min(allMessages.count, displayed.count + 100))
+                                    anchor.expectedCount = min(allMessages.count, displayed.count + 100)
+                                    restoreAnchor = anchor
                                 }
                                 atLatest = false
                                 historyLimit += 100
@@ -51,13 +59,7 @@ struct SybilAgentView: View {
                                         .frame(maxWidth: .infinity)
                                         .padding(.vertical, 6)
                                 }
-                                Group {
+                                AgentMessageRow(message: message, room: room, retry: { room.retry(message.id) })
-                                    if message.isToolCallLog {
-                                        AgentToolCard(message: message)
-                                    } else {
-                                        AgentMessageRow(message: message, retry: { room.retry(message.id) })
-                                    }
-                                }
                                 .background(GeometryReader { geometry in
                                     Color.clear.preference(key: AgentRowFrames.self, value: [message.id: geometry.frame(in: .named("agent-scroll"))])
                                 })
@@ -78,7 +80,10 @@ struct SybilAgentView: View {
                     }
                     .scrollTargetLayout()
                     .padding(.horizontal, 16)
-                    .padding(.vertical, 16)
+                    .padding(.bottom, 16)
+                    // Match normal chat: content clears the header, while the
+                    // viewport extends beneath the shared navigation fade.
+                    .padding(.top, 16 + topInset)
                     .frame(maxWidth: SybilLayout.webContentMaxWidth)
                     .frame(maxWidth: .infinity)
                 }
@@ -95,7 +100,8 @@ struct SybilAgentView: View {
                     AgentScrollMetrics(offset: geometry.contentOffset.y,
                         height: geometry.containerSize.height,
                         contentHeight: geometry.contentSize.height,
-                        bottomInset: geometry.contentInsets.bottom, topInset: geometry.contentInsets.top)
+                        bottomInset: geometry.contentInsets.bottom, topInset: geometry.contentInsets.top,
+                        visibleBottom: geometry.visibleRect.maxY)
                 } action: { previous, next in
                     scrollMetrics = next
                     if isScrolling || next.contentHeight <= next.height { atLatest = next.atBottom }
@@ -105,19 +111,20 @@ struct SybilAgentView: View {
                     }
                 }
                 .onPreferenceChange(AgentRowFrames.self) { frames in
-                    let previousAnchor = rowFrames.filter { $0.value.maxY > 0 && $0.value.minY < scrollMetrics.height }
+                    let anchor = restoreAnchor ?? (!atLatest && !isScrolling ? visibleReadingAnchor : nil)
-                        .min { $0.value.minY < $1.value.minY }
-                        .map { AgentReadingAnchor(id: $0.key, offset: $0.value.minY) }
-                    let anchor = restoreAnchor ?? (!atLatest && !isScrolling ? previousAnchor : nil)
                     if let anchor, let frame = frames[anchor.id], abs(frame.minY - anchor.offset) > 1 {
-                        // Restore the exact pixel offset after insertion, tool
+                        // Restore the exact pixel offset after insertion or text
-                        // expansion or text reflow. Normalize the saved frames to
+                        // reflow. Normalize the saved frames to
                         // the requested offset so the next layout cannot undo it.
                         let requested = scrollMetrics.offset + frame.minY - anchor.offset
-                        let target = min(max(requested, -scrollMetrics.topInset), max(-scrollMetrics.topInset, scrollMetrics.contentHeight - scrollMetrics.height + scrollMetrics.bottomInset))
+                        let target = min(max(requested, -scrollMetrics.topInset), scrollMetrics.maximumOffset)
                         let appliedShift = target - scrollMetrics.offset
                         rowFrames = frames.mapValues { $0.offsetBy(dx: 0, dy: -appliedShift) }
-                        if abs(appliedShift) > 1 { scrollPosition.scrollTo(y: target) }
+                        if abs(appliedShift) > 1 {
+                            // Geometry reports the raw offset; ScrollPosition uses
+                            // zero at the top inset, including the safe area.
+                            scrollPosition.scrollTo(y: target + scrollMetrics.topInset)
+                        }
                         restoreAnchor = nil
                     } else {
                         rowFrames = frames
@@ -157,16 +164,15 @@ struct SybilAgentView: View {
             statusBar
             composer
         }
-        .padding(.top, topInset)
         .onAppear { room.isSelected = true }
         .onDisappear { room.isSelected = false }
         .task(id: readKey) {
             // This cursor belongs to the rendered snapshot. New network input cancels
             // the task, and cannot be acknowledged while still entering the layout.
             let cursor = rendered.room.cursor
-            guard atLatest, scrollMetrics.atBottom, !isScrolling, !room.isObscured, !room.isModalPresented, scenePhase == .active, !room.isLoading else { return }
+            guard atLatest, scrollMetrics.atBottom, !isScrolling, !room.isObscured, !room.isModalPresented, !room.isAttachmentModalPresented, scenePhase == .active, !room.isLoading else { return }
             try? await Task.sleep(for: .milliseconds(reduceMotion ? 80 : 360))
-            guard !Task.isCancelled, atLatest, scrollMetrics.atBottom, !isScrolling, !room.isObscured, !room.isModalPresented, scenePhase == .active else { return }
+            guard !Task.isCancelled, atLatest, scrollMetrics.atBottom, !isScrolling, !room.isObscured, !room.isModalPresented, !room.isAttachmentModalPresented, scenePhase == .active else { return }
             room.markRead(renderedCursor: cursor)
         }
     }
@@ -194,31 +200,33 @@ struct SybilAgentView: View {
         }
     }
 
+    private var canSendComposer: Bool {
+        room.attachmentDraft.canSend
+    }
+
     private var composer: some View {
-        HStack(alignment: .bottom, spacing: 10) {
+        VStack(alignment: .leading, spacing: 8) {
-            TextField("Message Sybil…", text: $room.composer, axis: .vertical)
+            AgentAttachmentComposer(room: room)
-                .lineLimit(1...6)
+            HStack(alignment: .bottom, spacing: 10) {
-                .font(.sybil(.body))
+                SybilPromptField(
-                .focused($composerFocused)
+                    text: $room.composer,
+                    focused: $composerFocused,
+                    submit: submitComposer
+                )
                 .accessibilityIdentifier("agent-composer")
-            Button {
+
-                let content = room.composer
+                SybilPromptSendButton(canSend: canSendComposer, submit: submitComposer)
-                if room.send(content) { room.composer = ""; atLatest = true }
+                .accessibilityIdentifier("agent-send")
-            } label: {
-                Image(systemName: "arrow.up")
-                    .font(.system(size: 17, weight: .semibold))
-                    .foregroundStyle(.white)
-                    .frame(width: 38, height: 38)
-                    .background(SybilTheme.primaryGradient, in: Circle())
             }
-            .disabled(room.composer.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || room.composer.utf16.count > 40_000)
-            .accessibilityLabel("Send message")
-            .accessibilityIdentifier("agent-send")
         }
-        .padding(12)
+        .padding(.horizontal, 14)
-        .background(SybilTheme.surfaceStrong, in: RoundedRectangle(cornerRadius: 22))
+        .padding(.bottom, 12)
-        .overlay(RoundedRectangle(cornerRadius: 22).stroke(SybilTheme.border))
+        .padding(.top, 6)
-        .padding(.horizontal, 12).padding(.bottom, 10).padding(.top, 6)
+    }
+
+    private func submitComposer() {
+        guard canSendComposer, room.sendComposer() else { return }
+        atLatest = true
     }
 }
 
@@ -233,6 +241,7 @@ struct AgentAvatar: View {
 
 private struct AgentMessageRow: View {
     var message: Message
+    var room: SybilAgentRoom
     var retry: () -> Void
     private var own: Bool { message.role == .user }
     private var status: String { message.metadata?.objectValue?["status"]?.stringValue ?? "complete" }
@@ -240,6 +249,9 @@ private struct AgentMessageRow: View {
         HStack(alignment: .bottom, spacing: 8) {
             if !own { AgentAvatar().padding(.bottom, 23) }
             VStack(alignment: own ? .trailing : .leading, spacing: 5) {
+                ForEach(message.agentAttachments) { attachment in
+                    AgentAttachmentCard(attachment: attachment, room: room)
+                }
                 MessageBubble(message: message, isSending: false, streamingAssistantPresentation: nil, isForking: false, onFork: nil, agentStyle: true)
                 HStack(spacing: 6) {
                     Text(own ? "You" : "Sybil")
@@ -260,57 +272,6 @@ private struct AgentMessageRow: View {
     }
 }
 
-struct AgentToolCard: View {
-    var message: Message
-    @State private var expanded = false
-    var body: some View {
-        if let metadata = message.toolCallMetadata {
-            VStack(alignment: .leading, spacing: 0) {
-                Button {
-                    expanded.toggle()
-                } label: {
-                    HStack(spacing: 8) {
-                        ToolCallActivityChip(metadata: metadata, fallbackContent: message.content, createdAt: message.createdAt, compactLayout: true)
-                            .allowsHitTesting(false)
-                        Spacer(minLength: 0)
-                        Image(systemName: expanded ? "chevron.down" : "chevron.right")
-                            .font(.system(size: 13, weight: .semibold))
-                    }
-                    .contentShape(Rectangle())
-                }
-                .buttonStyle(.plain)
-                .accessibilityIdentifier("agent-tool-\(metadata.toolName ?? "tool")")
-                .accessibilityValue(expanded ? "Expanded" : "Collapsed")
-                if expanded {
-                    VStack(alignment: .leading, spacing: 12) {
-                        if let args = metadata.args { detail("Input", text: pretty(args)) }
-                        if let error = metadata.error { detail("Error", text: error) }
-                        if let result = metadata.result { detail("Result", text: pretty(result)) }
-                        else if let preview = metadata.resultPreview { detail("Result", text: preview) }
-                        if metadata.args == nil && metadata.result == nil && metadata.resultPreview == nil && metadata.error == nil {
-                            Text(message.content).font(.sybil(.caption))
-                        }
-                    }.padding(.top, 8).frame(maxWidth: .infinity, alignment: .leading)
-                }
-            }
-            .foregroundStyle(SybilTheme.textMuted)
-            .padding(8)
-            .background(SybilTheme.surface.opacity(0.8), in: RoundedRectangle(cornerRadius: 14))
-        }
-    }
-    private func detail(_ title: String, text: String) -> some View {
-        VStack(alignment: .leading, spacing: 4) {
-            Text(title).font(.sybil(.caption, weight: .semibold)).accessibilityIdentifier("agent-tool-\(title.lowercased())")
-            Text(text).font(.system(size: 12, design: .monospaced)).textSelection(.enabled)
-        }
-    }
-    private func pretty(_ value: JSONValue) -> String {
-        if let text = value.stringValue { return text }
-        let encoder = JSONEncoder(); encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
-        return (try? encoder.encode(value)).map { String(decoding: $0, as: UTF8.self) } ?? ""
-    }
-}
-
 // Animate both occupied height and content, so incoming rows push older history up.
 private struct AgentGrowingLayout: Layout {
     var progress: CGFloat
@@ -345,7 +306,12 @@ private struct AgentScrollMetrics: Equatable {
     var contentHeight: CGFloat = 0
     var bottomInset: CGFloat = 0
     var topInset: CGFloat = 0
-    var atBottom: Bool { height > 0 && contentHeight - offset - height + bottomInset <= 24 }
+    var visibleBottom: CGFloat = 0
+    // visibleRect includes the viewport extended into the safe area, as well as
+    // the alignment inset used when a short transcript is pinned to the bottom.
+    var distanceFromBottom: CGFloat { contentHeight + bottomInset - visibleBottom }
+    var atBottom: Bool { height > 0 && distanceFromBottom <= 24 }
+    var maximumOffset: CGFloat { max(-topInset, offset + distanceFromBottom) }
 }
 private struct AgentReadingAnchor {
     var id: String

ios/Packages/Sybil/Sources/Sybil/SybilPromptField.swift

@@ -0,0 +1,62 @@
+import SwiftUI
+
+struct SybilPromptField: View {
+    var placeholder: String = "Enter Prompt"
+    @Binding var text: String
+    @FocusState.Binding var focused: Bool
+    var selection: Binding<TextSelection?>? = nil
+    var axis: Axis = .vertical
+    var submit: () -> Void
+
+    var body: some View {
+        Group {
+            if let selection {
+                TextField(placeholder, text: $text, selection: selection, axis: axis)
+            } else {
+                TextField(placeholder, text: $text, axis: axis)
+            }
+        }
+        .focused($focused)
+        .font(.sybil(.body))
+        .textInputAutocapitalization(.sentences)
+        .autocorrectionDisabled(false)
+        .lineLimit(1 ... 6)
+        .submitLabel(.send)
+        .onSubmit(submit)
+        .submitOnMacReturn(submit)
+        .padding(.horizontal, 12)
+        .padding(.vertical, 10)
+        .background(
+            RoundedRectangle(cornerRadius: 12)
+                .fill(SybilTheme.composerGradient)
+                .opacity(0.98)
+        )
+        .foregroundStyle(SybilTheme.text)
+    }
+}
+
+struct SybilPromptSendButton: View {
+    var systemImage: String = "arrow.up"
+    var canSend: Bool
+    var submit: () -> Void
+
+    var body: some View {
+        Button(action: submit) {
+            Image(systemName: systemImage)
+                .font(.system(size: 17, weight: .semibold))
+                .frame(width: 40, height: 40)
+                .background(
+                    Circle()
+                        .fill(
+                            canSend
+                                ? AnyShapeStyle(SybilTheme.primaryGradient)
+                                : AnyShapeStyle(SybilTheme.surface)
+                        )
+                )
+                .foregroundStyle(canSend ? SybilTheme.text : SybilTheme.textMuted)
+        }
+        .buttonStyle(.plain)
+        .disabled(!canSend)
+        .accessibilityLabel("Send message")
+    }
+}

ios/Packages/Sybil/Sources/Sybil/SybilQuickQuestionView.swift

@@ -95,46 +95,19 @@ struct SybilQuickQuestionView: View {
     private var composer: some View {
         VStack(alignment: .leading, spacing: 10) {
             HStack(alignment: .bottom, spacing: 10) {
-                TextField(
+                SybilPromptField(
-                    "Ask anything...",
+                    placeholder: "Ask anything...",
                     text: Binding(
                         get: { viewModel.quickQuestionPrompt },
                         set: { viewModel.updateQuickQuestionPrompt($0) }
                     ),
+                    focused: $promptFocused,
                     selection: $promptSelection,
-                    axis: .horizontal
+                    axis: .horizontal,
+                    submit: submitQuestion
                 )
-                .focused($promptFocused)
-                .font(.body)
-                .textInputAutocapitalization(.sentences)
-                .autocorrectionDisabled(false)
-                .submitLabel(.send)
-                .onSubmit(submitQuestion)
-                .padding(.horizontal, 12)
-                .padding(.vertical, 10)
-                .background(
-                    RoundedRectangle(cornerRadius: 12)
-                        .fill(SybilTheme.composerGradient)
-                        .opacity(0.98)
-                )
-                .foregroundStyle(SybilTheme.text)
 
-                Button(action: submitQuestion) {
+                SybilPromptSendButton(canSend: viewModel.canSendQuickQuestion, submit: submitQuestion)
-                    Image(systemName: "arrow.up")
-                        .font(.body.weight(.semibold))
-                        .frame(width: 40, height: 40)
-                        .background(
-                            Circle()
-                                .fill(
-                                    viewModel.canSendQuickQuestion
-                                        ? AnyShapeStyle(SybilTheme.primaryGradient)
-                                        : AnyShapeStyle(SybilTheme.surfaceStrong.opacity(0.92))
-                                )
-                        )
-                        .foregroundStyle(viewModel.canSendQuickQuestion ? SybilTheme.text : SybilTheme.textMuted)
-                }
-                .buttonStyle(.plain)
-                .disabled(!viewModel.canSendQuickQuestion)
                 .accessibilityLabel("Ask quick question")
             }
 

ios/Packages/Sybil/Sources/Sybil/SybilViewModel.swift

@@ -680,7 +680,7 @@ final class SybilViewModel {
 
             await loadInitialData(using: client)
             if isAuthenticated, let agentClient = client as? any AgentAPIClienting, let baseURL = settings.normalizedAPIBaseURL {
-                agent.configure(client: agentClient, storage: .file(baseURL: baseURL))
+                agent.configure(client: agentClient, storage: .file(baseURL: baseURL), draftStorage: .file(baseURL: baseURL))
                 agent.setActive(isAppActive)
             }
             startActiveRunPolling()

ios/Packages/Sybil/Sources/Sybil/SybilWorkspaceView.swift

@@ -613,47 +613,19 @@ struct SybilWorkspaceView: View {
                     .accessibilityLabel("Attach file")
                 }
 
-                TextField(
+                SybilPromptField(
-                    viewModel.isSearchMode ? "Search the web" : "Enter Prompt",
+                    placeholder: viewModel.isSearchMode ? "Search the web" : "Enter Prompt",
                     text: $viewModel.composer,
-                    axis: .vertical
+                    focused: $composerFocused,
+                    submit: submitComposer
                 )
-                .focused($composerFocused)
-                .textInputAutocapitalization(.sentences)
-                .autocorrectionDisabled(false)
-                .lineLimit(1 ... 6)
-                .submitLabel(.send)
-                .onSubmit {
-                    submitComposer()
-                }
-                .submitOnMacReturn(submitComposer)
-                .padding(.horizontal, 12)
-                .padding(.vertical, 10)
-                .background(
-                    RoundedRectangle(cornerRadius: 12)
-                        .fill(SybilTheme.composerGradient)
-                        .opacity(0.98)
-                )
-                .foregroundStyle(SybilTheme.text)
 
-                Button {
+                SybilPromptSendButton(
-                    submitComposer()
+                    systemImage: viewModel.isSearchMode ? "magnifyingglass" : "arrow.up",
-                } label: {
+                    canSend: viewModel.canSendComposer,
-                    Image(systemName: viewModel.isSearchMode ? "magnifyingglass" : "arrow.up")
+                    submit: submitComposer
-                        .font(.system(size: 17, weight: .semibold))
+                )
-                        .frame(width: 40, height: 40)
+                .accessibilityLabel(viewModel.isSearchMode ? "Search" : "Send message")
-                        .background(
-                            Circle()
-                                .fill(
-                                    viewModel.canSendComposer
-                                        ? AnyShapeStyle(SybilTheme.primaryGradient)
-                                        : AnyShapeStyle(SybilTheme.surface)
-                                )
-                        )
-                        .foregroundStyle(viewModel.canSendComposer ? SybilTheme.text : SybilTheme.textMuted)
-                }
-                .buttonStyle(.plain)
-                .disabled(!viewModel.canSendComposer)
             }
         }
         .padding(.horizontal, 14)

ios/Packages/Sybil/Tests/SybilTests/AgentAttachmentTests.swift

@@ -0,0 +1,545 @@
+import CryptoKit
+import Foundation
+import ImageIO
+import Testing
+import UIKit
+import UniformTypeIdentifiers
+@testable import Sybil
+
+private let attachmentLimits = AgentAttachmentCapabilities(version: 1, maxCount: 8, maxTotalBytes: 33_554_432,
+    maxImageBytes: 6_291_456, maxFileBytes: 8_388_608, imageMimeTypes: ["image/png", "image/jpeg", "image/gif", "image/webp"],
+    maxImagePixels: 50_000_000, maxImageDimension: 16_384)
+private let originalBytes = Data([0, 255, 10, 13, 128, 42])
+private func sampleAttachment(_ id: String = "opaque-server-id", data: Data = originalBytes, name: String = "original.bin") -> AgentAttachment {
+    AgentAttachment(id: id, kind: .file, filename: name, mimeType: "application/octet-stream", sizeBytes: data.count,
+        sha256: SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined(), workspacePath: "/runtime/provided/\(name)")
+}
+private func descriptorData(capability: Bool = true) throws -> Data {
+    var object: [String: Any] = ["id": "root", "title": "Sybil", "type": "persistent-agent", "model": "fixture", "protocol": "pi-room.v1", "websocket": "/v1/agent/ws",
+        "activity": ["state": "idle", "isThinking": false, "queued": 0, "backgroundWorkers": 0, "tools": [], "queuedMessages": []]]
+    if capability { object["capabilities"] = ["attachments": try JSONSerialization.jsonObject(with: JSONEncoder().encode(attachmentLimits)), "future": true] }
+    object["unknown"] = ["additive": true]
+    return try JSONSerialization.data(withJSONObject: object)
+}
+private final class AttachmentTestStore: @unchecked Sendable {
+    private let lock = NSLock()
+    private var rows: [AgentOutboxRow] = []
+    var storage: AgentOutboxStorage { .init(read: { self.read() }, write: { value in self.lock.withLock { self.rows = value } }) }
+    func read() -> [AgentOutboxRow] { lock.withLock { rows } }
+}
+private actor AttachmentTestClient: AgentAPIClienting {
+    var uploads: [String] = []
+    var submissions: [AgentSubmission] = []
+    var failUploads = 0
+    var badReceipt = false
+    var uploadDelay = Duration.milliseconds(20)
+    var holdDownloads = false
+    var downloadWaiters: [String: CheckedContinuation<Data, Never>] = [:]
+    var downloadStarts: [String] = []
+    var downloadActive = 0
+    var downloadPeak = 0
+    var beforeSubmit: (@Sendable () -> Bool)?
+    var unavailableDescriptor = false
+    var unavailableSocket = false
+    func agentDescriptor() throws -> AgentDescriptor {
+        if unavailableDescriptor { throw AgentAttachmentIssue(message: "Synthetic open proxy requires authentication", code: "attachments_unavailable", statusCode: 503) }
+        return try AgentCoding.decoder().decode(AgentDescriptor.self, from: descriptorData())
+    }
+    func agentMessages(after: String?, before: String?) -> AgentPage { .init(conversationId: "root", messages: [], cursor: after ?? "0", hasMore: false) }
+    func agentReadState() -> AgentReadState { .init(cursor: "0") }
+    func agentMarkRead(cursor: String) -> AgentReadState { .init(cursor: cursor) }
+    func agentSubmit(content: String, requestID: String) -> AgentReceipt { .init(id: 1, status: "queued", messageId: "inbound:sybil:\(requestID)") }
+    func agentSubmit(_ submission: AgentSubmission) throws -> AgentReceipt {
+        #expect(beforeSubmit?() ?? true)
+        submissions.append(submission)
+        return .init(id: 1, status: "queued", messageId: "inbound:sybil:\(submission.requestId)", attachmentIds: badReceipt ? nil : submission.attachmentIDs)
+    }
+    func agentUpload(file: AgentPreparedAttachment, uploadID: String) async throws -> AgentAttachment {
+        uploads.append(uploadID)
+        try await Task.sleep(for: uploadDelay)
+        if failUploads > 0 { failUploads -= 1; throw AgentAttachmentIssue(message: "Free storage or retry later.", code: "attachment_quota_exceeded", statusCode: 507, details: ["futureQuotaField": .number(1)]) }
+        return AgentAttachment(id: "server-\(uploadID)", kind: .file, filename: file.filename, mimeType: file.mimeType, sizeBytes: file.data.count, sha256: file.sha256)
+    }
+    func agentDownload(_ attachment: AgentAttachment) async -> Data {
+        downloadStarts.append(attachment.id); downloadActive += 1; downloadPeak = max(downloadPeak, downloadActive)
+        defer { downloadActive -= 1 }
+        if holdDownloads { return await withCheckedContinuation { downloadWaiters[attachment.id] = $0 } }
+        return originalBytes
+    }
+    func pauseDownloads() { holdDownloads = true }
+    func releaseDownload(_ id: String) { downloadWaiters.removeValue(forKey: id)?.resume(returning: originalBytes) }
+    func downloadCounts() -> (Int, Int) { (downloadStarts.count, downloadPeak) }
+    func downloadedIDs() -> [String] { downloadStarts }
+    func agentSocket(after: String) throws -> any AgentSocket {
+        if unavailableSocket { return AttachmentUnavailableSocket() }
+        throw AgentFailure(message: "No socket in unit fixture")
+    }
+    func blockDescriptor() { unavailableDescriptor = true }
+    func blockSocket() { unavailableSocket = true }
+    func failNextUpload(delay: Duration = .milliseconds(20)) { failUploads = 1; uploadDelay = delay }
+    func delayUploads(_ delay: Duration) { uploadDelay = delay }
+    func malformedReceipts(_ value: Bool) { badReceipt = value }
+    func requirePersisted(_ check: @escaping @Sendable () -> Bool) { beforeSubmit = check }
+    func uploadIDs() -> [String] { uploads }
+    func sent() -> [AgentSubmission] { submissions }
+}
+private struct AttachmentUnavailableSocket: AgentSocket {
+    func receive() throws -> Data { throw AgentFailure(message: "Synthetic closed socket") }
+    func send(_ text: String) {}
+    func close() {}
+    func closeCode() -> Int { 4503 }
+}
+@MainActor private func attachmentEventually(_ predicate: () -> Bool) async -> Bool {
+    for _ in 0..<200 { if predicate() { return true }; try? await Task.sleep(for: .milliseconds(10)) }
+    return false
+}
+private final class AttachmentURLProtocol: URLProtocol, @unchecked Sendable {
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var handler: (@Sendable (URLRequest) throws -> (Int, [String: String], Data))?
+    static func install(_ value: @escaping @Sendable (URLRequest) throws -> (Int, [String: String], Data)) { lock.withLock { handler = value } }
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+    override func startLoading() {
+        do {
+            let handler = Self.lock.withLock { Self.handler! }
+            let (status, headers, data) = try handler(request)
+            client?.urlProtocol(self, didReceive: HTTPURLResponse(url: request.url!, statusCode: status, httpVersion: nil, headerFields: headers)!, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: data)
+            client?.urlProtocolDidFinishLoading(self)
+        } catch { client?.urlProtocol(self, didFailWithError: error) }
+    }
+    override func stopLoading() {}
+}
+private func attachmentSession() -> URLSession {
+    let config = URLSessionConfiguration.ephemeral; config.protocolClasses = [AttachmentURLProtocol.self]
+    return URLSession(configuration: config)
+}
+private func requestBytes(_ request: URLRequest) -> Data {
+    if let body = request.httpBody { return body }
+    guard let stream = request.httpBodyStream else { return Data() }
+    stream.open(); defer { stream.close() }
+    var data = Data(), buffer = [UInt8](repeating: 0, count: 4096)
+    while stream.hasBytesAvailable { let count = stream.read(&buffer, maxLength: buffer.count); if count <= 0 { break }; data.append(contentsOf: buffer.prefix(count)) }
+    return data
+}
+
+@Suite(.serialized) struct AgentAttachmentTests {
+    @Test func additiveCapabilityAndDistinctMetadata() throws {
+        let old = try AgentCoding.decoder().decode(AgentDescriptor.self, from: descriptorData(capability: false))
+        #expect(old.capabilities == nil)
+        let current = try AgentCoding.decoder().decode(AgentDescriptor.self, from: descriptorData())
+        #expect(current.capabilities?.attachments?.supported == true)
+        var future = try JSONSerialization.jsonObject(with: descriptorData()) as! [String: Any]
+        future["capabilities"] = ["attachments": ["version": 9, "newWire": true]]
+        let unsupported = try AgentCoding.decoder().decode(AgentDescriptor.self, from: JSONSerialization.data(withJSONObject: future))
+        #expect(unsupported.capabilities?.attachments == nil)
+        var other = attachmentLimits; other.version = 2
+        #expect(!other.supported)
+        let attachment = sampleAttachment()
+        let message = Message(id: "user", createdAt: Date(), role: .user, content: "caption", metadata: .object(["agentAttachments": .array([attachment.metadataValue]), "future": .bool(true)]))
+        #expect(message.attachments.isEmpty)
+        #expect(message.agentAttachments == [attachment])
+        #expect(message.content == "caption")
+        let legacy = Data(#"{"id":"x","kind":"file","filename":"x.bin","mimeType":"application/octet-stream","sizeBytes":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","unknown":true}"#.utf8)
+        #expect(try JSONDecoder().decode(AgentAttachment.self, from: legacy).workspacePath == nil)
+    }
+    @Test func safeNamesAndExactOriginalBytes() throws {
+        #expect(try AgentAttachmentPreparation.filename("cafe\u{301}.txt") == "café.txt")
+        for invalid in ["", ".", "..", "../secret", "x/y", "x\\y", "a\u{0000}b", "x\ny", String(repeating: "é", count: 128)] {
+            #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.filename(invalid) }
+        }
+        let file = try AgentAttachmentPreparation.prepare(originalBytes, filename: "archive.zip", mimeType: "application/zip", limits: attachmentLimits)
+        #expect(file.data == originalBytes)
+        let text = try AgentAttachmentPreparation.prepare(originalBytes, filename: "invalid-utf8.txt", mimeType: "text/plain", limits: attachmentLimits)
+        #expect(text.data == originalBytes) // Server classifies as file; client never decodes/truncates upload bytes.
+        #expect(try AgentAttachmentPreparation.prepare(Data(), filename: "empty.txt", mimeType: "text/plain", limits: attachmentLimits).data.isEmpty)
+        var small = attachmentLimits; small.maxFileBytes = 2
+        #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.prepare(originalBytes, filename: "x.bin", mimeType: "application/octet-stream", limits: small) }
+    }
+    @Test @MainActor func rasterValidationAndFileSelection() throws {
+        let image = UIGraphicsImageRenderer(size: CGSize(width: 12, height: 8)).image { context in UIColor.red.setFill(); context.fill(CGRect(x: 0, y: 0, width: 12, height: 8)) }
+        let png = try #require(image.pngData())
+        #expect(try AgentAttachmentPreparation.prepare(png, filename: "red.png", mimeType: "image/png", limits: attachmentLimits).data == png)
+        #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.raster(png, mime: "image/jpeg") }
+        #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.raster(png, mime: "image/png", pixels: 20) }
+        #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.raster(Data("<svg/>".utf8), mime: "image/svg+xml") }
+        let directory = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: directory) }
+        let url = directory.appendingPathComponent("sample.pdf"); try originalBytes.write(to: url)
+        let file = try AgentAttachmentPreparation.file(url, limits: attachmentLimits)
+        #expect(file.data == originalBytes); #expect(file.mimeType == "application/pdf")
+    }
+    @Test @MainActor func syntheticHEICPhotoConvertsButFileKeepsOriginal() async throws {
+        let image = UIGraphicsImageRenderer(size: CGSize(width: 2400, height: 1800)).image { context in
+            UIColor.blue.setFill(); context.fill(CGRect(x: 0, y: 0, width: 2400, height: 1800))
+        }
+        let encoded = NSMutableData()
+        let destination = try #require(CGImageDestinationCreateWithData(encoded, UTType.heic.identifier as CFString, 1, nil), "Simulator must provide an ImageIO HEIC encoder for this regression")
+        CGImageDestinationAddImage(destination, try #require(image.cgImage), nil)
+        #expect(CGImageDestinationFinalize(destination), "Synthetic HEIC encoding must succeed")
+        let data = encoded as Data
+        let prepared = try await AgentAttachmentPreparation.offMain {
+            try AgentAttachmentPreparation.photo(data, filename: "cafe\u{301}.HEIC", mimeType: "image/heic", limits: attachmentLimits)
+        }
+        #expect(prepared.filename == "café.jpg"); #expect(prepared.mimeType == "image/jpeg")
+        #expect(prepared.data.count <= attachmentLimits.imageLimit)
+        let source = try #require(CGImageSourceCreateWithData(prepared.data as CFData, nil))
+        #expect(CGImageSourceGetType(source) as String? == UTType.jpeg.identifier)
+        let properties = try #require(CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any])
+        #expect((properties[kCGImagePropertyPixelWidth] as? Int ?? Int.max) <= 2000)
+        #expect((properties[kCGImagePropertyPixelHeight] as? Int ?? Int.max) <= 2000)
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+        let url = root.appendingPathComponent("original.heic"); try data.write(to: url)
+        let file = try AgentAttachmentPreparation.file(url, limits: attachmentLimits)
+        #expect(file.data == data); #expect(file.filename == "original.heic"); #expect(file.mimeType == "image/heic")
+        var tooSmall = attachmentLimits; tooSmall.maxImagePixels = 100
+        #expect(throws: AgentAttachmentIssue.self) { try AgentAttachmentPreparation.photo(data, filename: "large.heic", mimeType: "image/heic", limits: tooSmall) }
+    }
+
+    @Test @MainActor func downloadCoordinatorBoundsAndCancelsQueuedTransfers() async throws {
+        let client = AttachmentTestClient(), downloads = AgentAttachmentDownloads()
+        await client.pauseDownloads()
+        let one = Task { try await downloads.data(for: sampleAttachment("one"), client: client) }
+        let two = Task { try await downloads.data(for: sampleAttachment("two"), client: client) }
+        for _ in 0..<100 { if await client.downloadCounts().0 == 2 { break }; try await Task.sleep(for: .milliseconds(10)) }
+        let three = Task { try await downloads.data(for: sampleAttachment("three"), client: client) }
+        let cancelled = Task { try await downloads.data(for: sampleAttachment("cancelled"), client: client) }
+        try await Task.sleep(for: .milliseconds(30)); cancelled.cancel()
+        await #expect(throws: CancellationError.self) { try await cancelled.value }
+        #expect(await client.downloadCounts().0 == 2)
+        await client.releaseDownload("one"); _ = try await one.value
+        for _ in 0..<100 { if await client.downloadCounts().0 == 3 { break }; try await Task.sleep(for: .milliseconds(10)) }
+        #expect(await client.downloadCounts().1 == 2)
+        #expect(await client.downloadedIDs().contains("cancelled") == false)
+        await client.releaseDownload("two"); await client.releaseDownload("three")
+        _ = try await two.value; _ = try await three.value
+        #expect(try await downloads.data(for: sampleAttachment("one"), client: client) == originalBytes)
+        #expect(await client.downloadCounts().0 == 3) // Verified cache hit.
+    }
+
+    @Test @MainActor func configurationResetRejectsOldDownloadsAndCache() async throws {
+        let old = AttachmentTestClient(), next = AttachmentTestClient(), room = SybilAgentRoom()
+        room.configure(client: old, storage: AttachmentTestStore().storage)
+        defer { room.stop() }
+        await old.pauseDownloads()
+        let stale = Task { try await room.downloadAttachment(sampleAttachment()) }
+        for _ in 0..<100 { if await old.downloadCounts().0 == 1 { break }; try await Task.sleep(for: .milliseconds(10)) }
+        room.configure(client: next, storage: AttachmentTestStore().storage)
+        await old.releaseDownload(sampleAttachment().id)
+        await #expect(throws: CancellationError.self) { try await stale.value }
+        #expect(try await room.downloadAttachment(sampleAttachment()) == originalBytes)
+        #expect(await next.downloadCounts().0 == 1)
+        #expect(try await room.downloadAttachment(sampleAttachment()) == originalBytes)
+        #expect(await next.downloadCounts().0 == 1)
+    }
+
+    @Test @MainActor func invalidatedDownloadQueueNeverStartsOrCaches() async throws {
+        let client = AttachmentTestClient(), downloads = AgentAttachmentDownloads()
+        await client.pauseDownloads()
+        let one = Task { try await downloads.data(for: sampleAttachment("one"), client: client) }
+        let two = Task { try await downloads.data(for: sampleAttachment("two"), client: client) }
+        for _ in 0..<100 { if await client.downloadCounts().0 == 2 { break }; try await Task.sleep(for: .milliseconds(10)) }
+        let queued = Task { try await downloads.data(for: sampleAttachment("queued"), client: client) }
+        try await Task.sleep(for: .milliseconds(20))
+        await downloads.invalidate()
+        await #expect(throws: CancellationError.self) { try await queued.value }
+        await client.releaseDownload("one"); await client.releaseDownload("two")
+        await #expect(throws: CancellationError.self) { try await one.value }
+        await #expect(throws: CancellationError.self) { try await two.value }
+        await #expect(throws: CancellationError.self) { try await downloads.data(for: sampleAttachment("one"), client: client) }
+        #expect(await client.downloadCounts().0 == 2)
+    }
+
+    @Test func orderedReferenceAndReceiptValidation() throws {
+        let a = sampleAttachment("one"), b = sampleAttachment("two")
+        let request = try AgentSubmission(content: "  ", requestID: "stable", attachments: [a, b])
+        let fields = try #require(JSONSerialization.jsonObject(with: JSONEncoder().encode(request)) as? [String: Any])
+        #expect((fields["attachments"] as? [[String: String]]) == [["id": "one"], ["id": "two"]])
+        #expect(throws: AgentAttachmentIssue.self) { try AgentSubmission(content: "", requestID: "stable") }
+        #expect(throws: AgentAttachmentIssue.self) { try AgentSubmission(content: "", requestID: "stable", attachments: [a, a]) }
+        for ids: [String]? in [nil, [], ["one"], ["two", "one"], ["one", "two", "extra"]] {
+            let receipt = AgentReceipt(id: 1, status: "queued", messageId: "inbound:sybil:stable", attachmentIds: ids)
+            #expect(throws: AgentAttachmentIssue.self) { try receipt.validate(requestID: "stable", attachmentIDs: ["one", "two"]) }
+        }
+        try AgentReceipt(id: 1, status: "queued", messageId: "inbound:sybil:stable", attachmentIds: ["one", "two"]).validate(requestID: "stable", attachmentIDs: request.attachmentIDs)
+    }
+    @Test func multipartPreservesBinaryAndBoundary() throws {
+        let id = UUID().uuidString
+        let file = AgentPreparedAttachment(filename: "café \"original\".bin", mimeType: "application/octet-stream", data: originalBytes)
+        let multipart = try AgentMultipart(file: file, uploadID: id)
+        let prefix = Data("\r\n\r\n".utf8)
+        #expect(multipart.body.range(of: originalBytes) != nil)
+        let printable = String(decoding: multipart.body, as: UTF8.self)
+        #expect(printable.components(separatedBy: "Content-Disposition:").count == 3)
+        #expect(printable.contains("name=\"uploadId\"\r\n\r\n\(id)"))
+        #expect(printable.contains("filename=\"café \\\"original\\\".bin\""))
+        #expect(multipart.body.suffix(Data("\r\n--\(multipart.boundary)--\r\n".utf8).count) == Data("\r\n--\(multipart.boundary)--\r\n".utf8))
+        #expect(multipart.body.range(of: prefix) != nil)
+    }
+    @Test func uploadTransportAuthBytesAndReceipt() async throws {
+        let file = AgentPreparedAttachment(filename: "original.bin", mimeType: "application/octet-stream", data: originalBytes), id = UUID().uuidString
+        AttachmentURLProtocol.install { request in
+            #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer synthetic-test")
+            #expect(request.url?.query == nil)
+            if request.url!.path == "/api/v1/agent" { return (200, [:], try descriptorData()) }
+            #expect(request.url!.path == "/api/v1/agent/attachments"); #expect(request.httpMethod == "POST")
+            let contentType = try #require(request.value(forHTTPHeaderField: "Content-Type"))
+            let boundary = try #require(contentType.components(separatedBy: "boundary=").last)
+            let bytes = requestBytes(request)
+            #expect(bytes.starts(with: Data("--\(boundary)\r\n".utf8)))
+            #expect(bytes.range(of: originalBytes) != nil); #expect(bytes.range(of: Data(id.utf8)) != nil)
+            return (201, [:], try JSONEncoder().encode(["attachment": sampleAttachment()]))
+        }
+        let session = attachmentSession(); defer { session.invalidateAndCancel() }
+        let client = SybilAPIClient(configuration: .init(baseURL: URL(string: "https://fixture.invalid/api")!, authToken: "synthetic-test"), session: session)
+        #expect(try await client.agentUpload(file: file, uploadID: id) == sampleAttachment())
+    }
+    @Test func missingCapabilityNeverUploadsOrSubmitsReferences() async throws {
+        AttachmentURLProtocol.install { request in
+            #expect(request.url!.path == "/api/v1/agent")
+            return (200, [:], try descriptorData(capability: false))
+        }
+        let session = attachmentSession(); defer { session.invalidateAndCancel() }
+        let client = SybilAPIClient(configuration: .init(baseURL: URL(string: "https://fixture.invalid/api")!), session: session)
+        await #expect(throws: AgentAttachmentIssue.self) { try await client.agentUpload(file: .init(filename: "original.bin", mimeType: "application/octet-stream", data: originalBytes), uploadID: UUID().uuidString) }
+        await #expect(throws: AgentAttachmentIssue.self) { try await client.agentSubmit(AgentSubmission(content: "", requestID: "stable", attachments: [sampleAttachment()])) }
+    }
+    @Test func openPublicAPIDisablesAttachmentCapabilityAndDownloads() async throws {
+        AttachmentURLProtocol.install { request in
+            #expect(request.url!.path == "/v1/agent")
+            return (200, [:], try descriptorData())
+        }
+        let session = attachmentSession(); defer { session.invalidateAndCancel() }
+        let client = SybilAPIClient(configuration: .init(baseURL: URL(string: "https://fixture.invalid")!), session: session)
+        #expect(try await client.agentDescriptor().capabilities?.attachments == nil)
+        await #expect(throws: AgentAttachmentIssue.self) { try await client.agentDownload(sampleAttachment()) }
+    }
+    @Test func quotaCapabilitySnapshotAndDotFilenameAreAdditive() throws {
+        var fields = try JSONSerialization.jsonObject(with: JSONEncoder().encode(attachmentLimits)) as! [String: Any]
+        fields.merge(["quotaBytes": 1073741824, "usedBytes": 20, "remainingBytes": 1073741804, "maxConcurrentUploads": 2, "maxConcurrentDecodes": 1, "future": true]) { _, next in next }
+        let limits = try JSONDecoder().decode(AgentAttachmentCapabilities.self, from: JSONSerialization.data(withJSONObject: fields))
+        #expect(limits.supported); #expect(limits.remainingBytes == 1073741804)
+        #expect(limits.maxConcurrentUploads == 2); #expect(limits.maxConcurrentDecodes == 1)
+        var attachment = sampleAttachment(name: ".notes.txt")
+        attachment.workspacePath = "/data/workspace/uploads/server-id/_notes.txt"
+        try attachment.validate()
+        #expect(attachment.filename == ".notes.txt")
+        #expect(attachment.workspacePath?.hasSuffix("/_notes.txt") == true)
+    }
+    @Test func downloadAuthOpaqueIDExactBytesAndLimits() async throws {
+        let attachment = sampleAttachment("opaque/part?value#x")
+        AttachmentURLProtocol.install { request in
+            #expect(request.url!.absoluteString == "https://fixture.invalid/api/v1/agent/attachments/opaque%2Fpart%3Fvalue%23x/content")
+            #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer synthetic-test")
+            #expect(request.cachePolicy == .reloadIgnoringLocalCacheData)
+            return (200, ["Content-Length": String(originalBytes.count)], originalBytes)
+        }
+        let session = attachmentSession(); defer { session.invalidateAndCancel() }
+        let client = SybilAPIClient(configuration: .init(baseURL: URL(string: "https://fixture.invalid/api/")!, authToken: "synthetic-test"), session: session)
+        #expect(try await client.agentDownload(attachment) == originalBytes)
+        AttachmentURLProtocol.install { _ in (200, [:], originalBytes + Data([9])) }
+        await #expect(throws: AgentAttachmentIssue.self) { try await client.agentDownload(attachment) }
+        AttachmentURLProtocol.install { _ in (200, [:], Data(repeating: 1, count: originalBytes.count)) }
+        await #expect(throws: AgentAttachmentIssue.self) { try await client.agentDownload(attachment) }
+    }
+    @Test func errorCodesAndAdditiveQuotaFieldsSurvive() async throws {
+        for status in [409, 413, 422, 429, 507, 503] {
+            AttachmentURLProtocol.install { request in
+                if request.url!.path == "/api/v1/agent" { return (200, [:], try descriptorData()) }
+                return (status, status == 429 ? ["Retry-After": "2"] : [:], try JSONSerialization.data(withJSONObject: ["error": true, "message": "Actionable storage message", "statusCode": status, "code": status == 507 ? "attachment_quota_exceeded" : status == 422 ? "image_model_unsupported" : "attachments_busy", "futureByteField": 123]))
+            }
+            let session = attachmentSession(); defer { session.invalidateAndCancel() }
+            let client = SybilAPIClient(configuration: .init(baseURL: URL(string: "https://fixture.invalid")!, authToken: "synthetic-test"), session: session)
+            do { _ = try await client.agentDownload(sampleAttachment()); Issue.record("Expected failure") }
+            catch let issue as AgentAttachmentIssue {
+                #expect(issue.statusCode == status); #expect(issue.message == "Actionable storage message")
+                #expect(issue.details["futureByteField"] == .number(123))
+                if status == 507 { #expect(issue.code == "attachment_quota_exceeded") }
+                if status == 429 { #expect(issue.retryAfter == "2") }
+                if status == 422 { #expect(issue.code == "image_model_unsupported") }
+            }
+        }
+    }
+    @Test func redirectPolicyRejectsUntrustedOrigin() async throws {
+        let session = attachmentSession(); defer { session.invalidateAndCancel() }
+        let task = session.dataTask(with: URL(string: "https://fixture.invalid/api")!)
+        let policy = AgentAttachmentRedirectPolicy()
+        let response = HTTPURLResponse(url: URL(string: "https://fixture.invalid/api")!, statusCode: 302, httpVersion: nil, headerFields: [:])!
+        await withCheckedContinuation { continuation in
+            policy.urlSession(session, task: task, willPerformHTTPRedirection: response, newRequest: URLRequest(url: URL(string: "https://untrusted.invalid")!)) { request in
+                #expect(request == nil); continuation.resume()
+            }
+        }
+        task.cancel()
+    }
+    @Test @MainActor func orderedSelectionFailureRetryRemoveAndCapability() async throws {
+        let client = AttachmentTestClient(), draft = AgentAttachmentDraft()
+        draft.configure(client: client, storage: nil); draft.updateCapability(attachmentLimits)
+        await client.failNextUpload()
+        let first = try #require(draft.add(filename: "one.bin") { .init(filename: "one.bin", mimeType: "application/octet-stream", data: originalBytes) })
+        let second = try #require(draft.add(filename: "two.bin") { .init(filename: "two.bin", mimeType: "application/octet-stream", data: originalBytes) })
+        #expect(!draft.canSend)
+        #expect(await attachmentEventually { draft.items[0].state == .failed && draft.items[1].state == .ready })
+        #expect(draft.items[0].issue?.code == "attachment_quota_exceeded")
+        #expect(!draft.canSend); draft.retry(first)
+        #expect(await attachmentEventually { draft.items.allSatisfy { $0.state == .ready } })
+        #expect(draft.ready.map(\.filename) == ["one.bin", "two.bin"])
+        #expect(await client.uploadIDs() == [first, second, first])
+        #expect(draft.canSend)
+        draft.updateCapability(nil); #expect(!draft.canSend)
+        #expect(draft.ready.count == 2)
+        draft.remove(first); draft.remove(second); draft.caption = "Text still works"
+        #expect(draft.canSend)
+    }
+    @Test @MainActor func removedInflightUploadCannotReappear() async throws {
+        let client = AttachmentTestClient(), draft = AgentAttachmentDraft()
+        await client.delayUploads(.milliseconds(250))
+        draft.configure(client: client, storage: nil); draft.updateCapability(attachmentLimits)
+        let id = try #require(draft.add(filename: "remove.bin") { .init(filename: "remove.bin", mimeType: "application/octet-stream", data: originalBytes) })
+        #expect(await attachmentEventually { draft.items.first?.state == .uploading })
+        draft.remove(id)
+        try await Task.sleep(for: .milliseconds(300))
+        #expect(draft.items.isEmpty); #expect(!draft.canSend)
+    }
+    @Test @MainActor func stagedUploadAndReadyDraftSurviveRelaunch() async throws {
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        defer { try? FileManager.default.removeItem(at: root) }
+        let storage = AgentDraftStorage.file(baseURL: URL(string: "https://fixture.invalid/api")!, root: root)
+        let client = AttachmentTestClient(), first = AgentAttachmentDraft()
+        await client.failNextUpload()
+        first.configure(client: client, storage: storage); first.updateCapability(attachmentLimits); first.caption = "Keep my caption"
+        let id = try #require(first.add(filename: "original.bin") { .init(filename: "original.bin", mimeType: "application/octet-stream", data: originalBytes) })
+        #expect(await attachmentEventually { first.items.first?.state == .failed })
+        first.suspend()
+        let next = AgentAttachmentDraft(); next.configure(client: client, storage: storage); next.updateCapability(attachmentLimits)
+        #expect(next.caption == "Keep my caption"); #expect(next.items.first?.id == id)
+        next.retry(id); #expect(await attachmentEventually { next.items.first?.state == .ready })
+        #expect(await client.uploadIDs() == [id, id]); #expect(try storage.bytes(id) == originalBytes)
+        let reopened = AgentAttachmentDraft(); reopened.configure(client: client, storage: storage)
+        #expect(reopened.ready == next.ready); #expect(!reopened.canSend)
+        reopened.updateCapability(attachmentLimits); #expect(reopened.canSend)
+        reopened.clearAfterSubmission(); #expect(try storage.read().items.isEmpty)
+        #expect(throws: (any Error).self) { try storage.bytes(id) }
+    }
+    @Test @MainActor func outboxReferencesPersistBeforePostRetryAndEchoWins() async throws {
+        let client = AttachmentTestClient(), store = AttachmentTestStore(), room = SybilAgentRoom()
+        room.configure(client: client, storage: store.storage); defer { room.stop() }
+        #expect(await attachmentEventually { !room.isLoading })
+        await client.malformedReceipts(true)
+        await client.requirePersisted { store.read().first?.attachments == [sampleAttachment()] }
+        #expect(room.send("", attachments: [sampleAttachment()]))
+        #expect(await attachmentEventually { room.outbox.first?.status == "failed" })
+        let original = try #require(room.outbox.first)
+        room.retry(original.id)
+        #expect(await attachmentEventually { room.outbox.first?.status == "failed" })
+        let submitted = await client.sent()
+        #expect(submitted.count == 2); #expect(submitted.allSatisfy { $0.requestId == original.requestID && $0.attachmentIDs == [sampleAttachment().id] })
+        var echo = original.message
+        echo.content = "Attached: original.bin."
+        echo.metadata?.self = .object(["kind": .string("message"), "entryId": .number(1), "status": .string("complete"), "agentAttachments": .array([sampleAttachment().metadataValue])])
+        try room.receive(.messages(.init(conversationId: "root", messages: [echo], cursor: "1", hasMore: false)))
+        room.flush()
+        #expect(room.outbox.first?.confirmed == true); #expect(store.read().isEmpty)
+        #expect(room.messages.count == 1); #expect(room.messages.first?.agentAttachments == [sampleAttachment()])
+        #expect(room.messages.first?.createdAt == original.createdAt)
+    }
+    @Test @MainActor func failedDraftHandoffCannotPostOrCreateAnotherIdentityAfterRelaunch() async throws {
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        defer { try? FileManager.default.removeItem(at: root) }
+        let disk = AgentDraftStorage.file(baseURL: URL(string: "https://fixture.invalid/api")!, root: root)
+        let draftID = UUID().uuidString
+        let item = AgentDraftItem(filename: "original.bin", state: .ready, attachment: sampleAttachment())
+        try disk.write(.init(caption: "Keep caption and references", items: [item], id: draftID))
+        var unavailable = disk
+        unavailable.write = { snapshot in
+            if snapshot.items.isEmpty { throw AgentAttachmentIssue.local("Synthetic disk failure") }
+            try disk.write(snapshot)
+        }
+        let client = AttachmentTestClient(), store = AttachmentTestStore(), room = SybilAgentRoom()
+        room.configure(client: client, storage: store.storage, draftStorage: unavailable)
+        #expect(await attachmentEventually { !room.isLoading })
+        #expect(!room.sendComposer())
+        #expect(room.composer == "Keep caption and references")
+        #expect(room.attachmentDraft.ready == [sampleAttachment()])
+        #expect(store.read().count == 1)
+        let saved = try #require(store.read().first)
+        #expect(saved.draftID == draftID)
+        room.retry(saved.id)
+        #expect(await client.sent().isEmpty)
+        room.stop()
+        let reopened = SybilAgentRoom()
+        reopened.configure(client: client, storage: store.storage, draftStorage: disk)
+        defer { reopened.stop() }
+        #expect(await attachmentEventually { !reopened.isLoading })
+        #expect(reopened.composer.isEmpty); #expect(reopened.attachmentDraft.items.isEmpty)
+        #expect(!reopened.sendComposer())
+        reopened.retry(saved.id)
+        #expect(await attachmentEventually { reopened.outbox.first?.seenOnServer == true })
+        #expect(await client.sent().map(\.requestId) == [saved.requestID])
+        #expect(await client.sent().first?.attachmentIDs == [sampleAttachment().id])
+    }
+    @Test @MainActor func openProxyHTTP503AndSocket4503KeepReadyDraftAndOutbox() async throws {
+        for socketFailure in [false, true] {
+            let client = AttachmentTestClient(), store = AttachmentTestStore(), room = SybilAgentRoom()
+            if socketFailure { await client.blockSocket() } else { await client.blockDescriptor() }
+            let row = AgentOutboxRow(requestID: "unchanged-retry", content: "Retained caption", createdAt: Date(), attachments: [sampleAttachment()])
+            try store.storage.write([row])
+            let snapshot = AgentDraftSnapshot(caption: "Retained draft", items: [.init(filename: "original.bin", state: .ready, attachment: sampleAttachment())])
+            let draft = AgentDraftStorage(read: { snapshot }, write: { _ in }, stage: { _, _ in }, bytes: { _ in originalBytes }, remove: { _ in })
+            room.configure(client: client, storage: store.storage, draftStorage: draft)
+            #expect(await attachmentEventually { room.error?.contains(socketFailure ? "4503" : "Synthetic open proxy") == true })
+            #expect(!room.attachmentDraft.supportsAttachments)
+            #expect(room.composer == "Retained draft"); #expect(room.attachmentDraft.ready == [sampleAttachment()])
+            #expect(!room.sendComposer())
+            #expect(room.outbox.first?.requestID == "unchanged-retry")
+            #expect(store.read().first?.attachments == [sampleAttachment()])
+            #expect(await client.sent().isEmpty)
+            room.stop()
+        }
+    }
+    @Test @MainActor func mismatchedCanonicalAndQueuedEchoesNeverHideLocalReferencesOrRetry() async throws {
+        let client = AttachmentTestClient(), store = AttachmentTestStore(), room = SybilAgentRoom()
+        await client.malformedReceipts(true)
+        room.configure(client: client, storage: store.storage); defer { room.stop() }
+        #expect(await attachmentEventually { !room.isLoading })
+        let attachments = [sampleAttachment("first"), sampleAttachment("second")]
+        #expect(room.send("Original caption", attachments: attachments))
+        #expect(await attachmentEventually { room.outbox.first?.status == "failed" })
+        let row = try #require(room.outbox.first)
+        for (index, wrong) in [[], Array(attachments.reversed()), [attachments[0]]].enumerated() {
+            var message = row.message
+            message.content = "Incorrect server echo"
+            message.metadata = .object(["kind": .string("message"), "status": .string("complete"), "entryId": .number(Double(index + 1)), "agentAttachments": .array(wrong.map(\.metadataValue))])
+            try room.receive(.messages(.init(conversationId: "root", messages: [message], cursor: String(index + 1), hasMore: false)))
+            var activity = room.snapshot.room.activity
+            activity.queuedMessages = [message]
+            try room.receive(.activity("root", activity)); room.flush()
+            #expect(room.outbox.first?.confirmed == false); #expect(room.outbox.first?.seenOnServer == false)
+            #expect(room.outbox.first?.status == "failed"); #expect(room.outbox.first?.error != nil)
+            #expect(room.messages.first?.agentAttachments == attachments)
+            #expect(room.messages.first?.content == "Original caption")
+            #expect(store.read().first?.requestID == row.requestID)
+        }
+    }
+    @Test func legacyOutboxAndQueuedHistoryKeepDistinctAttachmentsAndHiddenTools() throws {
+        let row = AgentOutboxRow(requestID: "stable", content: "caption", createdAt: Date(timeIntervalSince1970: 1))
+        #expect(try JSONDecoder().decode(AgentOutboxRow.self, from: JSONEncoder().encode(row)).attachments == nil)
+        var attached = row; attached.attachments = [sampleAttachment()]
+        let restored = try JSONDecoder().decode(AgentOutboxRow.self, from: JSONEncoder().encode(attached))
+        #expect(restored.attachments == attached.attachments); #expect(restored.requestID == row.requestID)
+        var queued = restored.message; queued.metadata = .object(["kind": .string("message"), "status": .string("queued"), "agentAttachments": .array([sampleAttachment().metadataValue])])
+        var committed = queued; committed.metadata = .object(["kind": .string("message"), "status": .string("complete"), "entryId": .number(2), "agentAttachments": .array([sampleAttachment().metadataValue])])
+        let tool = Message(id: "hidden", createdAt: Date(), role: .tool, content: "raw tool", metadata: .object(["kind": .string("tool_call"), "entryId": .number(3)]))
+        var state = AgentRoomState()
+        try state.apply(.init(conversationId: "root", messages: [queued, tool], cursor: "3", hasMore: false))
+        try state.apply(.init(conversationId: "root", messages: [committed], cursor: "3", hasMore: false))
+        try state.apply(.init(conversationId: "root", messages: [queued], cursor: "2", hasMore: false))
+        #expect(state.messages.count == 2); #expect(state.cursor == "3"); #expect(state.unreadCount == 0)
+        let transcript = AgentTranscript(messages: state.messages)
+        #expect(transcript.messages.count == 1); #expect(transcript.messages[0].agentAttachments == [sampleAttachment()])
+        #expect(transcript.messages[0].attachments.isEmpty)
+    }
+}

ios/Packages/Sybil/Tests/SybilTests/AgentTests.swift

@@ -97,6 +97,161 @@ private func eventually(_ predicate: () -> Bool) async -> Bool {
 }
 
 struct AgentTests {
+    @Test @MainActor func mixedLoadedHistoryFiltersOnlyToolRows() async throws {
+        var user = agentMessage("user", entry: "1", role: .user)
+        user.content = "Explain the tool_call and tool result."
+        let call = agentMessage("call", entry: "2", role: .tool, info: ["status": .string("initiated")])
+        var reply = agentMessage("reply", entry: "3")
+        reply.content = "The search tool failed; here is what you can do."
+        // Role-only results still need hiding even without tool-call metadata.
+        var result = agentMessage("result", entry: "4", role: .tool)
+        result.metadata = nil
+        let markedCall = agentMessage("marked-call", entry: "5", info: ["kind": .string("tool_call")])
+        var plainReply = agentMessage("plain-reply", entry: "6")
+        plainReply.metadata = nil
+        let failure = agentMessage("failure", entry: "7", info: ["status": .string("failed"), "error": .string("Please try again")])
+        let terminal = agentMessage("terminal", entry: "8", role: .tool, info: ["status": .string("failed"), "error": .string("Raw tool failure"), "resultPreview": .string("Raw result")])
+        let history = [user, call, reply, result, markedCall, plainReply, failure, terminal].enumerated().map { index, message in
+            var message = message
+            message.createdAt.addTimeInterval(Double(index))
+            return message
+        }
+        let client = TestAgentClient(pages: ["0": agentPage(Array(history.dropLast()), cursor: "7", more: true), "7": agentPage([history[7]], cursor: "8")])
+        let room = SybilAgentRoom(); room.configure(client: client, storage: MemoryOutbox().storage)
+        defer { room.stop() }
+        #expect(await eventually { room.connection == "Connected" })
+        #expect(await client.requestedCursors() == ["0", "7"])
+        #expect(await client.connectedAfters() == ["8"])
+        let transcript = AgentTranscript(messages: room.messages)
+        #expect(transcript.displayed == [history[0], history[2], history[5], history[6]])
+        #expect(room.snapshot.room.messages == history)
+        #expect(room.messages.count == 8)
+        #expect(room.snapshot.room.cursor == "8")
+        #expect(room.snapshot.room.readCursor == "0")
+        #expect(room.unreadCount == 2)
+        #expect(room.snapshot.entranceIDs.isEmpty)
+        // Shared regular-chat tool metadata remains available and unchanged.
+        #expect(terminal.isToolCallLog)
+        #expect(terminal.toolCallMetadata?.resultPreview == "Raw result")
+    }
+
+    @Test func transcriptWindowsAndAnchorsUseVisibleRows() {
+        var raw: [Message] = [], visible: [Message] = []
+        for index in 1...160 {
+            var message = agentMessage("reply-\(index)", entry: "\(index * 2)")
+            message.createdAt.addTimeInterval(Double(index * 2) * 86_400)
+            var tool = agentMessage("tool-\(index)", entry: "\(index * 2 + 1)", role: .tool)
+            // Tools on separate dates must not introduce their own separators.
+            tool.createdAt = message.createdAt.addingTimeInterval(86_400)
+            raw += [message, tool]; visible.append(message)
+        }
+        let initial = AgentTranscript(messages: raw)
+        #expect(initial.startIndex == 60)
+        #expect(initial.displayed == Array(visible.suffix(100)))
+        let anchorID = initial.displayed.first?.id
+        let hidden = agentMessage("late-tool", entry: "400", role: .tool)
+        let updated = AgentTranscript(messages: raw + [hidden], startID: anchorID)
+        #expect(updated.displayed == initial.displayed)
+        let earlierID = initial.messages[max(0, initial.startIndex - 100)].id
+        let expanded = AgentTranscript(messages: raw, startID: earlierID, limit: 200)
+        #expect(expanded.displayed == visible)
+        #expect(expanded.displayed.firstIndex(where: { $0.id == anchorID }) == 60)
+        let hiddenAnchor = AgentTranscript(messages: raw, startID: "tool-160")
+        #expect(hiddenAnchor.displayed == initial.displayed)
+        let onlyTools = AgentTranscript(messages: raw.filter { $0.role == .tool })
+        #expect(onlyTools.messages.isEmpty)
+        #expect(onlyTools.displayed.isEmpty)
+        #expect(onlyTools.startIndex == 0)
+    }
+
+    @Test @MainActor func liveToolUpsertsPreserveRawHistoryCursorsAndActivity() async throws {
+        let user = agentMessage("user", entry: "1", role: .user)
+        let reply = agentMessage("reply", entry: "2")
+        let client = TestAgentClient(pages: ["0": agentPage([user, reply], cursor: "2")])
+        let room = SybilAgentRoom(); room.configure(client: client, storage: MemoryOutbox().storage)
+        defer { room.stop() }
+        #expect(await eventually { room.connection == "Connected" })
+        let queued = agentMessage("queued", entry: "0", role: .user, info: ["status": .string("queued")])
+        var activity = AgentActivity()
+        activity.isThinking = true; activity.backgroundWorkers = 2; activity.queued = 1
+        activity.queuedMessages = [queued]
+        activity.wait = .init(due: 1_800_000_000_000, reason: "Waiting for background work")
+        activity.error = "A worker needs attention"
+        try room.receive(.activity("root", activity)); room.flush()
+        #expect(await eventually { room.snapshot.isTyping })
+        let visible = AgentTranscript(messages: room.messages).displayed
+        #expect(Set(visible.map(\.id)) == ["user", "reply", "queued"])
+        let start = agentMessage("tool", entry: "3", role: .tool, info: ["status": .string("initiated"), "toolName": .string("search"), "args": .object(["query": .string("fixture")]), "startedAt": .string("start")])
+        let completed = agentMessage("tool", entry: "4", role: .tool, info: ["status": .string("completed"), "resultPreview": .string("Raw preview")])
+        let result = agentMessage("tool", entry: "5", role: .tool, info: ["status": .string("completed"), "result": .object(["matches": .number(3)])])
+        for (message, cursor) in [(start, "3"), (completed, "4"), (result, "5"), (start, "3")] {
+            try room.receive(.messages(agentPage([message], cursor: cursor))); room.flush()
+            #expect(AgentTranscript(messages: room.messages).displayed == visible)
+            #expect(room.snapshot.room.messages.count == 3)
+            #expect(room.unreadCount == 1)
+            #expect(room.snapshot.room.readCursor == "0")
+            #expect(room.snapshot.isTyping)
+            #expect(room.snapshot.room.activity == activity)
+        }
+        let tool = try #require(room.snapshot.room.messages.first(where: { $0.id == "tool" })?.toolCallMetadata)
+        #expect(tool.status == "completed")
+        #expect(tool.args == .object(["query": .string("fixture")]))
+        #expect(tool.resultPreview == "Raw preview")
+        #expect(tool.result == .object(["matches": .number(3)]))
+        #expect(tool.startedAt == "start")
+        #expect(room.snapshot.room.cursor == "5")
+        // The rendered snapshot's cursor includes hidden tool updates. A later
+        // reply must remain unread when only that captured cursor is acknowledged.
+        room.isSelected = true
+        let capturedCursor = room.snapshot.room.cursor
+        let lateReply = agentMessage("late-reply", entry: "6")
+        let lateTool = agentMessage("late-tool", entry: "7", role: .tool)
+        try room.receive(.messages(agentPage([lateReply, lateTool], cursor: "7"))); room.flush()
+        room.markRead(renderedCursor: capturedCursor)
+        #expect(await eventually { room.snapshot.room.readCursor == "5" })
+        #expect(room.snapshot.room.cursor == "7")
+        #expect(room.unreadCount == 1)
+        #expect(AgentTranscript(messages: room.messages).displayed == visible + [lateReply])
+        #expect(!room.snapshot.isTyping)
+        #expect(room.isBusy)
+        let socket = try #require(await client.latestSocket())
+        await socket.push(#"{"type":"error","error":"Room connection unavailable"}"#)
+        #expect(await eventually { room.error == "Room connection unavailable" })
+        #expect(AgentTranscript(messages: room.messages).displayed == visible + [lateReply])
+        #expect(room.snapshot.room.messages.count == 5)
+    }
+
+    @Test @MainActor func failedSendDetailsAndRetryStayVisibleWithHiddenTools() async throws {
+        let tool = agentMessage("tool", entry: "1", role: .tool)
+        let client = TestAgentClient(pages: ["0": agentPage([tool], cursor: "1")])
+        await client.setFailures(submit: true)
+        let memory = MemoryOutbox()
+        let room = SybilAgentRoom(); room.configure(client: client, storage: memory.storage)
+        defer { room.stop() }
+        #expect(await eventually { room.connection == "Connected" })
+        #expect(room.send("Please retry the search tool"))
+        #expect(await eventually { room.outbox.first?.status == "failed" })
+        let failed = try #require(AgentTranscript(messages: room.messages).displayed.first)
+        let requestID = try #require(room.outbox.first?.requestID)
+        #expect(failed.role == .user)
+        #expect(failed.content == "Please retry the search tool")
+        #expect(failed.metadata?.objectValue?["status"] == .string("failed"))
+        #expect(failed.metadata?.objectValue?["error"] == .string("Lost acknowledgement"))
+        #expect(AgentTranscript(messages: room.messages).displayed.count == 1)
+        #expect(memory.read().first?.requestID == requestID)
+        await client.setFailures()
+        room.retry(failed.id)
+        #expect(await eventually { room.outbox.first?.status == "queued" })
+        let retried = try #require(AgentTranscript(messages: room.messages).displayed.first)
+        #expect(retried.id == failed.id)
+        #expect(retried.createdAt == failed.createdAt)
+        #expect(retried.metadata?.objectValue?["status"] == .string("queued"))
+        #expect(retried.metadata?.objectValue?["error"] == nil)
+        #expect(await client.submittedIDs() == [requestID, requestID])
+        #expect(room.snapshot.room.messages == [tool])
+        #expect(room.messages.count == 2)
+    }
+
     @Test func cursorAndMalformedFrames() throws {
         #expect(try AgentCursor.normalize("00012") == "12")
         #expect(try AgentCursor.advance("9", "10") == "10")

ios/README.md

@@ -26,11 +26,73 @@ Multiple messages can be queued while the Agent works. The local outbox is saved
 atomically under Application Support before submission and is scoped to the API
 base URL. An interrupted send stays on its original bubble with **Retry**, retaining
 its request ID and timestamp across relaunch. A canonical server echo confirms it
-even if the HTTP acknowledgement is lost. Tool cards expand to show input, result,
+even if the HTTP acknowledgement is lost. Raw tool calls and results are hidden
-and error details. Attachments and model selection belong to ordinary chats.
+in the Agent transcript, including loaded history and live updates. History windows,
+date separators and scroll anchors use visible messages; raw merged history and
+cursors remain intact. Send failures, room errors and activity indicators remain
+visible. Model selection and tool cards continue to belong to ordinary chats.
 
 Agent contracts remain in `../docs/api/rest.md` and
-`../docs/api/streaming-chat.md`; this client requires no backend deployment.
+`../docs/api/streaming-chat.md`. ROOT attachments consume the coordinated v1
+contract (2026-10-14), now documented in the integrated API sources above.
+Attachment readiness requires the coordinated backend/runtime and existing public
+API bearer authentication. This iOS change does not deploy or configure them.
+
+### ROOT attachments
+
+The Agent composer exposes Files and Photo Library only when the authenticated
+descriptor advertises supported `capabilities.attachments.version == 1`. Missing,
+malformed, or unsupported capability keeps the client text-only. Ordinary chat
+attachments retain their existing inline format and behavior.
+Open-proxy HTTP 503 / WebSocket 4503 failures disable attachment selection while
+retaining draft descriptors and outbox retry identities; reconnect checks support.
+
+Files preserve their original bytes, including PDF, archives, text and HEIC files.
+Photo Library HEIC/HEIF selections are intentionally converted to bounded JPEG
+visual input with a matching `.jpg` filename. PNG/JPEG/GIF/WebP are validated as
+raster images; model input is static, with no claim of document or animation
+understanding. Safe original names supplied by the picker are retained; PhotosPicker
+may provide an export filename rather than the original Photo Library asset name.
+The production app does not request broad Photo Library access.
+
+Selection order is stable. One preparation/upload runs at a time, with per-item
+loading, upload, error, retry and removal. Sending requires every item to be ready;
+an empty caption can send ready attachments. Advertised limits are checked against
+v1 hard ceilings (8 files, 32 MiB total, 6 MiB/image, 8 MiB/file, 50 million pixels,
+16,384 pixels/axis). Quota snapshots are decoded but do not reserve space. Server
+messages/codes, quota details and Retry-After survive failures, including 409, 413,
+429 and 507. Removal cancels local work and removes the reference; it does not
+delete an uploaded server original.
+
+The caption, ordered upload UUIDs and ready descriptors are saved in a small atomic
+manifest under Application Support, scoped to the API base URL. Prepared bytes are
+staged in app-owned files (at most 8 MiB each and 32 MiB per draft); no inline bytes
+or tokens enter the outbox. Relaunch restores ready drafts and offers explicit retry
+for interrupted staged uploads with the same upload UUID. A selection interrupted
+before staging must be removed and selected again. Uploads suspend when the room
+stops; failed work does not automatically retry. Uploaded originals have no client
+expiration. After submission, the outbox owns the caption, ordered descriptors and
+stable request ID. A persisted draft identity recovers a crash during this handoff
+without creating a second send. Storage failure blocks submission rather than
+discarding a draft. Attachment receipts must acknowledge exactly the submitted IDs
+in order; matching canonical echoes still win ambiguous HTTP failures.
+
+History and queued/live messages decode only `metadata.agentAttachments` for ROOT.
+Cards retain filename, MIME, size and the optional server-provided `workspacePath`,
+which can be copied. The client never constructs a runtime path or sends one as a
+reference; leading-dot display filenames remain unchanged. Captions remain public
+text, including the server's fallback for attachment-only messages.
+
+Original downloads use the configured authenticated URLSession and API base
+(including `/api`), reject redirects, and verify exact size and SHA-256. At most two
+downloads run concurrently, with a 16 MiB in-memory cache discarded on configuration
+change. Queued/active cancellation and generation checks prevent stale previews
+from crossing configurations. Raster previews use bounded thumbnails; text previews
+are plain text, including HTML/SVG. Save/share exports exact original bytes to a
+temporary file removed when its card disappears or configuration changes. An app
+crash may leave a temporary export for normal OS temporary-directory cleanup.
+Image preview frames have fixed height to preserve scroll anchors during loading.
+Attachment modals track their own visibility without changing Quick Question state.
 
 ### Agent regression and Simulator checks
 
@@ -44,7 +106,10 @@ just screenshot build/agent-evidence/simulator.png
 ```
 
 `just test` runs reducer, cursor, outbox, presentation, shared-read and lifecycle
-regressions along with the existing app tests through Xcode on iPhone 16e.
+regressions along with attachment capability/metadata, multipart/auth/bytes/errors,
+HEIC conversion versus original-file preservation, ordered receipts, draft/outbox
+relaunch, cancellation, two-transfer concurrency and configuration isolation tests
+through Xcode on iPhone 16e.
 For interactive UI coverage, start the local fixture (Python with `aiohttp`):
 
 ```sh
@@ -68,6 +133,15 @@ admission/retry, tools, asynchronous replies, inactive sidebar unread counts,
 shared reads, reconnect/malformed replay, foreground recovery, long-history scroll
 anchors and multiline keyboard layout. The launch arguments select the fixture
 through ordinary API settings; no fixture mode is compiled into the application.
+Attachment cases exercise authenticated originals, safe text/raster display,
+history reload, capability absence and picker cancellation. The real Photo Library
+selection-to-send test is explicitly skipped: this iOS 26.5 XCTest environment has
+unreliable Photos authorization, callback isolation and synthetic-asset cleanup.
+Selection-to-send remains a manual/device pre-release check, not a validated UI
+path. The gate prevents photo mutations during the general UI suite. Synthetic
+HEIC conversion and original HEIC file preservation are covered by package tests.
+The fixture accepts multipart uploads, stable upload/message retries, structured
+errors and attachment receipts; it is not a runtime image-decoder or quota test.
 Use a fresh result-bundle path for each run. Check the same UI on iPad and with
 Simulator Reduce Motion enabled before release.
 

ios/Tests/Fixtures/agent_server.py

@@ -5,6 +5,10 @@ Run with Python + aiohttp, then xcodebuild test -scheme SybilAgentUI.
 import asyncio
 import datetime
 import json
+import hashlib
+import unicodedata
+import uuid
+from urllib.parse import quote
 from aiohttp import web
 
 sockets = set()
@@ -16,6 +20,21 @@ busy = False
 attempts = {}
 log = []
 reply_tasks = set()
+attachments = {}
+uploads = {}
+attachment_capability = True
+next_upload_error = None
+blocked_proxy = False
+transcript_comparison = False
+CAPABILITY = dict(version=1, maxCount=8, maxTotalBytes=33554432, maxImageBytes=6291456,
+                  maxFileBytes=8388608, imageMimeTypes=['image/png', 'image/jpeg', 'image/gif', 'image/webp'],
+                  maxImagePixels=50000000, maxImageDimension=16384, quotaBytes=1073741824, usedBytes=0,
+                  remainingBytes=1073741824, maxConcurrentUploads=2, maxConcurrentDecodes=1)
+
+def attachment_error(status, code, message, **fields):
+    return web.json_response(dict(error=True, message=message, statusCode=status, code=code, **fields), status=status,
+                             headers={"Retry-After": "2"} if status == 429 else None)
+
 
 def stamp():
     return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
@@ -69,7 +88,7 @@ async def reply(content):
     await broadcast(dict(type='activity', conversationId='fixture-root', activity=activity()))
 
 async def route(request):
-    global read_cursor, cursor, busy
+    global read_cursor, cursor, busy, attachment_capability, next_upload_error, blocked_proxy, transcript_comparison
     path = request.path
     log.append(dict(method=request.method, path=path, query=dict(request.query)))
     if path == '/control':
@@ -80,8 +99,21 @@ async def route(request):
                 task.cancel()
             reply_tasks.clear()
             messages.clear(); requests.clear(); attempts.clear(); cursor = 0; read_cursor = 0; busy = False
+            attachment_capability = True; next_upload_error = None; blocked_proxy = False; transcript_comparison = False
             for i in range(body.get('count', 3)):
                 message(f'History message {i + 1}: local simulator fixture.')
+        elif action == 'transcript-comparison':
+            transcript_comparison = True
+        elif action == 'capability':
+            attachment_capability = body.get('enabled', True)
+        elif action == 'upload-error':
+            next_upload_error = body
+        elif action == 'blocked-proxy':
+            blocked_proxy = body.get('enabled', True)
+        elif action == 'attachment-history':
+            selected = [attachments[key]['descriptor'] for key in body['ids']]
+            row = message(body.get('content') or 'Attached: ' + ', '.join(a['filename'] for a in selected) + '.', 'user', info={'agentAttachments': selected})
+            await broadcast(dict(type='messages', **page([row])))
         elif action == 'reply':
             await emit(body.get('content', 'Late asynchronous fixture reply'))
         elif action == 'long-tool':
@@ -102,10 +134,13 @@ async def route(request):
         return web.json_response(dict(cursor=cursor, readCursor=read_cursor, messages=messages, requests=requests, log=log))
     if path == '/api/v1/auth/session':
         return web.json_response(dict(authenticated=True, mode='token'))
+    comparison = dict(id='fade-comparison', title='Transcript fade comparison', createdAt=stamp(), updatedAt=stamp())
     if path == '/api/v1/workspace-items':
-        return web.json_response(dict(items=[], hasMore=False))
+        return web.json_response(dict(items=[dict(comparison, type='chat')] if transcript_comparison else [], hasMore=False))
     if path == '/api/v1/chats':
-        return web.json_response(dict(chats=[]))
+        return web.json_response(dict(chats=[comparison] if transcript_comparison else []))
+    if path == '/api/v1/chats/fade-comparison' and transcript_comparison:
+        return web.json_response(dict(chat=dict(comparison, messages=messages)))
     if path == '/api/v1/searches':
         return web.json_response(dict(searches=[]))
     if path == '/api/v1/models':
@@ -115,8 +150,70 @@ async def route(request):
     if path.startswith('/api/v1/agent') and path != '/api/v1/agent/ws':
         if request.headers.get('Authorization') != 'Bearer fixture-token':
             return web.json_response(dict(error='Fixture token missing'), status=401)
+        if blocked_proxy:
+            return attachment_error(503, 'attachments_unavailable', 'Synthetic proxy requires safely authenticated Agent access.')
     if path == '/api/v1/agent':
-        return web.json_response(dict(id='fixture-root', title='Sybil Agent', type='persistent-agent', model='fixture', protocol='pi-room.v1', websocket='/v1/agent/ws', activity=activity()))
+        descriptor = dict(id='fixture-root', title='Sybil Agent', type='persistent-agent', model='fixture', protocol='pi-room.v1', websocket='/v1/agent/ws', activity=activity())
+        if attachment_capability:
+            descriptor['capabilities'] = {'attachments': CAPABILITY}
+        return web.json_response(descriptor)
+    if path == '/api/v1/agent/attachments' and request.method == 'POST':
+        if not attachment_capability:
+            return attachment_error(503, 'attachments_unavailable', 'Attachments are unavailable.')
+        if next_upload_error:
+            failure = next_upload_error; next_upload_error = None
+            return attachment_error(failure.get('status', 507), failure.get('code', 'attachment_quota_exceeded'),
+                                    'Synthetic attachment storage is full; contact the operator or retry later.', **({'quotaBytes': 1073741824, 'remainingBytes': 0, 'requiredBytes': 20000} if failure.get('status', 507) == 507 else {}))
+        reader = await request.multipart()
+        parts = {}
+        while part := await reader.next():
+            if part.name not in ('file', 'uploadId') or part.name in parts:
+                return attachment_error(400, 'invalid_upload', 'Exactly one file and uploadId are required.')
+            parts[part.name] = (part.filename, part.headers.get('Content-Type'), bytes(await part.read(decode=False)))
+        if set(parts) != {'file', 'uploadId'}:
+            return attachment_error(400, 'invalid_upload', 'Missing file or uploadId.')
+        try:
+            upload_id = str(uuid.UUID(parts['uploadId'][2].decode()))
+            filename = unicodedata.normalize('NFC', parts['file'][0])
+            assert filename and len(filename.encode()) <= 255 and filename not in ('.', '..')
+            assert not any(c in '/\\' or unicodedata.category(c) == 'Cc' for c in filename)
+        except (ValueError, AssertionError, TypeError):
+            return attachment_error(400, 'invalid_upload', 'Invalid upload ID or filename.')
+        _, mime, data = parts['file']
+        mime = (mime or 'application/octet-stream').lower()
+        if len(data) > CAPABILITY['maxFileBytes']:
+            return attachment_error(413, 'attachment_limit_exceeded', 'File exceeds the upload limit.')
+        digest = hashlib.sha256(data).hexdigest()
+        identity = (filename, mime, digest)
+        if upload_id in uploads:
+            old_identity, attachment_id = uploads[upload_id]
+            if old_identity != identity:
+                return attachment_error(409, 'idempotency_conflict', 'Upload ID already belongs to another original.')
+            return web.json_response({'attachment': attachments[attachment_id]['descriptor']})
+        kind = 'file'
+        if mime in CAPABILITY['imageMimeTypes']:
+            kind = 'image'  # Synthetic fixture images are generated by the test; runtime validates decoding.
+        elif mime.startswith('text/'):
+            try:
+                if '\0' not in data.decode('utf-8-sig'):
+                    kind = 'text'
+            except UnicodeDecodeError:
+                pass
+        attachment_id = 'fixture-' + str(uuid.uuid4())
+        descriptor = dict(id=attachment_id, kind=kind, filename=filename, mimeType=mime, sizeBytes=len(data), sha256=digest,
+                          workspacePath='/data/workspace/uploads/' + attachment_id + '/' + ('_' + filename[1:] if filename.startswith('.') else filename))
+        attachments[attachment_id] = dict(descriptor=descriptor, data=data)
+        uploads[upload_id] = (identity, attachment_id)
+        return web.json_response({'attachment': descriptor}, status=201)
+    if path.startswith('/api/v1/agent/attachments/') and path.endswith('/content'):
+        attachment_id = path.removeprefix('/api/v1/agent/attachments/').removesuffix('/content')
+        stored = attachments.get(attachment_id)
+        if stored is None:
+            return attachment_error(404, 'attachment_not_found', 'The original is unavailable.')
+        descriptor = stored['descriptor']
+        mime = descriptor['mimeType'] if descriptor['kind'] == 'image' else 'text/plain' if descriptor['kind'] == 'text' else 'application/octet-stream'
+        return web.Response(body=stored['data'], content_type=mime, headers={'Cache-Control': 'private, no-store',
+                            'Content-Disposition': 'attachment; filename="original"; filename*=UTF-8\'\'' + quote(descriptor['filename'], safe=''), 'X-Content-Type-Options': 'nosniff'})
     if path == '/api/v1/agent/read-state':
         if request.method == 'PUT':
             read_cursor = max(read_cursor, int((await request.json())['cursor']))
@@ -125,13 +222,29 @@ async def route(request):
         if request.method == 'POST':
             body = await request.json()
             key, content = body['requestId'], body['content']
+            refs = body.get('attachments', [])
+            ids = [ref.get('id') for ref in refs]
+            if refs and not attachment_capability:
+                return attachment_error(503, 'attachments_unavailable', 'Attachments are unavailable.')
+            if any(set(ref) != {'id'} for ref in refs) or len(ids) != len(set(ids)) or len(ids) > 8:
+                return attachment_error(400, 'invalid_attachment', 'Invalid ordered references.')
+            if any(key not in attachments for key in ids):
+                return attachment_error(404, 'attachment_not_found', 'The attachment does not exist.')
+            if not content.strip() and not ids:
+                return attachment_error(400, 'invalid_attachment', 'Enter a caption or attach files.')
+            if key in requests and (ids or requests[key].get('attachmentIds')) and requests[key].get('_payload') != [content, ids]:
+                return attachment_error(409, 'idempotency_conflict', 'Message identity is already bound to another payload.')
             attempts[key] = attempts.get(key, 0) + 1
             if content == 'retry fixture' and attempts[key] == 1:
                 return web.json_response(dict(error='Simulated uncertain admission; retry'), status=502)
             receipt = dict(id=len(requests) + 1, status='queued', messageId=f'inbound:sybil:{key}')
+            if ids:
+                receipt['attachmentIds'] = ids
             if key not in requests:
-                requests[key] = receipt
+                requests[key] = dict(receipt, _payload=[content, ids])
-                row = message(content, 'user', id=receipt['messageId'])
+                descriptors = [attachments[key]['descriptor'] for key in ids]
+                display = content if content.strip() else 'Attached: ' + ', '.join(a['filename'] for a in descriptors) + '.'
+                row = message(display, 'user', id=receipt['messageId'], info={'agentAttachments': descriptors} if ids else None)
                 busy = True
                 await broadcast(dict(type='messages', **page([row])))
                 await broadcast(dict(type='activity', conversationId='fixture-root', activity=activity()))
@@ -141,7 +254,7 @@ async def route(request):
             if content == 'echo wins fixture':
                 await asyncio.sleep(0.3)
                 return web.json_response(dict(error='Lost HTTP acknowledgement'), status=502)
-            return web.json_response(requests[key], status=202)
+            return web.json_response({k: v for k, v in requests[key].items() if k != '_payload'}, status=202)
         after = int(request.query.get('after', 0))
         rows = [m for m in messages if m['metadata']['entryId'] > after]
         limit = min(int(request.query.get('limit', 200)), 200)
@@ -151,6 +264,9 @@ async def route(request):
         if request.query:
             return web.Response(status=400)
         socket = web.WebSocketResponse(); await socket.prepare(request)
+        if blocked_proxy:
+            await socket.close(code=4503, message=b'attachments_unavailable')
+            return socket
         auth = await socket.receive_json(timeout=5)
         if auth.get('token') != 'fixture-token' or auth.get('type') != 'auth':
             await socket.close(code=4401); return socket
@@ -172,6 +288,6 @@ async def route(request):
 
 for i in range(3):
     message(f'History message {i + 1}: local simulator fixture.')
-app = web.Application()
+app = web.Application(client_max_size=8 * 1024 * 1024 + 64 * 1024)
 app.router.add_route('*', '/{path:.*}', route)
 web.run_app(app, host='127.0.0.1', port=8799)

ios/Tests/SybilUITests/AgentUITests.swift

@@ -1,5 +1,6 @@
 import XCTest
 import UIKit
+import Photos
 
 @MainActor
 final class AgentUITests: XCTestCase {
@@ -10,7 +11,9 @@ final class AgentUITests: XCTestCase {
         app.launchArguments = ["-sybil.ios.apiBaseURL", "http://127.0.0.1:8799/api", "-sybil.ios.adminToken", "fixture-token"]
         app.launch()
         openAgent()
+        try clearComposer()
     }
+    override func tearDown() async throws { app.terminate() }
     private func openAgent() {
         if !app.buttons["agent-sidebar"].waitForExistence(timeout: 2) || !app.buttons["agent-sidebar"].isHittable {
             XCTAssertTrue(app.buttons["Show sidebar"].waitForExistence(timeout: 15))
@@ -23,6 +26,16 @@ final class AgentUITests: XCTestCase {
     private var composer: XCUIElement {
         app.textFields["agent-composer"].exists ? app.textFields["agent-composer"] : app.textViews["agent-composer"]
     }
+    private func clearComposer() throws {
+        guard let existing = composer.value as? String, !existing.isEmpty, existing != "Enter Prompt" else { return }
+        composer.tap(); composer.press(forDuration: 1)
+        let selectAll = app.descendants(matching: .any).matching(NSPredicate(format: "label == %@", "Select All")).firstMatch
+        if selectAll.waitForExistence(timeout: 2) { selectAll.tap() }
+        else { composer.typeText(String(repeating: XCUIKeyboardKey.rightArrow.rawValue, count: existing.count)) }
+        composer.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue, count: existing.count))
+        let value = composer.value as? String ?? ""
+        _ = try XCTUnwrap(value.isEmpty || value == "Enter Prompt" ? true : nil, "Clear the synthetic fixture caption before the next test")
+    }
     private func send(_ text: String) {
         composer.tap(); composer.typeText(text); app.buttons["agent-send"].tap()
     }
@@ -37,6 +50,171 @@ final class AgentUITests: XCTestCase {
         let (data, _) = try await URLSession.shared.data(for: request)
         return try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
     }
+    private func uploadOriginal(name: String, mime: String, bytes: Data) async throws -> [String: Any] {
+        let boundary = "Fixture-" + UUID().uuidString
+        let uploadID = UUID().uuidString
+        var body = Data("--\(boundary)\r\nContent-Disposition: form-data; name=\"uploadId\"\r\n\r\n\(uploadID)\r\n--\(boundary)\r\nContent-Disposition: form-data; name=\"file\"; filename=\"\(name)\"\r\nContent-Type: \(mime)\r\n\r\n".utf8)
+        body.append(bytes); body.append(Data("\r\n--\(boundary)--\r\n".utf8))
+        var request = URLRequest(url: URL(string: "http://127.0.0.1:8799/api/v1/agent/attachments")!)
+        request.httpMethod = "POST"; request.httpBody = body
+        request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")
+        request.setValue("Bearer fixture-token", forHTTPHeaderField: "Authorization")
+        let (data, response) = try await URLSession.shared.data(for: request)
+        XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 201)
+        let json = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        return try XCTUnwrap(json["attachment"] as? [String: Any])
+    }
+
+    func testAttachmentHistoryDownloadAndReload() async throws {
+        let original = Data("Synthetic original text. <script>plain text only</script>".utf8)
+        let file = try await uploadOriginal(name: "fixture-original.txt", mime: "text/plain", bytes: original)
+        let image = UIGraphicsImageRenderer(size: CGSize(width: 64, height: 48)).image { context in
+            UIColor.systemTeal.setFill(); context.fill(CGRect(x: 0, y: 0, width: 64, height: 48))
+        }
+        let photo = try await uploadOriginal(name: "fixture-image.png", mime: "image/png", bytes: try XCTUnwrap(image.pngData()))
+        let ids = [try XCTUnwrap(file["id"] as? String), try XCTUnwrap(photo["id"] as? String)]
+        try await control(["action": "attachment-history", "ids": ids, "content": "Synthetic attachments caption"])
+        XCTAssertTrue(app.staticTexts["Synthetic attachments caption"].waitForExistence(timeout: 8))
+        XCTAssertTrue(app.staticTexts["fixture-original.txt"].exists)
+        XCTAssertTrue(app.staticTexts["fixture-image.png"].exists)
+        let path = try XCTUnwrap(file["workspacePath"] as? String)
+        XCTAssertTrue(app.buttons["Copy workspace path: " + path].exists)
+        let download = app.buttons["agent-download"].firstMatch
+        if !download.isHittable { app.scrollViews.firstMatch.swipeDown() }
+        XCTAssertTrue(download.waitForExistence(timeout: 5)); download.tap()
+        XCTAssertTrue(app.buttons["Save or share original"].waitForExistence(timeout: 8))
+        XCTAssertTrue(app.staticTexts.containing(NSPredicate(format: "label CONTAINS %@", "<script>plain text only</script>")).firstMatch.exists)
+        capture("agent-attachment-original-and-preview")
+        try await control(["action": "long-tool"])
+        XCTAssertFalse(app.staticTexts["Local tool output"].exists)
+        app.terminate(); app.launch(); openAgent()
+        XCTAssertTrue(app.staticTexts["fixture-image.png"].waitForExistence(timeout: 8))
+        XCTAssertTrue(app.staticTexts["fixture-original.txt"].exists)
+        XCTAssertFalse(app.staticTexts["Local tool output"].exists)
+        capture("agent-attachment-reloaded")
+        // The real app's authenticated content request is recorded by the loopback fixture.
+        let state = try await control(["action": "state"])
+        let log = try XCTUnwrap(state["log"] as? [[String: Any]])
+        XCTAssertTrue(log.contains { ($0["path"] as? String) == "/api/v1/agent/attachments/\(ids[0])/content" })
+    }
+
+    func testAttachmentCapabilityAndPickerCancellation() async throws {
+        XCTAssertTrue(app.buttons["agent-attach"].waitForExistence(timeout: 8))
+        composer.tap(); composer.typeText("Preserved attachment draft caption")
+        app.buttons["agent-attach"].tap()
+        app.buttons["Files"].tap()
+        XCTAssertTrue(app.buttons["Cancel"].firstMatch.waitForExistence(timeout: 5))
+        app.buttons["Cancel"].firstMatch.tap()
+        XCTAssertEqual(composer.value as? String, "Preserved attachment draft caption")
+        app.buttons["agent-attach"].tap(); app.buttons["Photo Library"].tap()
+        XCTAssertTrue(app.buttons["Cancel"].firstMatch.waitForExistence(timeout: 5))
+        app.buttons["Cancel"].firstMatch.tap()
+        XCTAssertEqual(composer.value as? String, "Preserved attachment draft caption")
+        capture("agent-attachment-pickers-cancelled")
+        try await control(["action": "capability", "enabled": false])
+        app.terminate(); app.launch(); openAgent()
+        XCTAssertFalse(app.buttons["agent-attach"].exists)
+        XCTAssertEqual(composer.value as? String, "Preserved attachment draft caption")
+        try clearComposer()
+        capture("agent-text-only-capability")
+    }
+
+    func testPhotoSelectionToAttachmentOnlySend() async throws {
+        try XCTSkipIf(true, "Manual/device pre-release check: iOS 26.5 XCTest Photos authorization, callback isolation and cleanup are unreliable in this fixture. Selection-to-send is NOT validated; keep the general suite free of photo mutations.")
+        // Only synthetic assets are touched; no unrelated photo bytes are read.
+        if PHPhotoLibrary.authorizationStatus(for: .readWrite) != .authorized {
+            // XCTest's synchronous UI waits must not block the authorization request.
+            let permission = Task.detached { await PHPhotoLibrary.requestAuthorization(for: .readWrite) }
+            try await Task.sleep(for: .milliseconds(300))
+            let allow = XCUIApplication(bundleIdentifier: "com.apple.springboard").buttons.matching(
+                NSPredicate(format: "label IN %@", ["Allow Full Access", "Allow Access to All Photos", "Allow Access"])).firstMatch
+            if allow.waitForExistence(timeout: 5) { allow.tap(); _ = await permission.value }
+            else if PHPhotoLibrary.authorizationStatus(for: .readWrite) != .notDetermined { _ = await permission.value }
+        }
+        try XCTSkipUnless(PHPhotoLibrary.authorizationStatus(for: .readWrite) == .authorized,
+                          "Simulator Photos authorization \(PHPhotoLibrary.authorizationStatus(for: .readWrite).rawValue) is unavailable to \(Bundle.main.bundleIdentifier ?? "test runner")")
+        // Recover only fixtures from an interrupted test, identified by BOTH our unique
+        // date and original-filename prefix, before creating this run's asset.
+        let options = PHFetchOptions()
+        options.predicate = NSPredicate(format: "creationDate == %@", ISO8601DateFormatter().date(from: "2099-12-31T20:00:00Z")! as NSDate)
+        let previous = PHAsset.fetchAssets(with: .image, options: options)
+        let owned = previous.objects(at: IndexSet(integersIn: 0..<previous.count)).filter {
+            PHAssetResource.assetResources(for: $0).contains { $0.originalFilename.hasPrefix("sybil-attachment-ui-") }
+        }.map(\.localIdentifier)
+        if !owned.isEmpty { try await removeSyntheticPhotos(owned) }
+        let name = "sybil-attachment-ui-" + UUID().uuidString + ".png"
+        let url = FileManager.default.temporaryDirectory.appendingPathComponent(name)
+        let photo = UIGraphicsImageRenderer(size: CGSize(width: 96, height: 64)).image { context in
+            UIColor.systemPurple.setFill(); context.fill(CGRect(x: 0, y: 0, width: 96, height: 64))
+        }
+        try XCTUnwrap(photo.pngData()).write(to: url)
+        defer { try? FileManager.default.removeItem(at: url) }
+        nonisolated(unsafe) var assetID: String?
+        try await PHPhotoLibrary.shared().performChanges { @Sendable in
+            let creation = PHAssetCreationRequest.forAsset()
+            // A unique synthetic date lets us find this asset without enumerating other photos.
+            creation.creationDate = ISO8601DateFormatter().date(from: "2099-12-31T20:00:00Z")
+            let options = PHAssetResourceCreationOptions(); options.originalFilename = name
+            creation.addResource(with: .photo, fileURL: url, options: options)
+            assetID = creation.placeholderForCreatedAsset?.localIdentifier
+        }
+        let ownedID = try XCTUnwrap(assetID)
+        let identity = XCTAttachment(string: ownedID); identity.name = "synthetic-photo-owned-identifier"; identity.lifetime = .keepAlways; add(identity)
+        addTeardownBlock { try await Self.eraseSyntheticPhotos([ownedID]) }
+        do { try await exercisePhotoSelection() }
+        catch {
+            try await removeSyntheticPhotos([ownedID])
+            throw error
+        }
+        try await removeSyntheticPhotos([ownedID])
+    }
+
+    private func removeSyntheticPhotos(_ identifiers: [String]) async throws {
+        try await Self.eraseSyntheticPhotos(identifiers)
+        let evidence = XCTAttachment(string: "Removed \(identifiers.count) synthetic asset(s) by owned identifier; remaining count 0.")
+        evidence.name = "synthetic-photo-cleanup"; evidence.lifetime = .keepAlways; add(evidence)
+    }
+
+    nonisolated private static func eraseSyntheticPhotos(_ identifiers: [String]) async throws {
+        try await Task.detached {
+            let owned = PHAsset.fetchAssets(withLocalIdentifiers: identifiers, options: nil)
+            if owned.count > 0 { try await PHPhotoLibrary.shared().performChanges { PHAssetChangeRequest.deleteAssets(owned) } }
+            let remaining = PHAsset.fetchAssets(withLocalIdentifiers: identifiers, options: nil).count
+            XCTAssertEqual(remaining, 0)
+            print("Synthetic photo cleanup: \(identifiers.count) owned identifier(s), \(remaining) remaining.")
+        }.value
+    }
+
+    private func exercisePhotoSelection() async throws {
+        app.activate()
+        XCTAssertFalse(app.buttons["agent-send"].isEnabled)
+        app.buttons["agent-attach"].tap(); app.buttons["Photo Library"].tap()
+        let cell = app.descendants(matching: .any).matching(NSPredicate(format:
+            "label BEGINSWITH %@ AND NOT label CONTAINS %@", "Photo, December 31, 2099", ", Photo,")).firstMatch
+        XCTAssertTrue(cell.waitForExistence(timeout: 8))
+        cell.tap()
+        app.buttons.matching(NSPredicate(format: "label BEGINSWITH %@", "Add")).firstMatch.tap()
+        let ready = XCTNSPredicateExpectation(predicate: NSPredicate(format: "enabled == true"), object: app.buttons["agent-send"])
+        await fulfillment(of: [ready], timeout: 15)
+        XCTAssertFalse(app.buttons["agent-upload-retry"].exists)
+        capture("agent-photo-upload-ready")
+        app.buttons["agent-send"].tap()
+        let fallback = app.staticTexts.containing(NSPredicate(format: "label BEGINSWITH %@", "Attached: ")).firstMatch
+        XCTAssertTrue(fallback.waitForExistence(timeout: 12))
+        XCTAssertFalse(app.buttons["agent-retry"].exists)
+        let state = try await control(["action": "state"])
+        let requests = try XCTUnwrap(state["requests"] as? [String: [String: Any]])
+        XCTAssertEqual(requests.count, 1)
+        let submission = try XCTUnwrap(requests.values.first)
+        XCTAssertEqual((submission["_payload"] as? [Any])?.first as? String, "")
+        XCTAssertEqual((submission["attachmentIds"] as? [String])?.count, 1)
+        capture("agent-photo-attachment-only-canonical")
+        app.terminate(); app.launch(); openAgent()
+        XCTAssertTrue(app.staticTexts.containing(NSPredicate(format: "label BEGINSWITH %@", "Attached: ")).firstMatch.waitForExistence(timeout: 8))
+        XCTAssertFalse(app.buttons["agent-retry"].exists)
+        capture("agent-photo-attachment-only-reloaded")
+    }
+
     func testSendQueueToolsAndRetry() async throws {
         capture("agent-history")
         send("first fixture")
@@ -55,11 +233,11 @@ final class AgentUITests: XCTestCase {
         XCTAssertTrue(app.staticTexts.containing(NSPredicate(format: "label CONTAINS %@", "Finished: echo wins fixture")).firstMatch.waitForExistence(timeout: 12))
         XCTAssertFalse(app.buttons["agent-retry"].exists)
         composer.tap(); app.swipeDown()
-        let failures = app.buttons.matching(identifier: "agent-tool-fixture_error")
+        XCTAssertFalse(app.buttons["agent-tool-fixture_search"].exists)
-        failures.element(boundBy: failures.count - 1).tap()
+        XCTAssertFalse(app.buttons["agent-tool-fixture_error"].exists)
-        XCTAssertTrue(app.staticTexts["agent-tool-input"].waitForExistence(timeout: 3))
+        XCTAssertFalse(app.staticTexts["Inspecting the fixture"].exists)
-        XCTAssertTrue(app.staticTexts["agent-tool-error"].exists)
+        XCTAssertFalse(app.staticTexts["Fixture unavailable"].exists)
-        capture("agent-tool-error")
+        capture("agent-hidden-tools")
         let state = try await control(["action": "state"])
         XCTAssertEqual((state["requests"] as? [String: Any])?.count, 4)
     }
@@ -71,25 +249,22 @@ final class AgentUITests: XCTestCase {
         capture("agent-reduce-motion")
     }
 
-    func testExpandedToolCollapseToShortHistory() async throws {
+    func testToolResultsStayHiddenLiveAndAfterReload() async throws {
         try await control(["action": "long-tool"])
-        let tool = app.buttons["agent-tool-fixture_long"]
+        try await control(["action": "reply", "content": "Reply after a hidden tool result"])
-        XCTAssertTrue(tool.waitForExistence(timeout: 5))
+        XCTAssertTrue(app.staticTexts["Reply after a hidden tool result"].waitForExistence(timeout: 5))
-        tool.tap()
+        XCTAssertTrue(app.staticTexts["Reply after a hidden tool result"].isHittable)
-        XCTAssertTrue(app.staticTexts["agent-tool-result"].waitForExistence(timeout: 3))
+        XCTAssertFalse(app.buttons["agent-tool-fixture_long"].exists)
-        let scroll = app.scrollViews.firstMatch
+        XCTAssertFalse(app.staticTexts["Local tool output"].exists)
-        for _ in 0..<12 {
+        XCTAssertFalse(app.staticTexts["agent-tool-result"].exists)
-            if tool.isHittable { break }
-            scroll.swipeDown()
-        }
-        XCTAssertTrue(tool.isHittable)
-        tool.tap()
-        XCTAssertEqual(tool.value as? String, "Collapsed")
-        try await control(["action": "reply", "content": "Reply after collapsing a tall tool"])
-        XCTAssertTrue(app.staticTexts["Reply after collapsing a tall tool"].waitForExistence(timeout: 5))
-        XCTAssertTrue(app.staticTexts["Reply after collapsing a tall tool"].isHittable)
         XCTAssertFalse(app.buttons["agent-jump-latest"].exists)
-        capture("agent-collapsed-tool-short-history")
+        capture("agent-hidden-tool-live")
+        app.terminate(); app.launch(); openAgent()
+        XCTAssertTrue(app.staticTexts["Reply after a hidden tool result"].waitForExistence(timeout: 5))
+        XCTAssertFalse(app.buttons["agent-tool-fixture_long"].exists)
+        XCTAssertFalse(app.staticTexts["Local tool output"].exists)
+        XCTAssertFalse(app.staticTexts["agent-tool-result"].exists)
+        capture("agent-hidden-tool-history")
     }
 
     func testTabletSidebarAndInactiveChat() async throws {

ios/Tests/SybilUITests/TranscriptFadeUITests.swift

@@ -0,0 +1,138 @@
+import XCTest
+import UIKit
+
+/// Loopback-only regressions. No picker selection or external backend writes.
+@MainActor
+final class TranscriptFadeUITests: XCTestCase {
+    private let app = XCUIApplication()
+
+    override func setUp() async throws {
+        continueAfterFailure = false
+        XCUIDevice.shared.orientation = .portrait
+        try await control(["action": "reset", "count": 160])
+        try await control(["action": "transcript-comparison"])
+        app.launchArguments = ["-sybil.ios.apiBaseURL", "http://127.0.0.1:8799/api", "-sybil.ios.adminToken", "fixture-token"]
+        app.launch()
+    }
+
+    override func tearDown() async throws { app.terminate() }
+
+    private func showSidebar() {
+        if !app.buttons["agent-sidebar"].isHittable {
+            XCTAssertTrue(app.buttons["Show sidebar"].waitForExistence(timeout: 15))
+            app.buttons["Show sidebar"].tap()
+        }
+        XCTAssertTrue(app.buttons["agent-sidebar"].waitForExistence(timeout: 5))
+    }
+
+    private func openAgent() {
+        showSidebar()
+        app.buttons["agent-sidebar"].tap()
+        XCTAssertTrue(app.textFields["agent-composer"].waitForExistence(timeout: 8) || app.textViews["agent-composer"].exists)
+        XCTAssertTrue(app.staticTexts["History message 160: local simulator fixture."].waitForExistence(timeout: 8))
+    }
+
+    private var composer: XCUIElement {
+        app.textFields["agent-composer"].exists ? app.textFields["agent-composer"] : app.textViews["agent-composer"]
+    }
+
+    private var transcript: XCUIElement {
+        // The tablet sidebar is also a scroll view; select the detail by its content.
+        app.scrollViews.containing(.staticText, identifier: "History message 160: local simulator fixture.").firstMatch
+    }
+
+    private func capture(_ name: String) {
+        let attachment = XCTAttachment(screenshot: XCUIScreen.main.screenshot())
+        attachment.name = name; attachment.lifetime = .keepAlways; add(attachment)
+    }
+
+    @discardableResult private func control(_ value: [String: Any]) async throws -> [String: Any] {
+        var request = URLRequest(url: URL(string: "http://127.0.0.1:8799/control")!)
+        request.httpMethod = "POST"; request.httpBody = try JSONSerialization.data(withJSONObject: value)
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        let (data, response) = try await URLSession.shared.data(for: request)
+        XCTAssertEqual((response as? HTTPURLResponse)?.statusCode, 200)
+        return try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+    }
+
+    func testSharedHeaderFadeGeometry() async throws {
+        showSidebar()
+        let chat = app.buttons.containing(NSPredicate(format: "label CONTAINS %@", "Transcript fade comparison")).firstMatch
+        XCTAssertTrue(chat.waitForExistence(timeout: 8)); chat.tap()
+        // Normal chat is lazy and can open at either end on phone/tablet.
+        let normal = app.scrollViews.containing(NSPredicate(format: "label BEGINSWITH %@", "History message ")).firstMatch
+        XCTAssertTrue(normal.waitForExistence(timeout: 8))
+        let normalTop = normal.frame.minY
+        let first = app.staticTexts["History message 1: local simulator fixture."]
+        if first.exists && first.isHittable { normal.swipeUp(velocity: .slow) }
+        else { normal.swipeDown(velocity: .slow) }
+        capture("normal-chat-content-crossing-shared-fade")
+        XCTAssertTrue(app.buttons["Attach file"].isHittable)
+
+        openAgent()
+        let scroll = transcript
+        XCTAssertTrue(scroll.exists)
+        scroll.swipeDown(velocity: .slow)
+        XCTAssertTrue(app.buttons["agent-jump-latest"].waitForExistence(timeout: 5))
+        capture("agent-content-crossing-shared-fade")
+        XCTAssertTrue(composer.isHittable)
+        XCTAssertTrue(app.buttons["agent-attach"].isHittable)
+        XCTAssertTrue(app.buttons["agent-send"].exists)
+        // A viewport padded below the header clips bubbles before they reach its fade.
+        XCTAssertEqual(scroll.frame.minY, normalTop, accuracy: 1,
+                       "Agent must scroll beneath the same workspace header as normal chat")
+    }
+
+    func testReadingPositionUnreadAndKeyboardUnderSharedFade() async throws {
+        openAgent()
+        let scroll = transcript
+        XCTAssertTrue(app.staticTexts["History message 160: local simulator fixture."].isHittable)
+        scroll.swipeDown(velocity: .slow)
+        scroll.swipeDown(velocity: .slow)
+        XCTAssertTrue(app.buttons["agent-jump-latest"].waitForExistence(timeout: 5))
+        // Stay below the header's content clearance, where text is readable.
+        let visibleTop = scroll.frame.minY + 100
+        let anchor = try XCTUnwrap(app.staticTexts.matching(NSPredicate(format: "label BEGINSWITH %@", "History message")).allElementsBoundByIndex.first {
+            $0.isHittable && $0.frame.minY > visibleTop && $0.frame.maxY < composer.frame.minY
+        })
+        let before = anchor.frame.minY
+        let stateBefore = try await control(["action": "state"])
+        try await control(["action": "reply", "content": "Fade regression reply while reading"])
+        let unread = XCTNSPredicateExpectation(predicate: NSPredicate(format: "label CONTAINS %@", "unread"), object: app.buttons["agent-jump-latest"])
+        await fulfillment(of: [unread], timeout: 8)
+        XCTAssertEqual(anchor.frame.minY, before, accuracy: 2)
+        let stateAfter = try await control(["action": "state"])
+        XCTAssertEqual(stateAfter["readCursor"] as? Int, stateBefore["readCursor"] as? Int)
+        XCTAssertLessThan(try XCTUnwrap(stateAfter["readCursor"] as? Int), try XCTUnwrap(stateAfter["cursor"] as? Int))
+        capture("agent-fade-reading-position-and-unread")
+
+        for _ in 0..<30 {
+            if app.buttons["Load earlier messages"].isHittable { break }
+            scroll.swipeDown(velocity: .fast)
+        }
+        let load = app.buttons["Load earlier messages"]
+        XCTAssertTrue(load.isHittable)
+        let first = app.staticTexts["History message 61: local simulator fixture."]
+        let beforeLoad = first.frame.minY
+        load.tap()
+        capture("agent-fade-prepend-reading-position")
+        XCTAssertEqual(first.frame.minY, beforeLoad, accuracy: 3,
+                       "Prepending must preserve the readable row's position beneath the header")
+
+        app.buttons["agent-jump-latest"].tap()
+        let latest = app.staticTexts["Fade regression reply while reading"]
+        let followed = XCTNSPredicateExpectation(predicate: NSPredicate(format: "hittable == true"), object: latest)
+        await fulfillment(of: [followed], timeout: 5)
+        composer.tap()
+        XCTAssertTrue(latest.isHittable)
+        XCTAssertTrue(app.buttons["agent-attach"].isHittable)
+        capture("agent-fade-latest-with-keyboard")
+        // No send: this only changes a local draft, then clears it.
+        composer.typeText("Fade draft\nsecond line\nthird line")
+        XCTAssertTrue(latest.isHittable)
+        composer.typeText(String(repeating: XCUIKeyboardKey.delete.rawValue, count: "Fade draft\nsecond line\nthird line".count))
+        try await Task.sleep(for: .milliseconds(500))
+        let read = try await control(["action": "state"])
+        XCTAssertEqual(read["readCursor"] as? Int, read["cursor"] as? Int)
+    }
+}

ios/project.yml

@@ -23,6 +23,7 @@ targets:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: net.buzzert.sybil2.agent-ui-tests
         GENERATE_INFOPLIST_FILE: YES
+        INFOPLIST_KEY_NSPhotoLibraryUsageDescription: Synthetic attachment UI tests create and remove their own photo.
         TEST_TARGET_NAME: SybilApp
         SWIFT_VERSION: 6.0
 schemes:

server/src/agent-attachments.ts

@@ -0,0 +1,141 @@
+import { Readable } from 'node:stream';
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { z } from 'zod';
+import { requireAdmin } from './auth.js';
+import { env } from './env.js';
+
+export const AGENT_UPLOAD_LIMIT = 8 * 1024 * 1024 + 64 * 1024;
+export const AgentAttachmentId = z.string().regex(/^att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+export const AgentAttachmentReferences = z.array(z.object({ id: AgentAttachmentId }).strict()).max(8)
+  .refine(items => new Set(items.map(item => item.id)).size === items.length, 'Attachment IDs must be unique');
+export const AgentAttachmentDescriptor = z.object({
+  id: AgentAttachmentId, kind: z.enum(['image', 'text', 'file']), filename: z.string().min(1).max(255),
+  mimeType: z.string().min(1).max(127), sizeBytes: z.number().int().min(0).max(8 * 1024 * 1024),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/), workspacePath: z.string().startsWith('/').max(4096).optional(),
+});
+export type AgentProxyJson = (path: string, method?: string, body?: unknown, signal?: AbortSignal) => Promise<{ status: number; data: unknown }>;
+
+function apiError(statusCode: number, code: string, message: string) {
+  return Object.assign(new Error(message), { statusCode, code });
+}
+export async function requireAgentAttachments(proxyJson: AgentProxyJson, signal?: AbortSignal) {
+  if (!env.ADMIN_TOKEN) throw apiError(503, 'attachments_unavailable', 'Attachments require authenticated Sybil access.');
+  const descriptor = await proxyJson('/api/conversations/root', 'GET', undefined, signal);
+  const value = descriptor.data as { capabilities?: { attachments?: { version?: number } } } | null;
+  if (descriptor.status !== 200 || value?.capabilities?.attachments?.version !== 1)
+    throw apiError(503, 'attachments_unavailable', 'The Agent does not currently support authenticated attachments.');
+}
+
+/** Authentication precedes parsing; bounded streaming keeps concurrent upload memory bounded. */
+export async function registerAgentAttachmentRoutes(app: FastifyInstance, options: { baseUrl: string; apiKey?: string; proxyJson: AgentProxyJson }) {
+  await app.register(async routes => {
+    let uploads = 0, downloads = 0;
+    type Transfer = { controller: AbortController; release(): void };
+    const transfers = new WeakMap<FastifyRequest, Transfer>();
+    const transfer = (req: FastifyRequest) => { const value = transfers.get(req)!; value.controller.signal.throwIfAborted(); return value; };
+    routes.addHook('onRequest', async (req, reply) => {
+      reply.header('Cache-Control', 'private, no-store'); requireAdmin(req);
+      if (!options.apiKey) throw apiError(503, 'attachments_unavailable', 'Sybil Agent is not configured.');
+      const uploading = req.method === 'POST';
+      if (uploading ? uploads >= 2 : downloads >= 4) throw apiError(429, 'attachments_busy', 'Attachment transfers are busy. Retry shortly.');
+      if (uploading) uploads++; else downloads++;
+      const controller = new AbortController(); let released = false;
+      const timeout = setTimeout(() => { release(); reply.raw.destroy(); }, 60_000);
+      const release = () => {
+        if (released) return; released = true;
+        if (uploading) uploads--; else downloads--;
+        clearTimeout(timeout); controller.abort();
+        req.raw.off('aborted', release); reply.raw.off('close', release); reply.raw.off('finish', release); reply.raw.off('error', release);
+      };
+      transfers.set(req, { controller, release });
+      req.raw.once('aborted', release); reply.raw.once('close', release); reply.raw.once('finish', release); reply.raw.once('error', release);
+      if (req.raw.aborted || reply.raw.destroyed) { release(); controller.signal.throwIfAborted(); }
+      if (uploading && Number(req.headers['content-length'] || 0) > AGENT_UPLOAD_LIMIT)
+        throw apiError(413, 'attachment_limit_exceeded', 'Upload request exceeds its size limit.');
+      await requireAgentAttachments(options.proxyJson, controller.signal);
+      controller.signal.throwIfAborted();
+    });
+    routes.addHook('onResponse', async req => { transfers.get(req)?.release(); });
+    routes.setErrorHandler((error: Error & { statusCode?: number; code?: string }, _req, reply) => {
+      if (reply.raw.destroyed) return;
+      if (_req.method === 'POST') reply.header('Connection', 'close');
+      const statusCode = error.statusCode || 502;
+      const code = typeof error.code === 'string' ? error.code : undefined;
+      if (statusCode === 429) reply.header('Retry-After', '2');
+      reply.code(statusCode).send({ error: true, message: statusCode >= 500 && !code ? 'Sybil Agent is unavailable.' : error.message,
+        statusCode, code: code || 'agent_unavailable' });
+    });
+    routes.addContentTypeParser(/^multipart\/form-data(?:;|$)/i, (req, payload, done) => {
+      if (String(req.headers['content-type']).length > 512) done(apiError(400, 'invalid_upload', 'Invalid multipart content type.'));
+      else done(null, payload);
+    });
+    const json = async (response: Response) => {
+      let size = 0; const chunks: Uint8Array[] = [];
+      if (!response.body) throw apiError(502, 'invalid_upstream_response', 'The Agent returned an empty response.');
+      const reader = response.body.getReader();
+      try {
+        for (;;) { const part = await reader.read(); if (part.done) break; size += part.value.length;
+          if (size > 64 * 1024) { await reader.cancel(); throw new Error('Response too large'); } chunks.push(part.value); }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;
+      } catch { throw apiError(502, 'invalid_upstream_response', 'The Agent returned an invalid response.'); }
+      finally { reader.releaseLock(); }
+    };
+    routes.post('/v1/agent/attachments', { bodyLimit: AGENT_UPLOAD_LIMIT }, async (req, reply) => {
+      if (!(req.body instanceof Readable)) throw apiError(400, 'invalid_upload', 'A multipart/form-data upload is required.');
+      let oversized = false;
+      const incoming = req.body;
+      const { controller } = transfer(req);
+      const body = Readable.from((async function* () {
+        let count = 0;
+        for await (const chunk of incoming) {
+          count += chunk.length;
+          if (count > AGENT_UPLOAD_LIMIT) { oversized = true; throw new Error('Upload limit exceeded'); }
+          yield chunk;
+        }
+      })());
+      try {
+        const response = await fetch(new URL('/api/conversations/root/attachments', options.baseUrl), {
+          method: 'POST', headers: { Authorization: `Bearer ${options.apiKey}`, 'Content-Type': String(req.headers['content-type']) },
+          body: body as unknown as RequestInit['body'], duplex: 'half', signal: controller.signal, redirect: 'error',
+        } as RequestInit & { duplex: string });
+        const value = await json(response); controller.signal.throwIfAborted();
+        if (response.ok && (![200, 201].includes(response.status) || !AgentAttachmentDescriptor.safeParse((value as { attachment?: unknown })?.attachment).success))
+          throw apiError(502, 'invalid_upstream_response', 'The Agent returned an invalid attachment descriptor.');
+        if (response.status === 429) reply.header('Retry-After', '2');
+        return reply.code(response.status).send(value);
+      } catch (error) {
+        if (oversized) throw apiError(413, 'attachment_limit_exceeded', 'Upload request exceeds its size limit.');
+        if (error && typeof error === 'object' && 'statusCode' in error) throw error;
+        throw apiError(502, 'agent_unavailable', 'The upload could not be confirmed. Retry with the same uploadId.');
+      } finally { body.destroy(); }
+    });
+    routes.get<{ Params: { id: string } }>('/v1/agent/attachments/:id/content', async (req, reply) => {
+      if (!AgentAttachmentId.safeParse(req.params.id).success) throw apiError(404, 'attachment_not_found', 'Attachment not found.');
+      const { controller } = transfer(req);
+      let response: Response;
+      try { response = await fetch(new URL(`/api/conversations/root/attachments/${req.params.id}/content`, options.baseUrl), {
+        headers: { Authorization: `Bearer ${options.apiKey}` }, signal: controller.signal, redirect: 'error',
+      }); } catch { throw apiError(502, 'agent_unavailable', 'Sybil Agent is unavailable.'); }
+      controller.signal.throwIfAborted();
+      if (!response.ok) return reply.code(response.status).send(await json(response));
+      const length = Number(response.headers.get('content-length'));
+      const disposition = response.headers.get('content-disposition');
+      const type = response.headers.get('content-type') || '';
+      if (!response.body || !Number.isSafeInteger(length) || length < 0 || length > 8 * 1024 * 1024
+        || !disposition?.startsWith('attachment;') || !/^(image\/(png|jpeg|gif|webp)|text\/plain(?:; charset=utf-8)?|application\/octet-stream)$/.test(type)) {
+        await response.body?.cancel(); throw apiError(502, 'invalid_upstream_response', 'The Agent returned an invalid download.');
+      }
+      // Originals are bounded to 8 MiB. Verify the received length before sending a success response.
+      const reader = response.body.getReader(); let size = 0; const chunks: Uint8Array[] = [];
+      try {
+        for (;;) { const part = await reader.read(); if (part.done) break; size += part.value.length;
+          if (size > length) throw new Error('Download length mismatch'); chunks.push(part.value); }
+        if (size !== length) throw new Error('Download length mismatch');
+      } catch { await reader.cancel().catch(() => {}); throw apiError(502, 'invalid_upstream_response', 'The attachment download was incomplete.'); }
+      finally { reader.releaseLock(); }
+      controller.signal.throwIfAborted();
+      reply.header('Content-Type', type).header('Content-Length', length).header('Content-Disposition', disposition).header('X-Content-Type-Options', 'nosniff');
+      return reply.send(Buffer.concat(chunks, size));
+    });
+  });
+}

server/src/agent.ts

@@ -6,17 +6,19 @@ import { z } from 'zod';
 import { requireAdmin } from './auth.js';
 import { prisma } from './db.js';
 import { env } from './env.js';
+import { AgentAttachmentReferences, registerAgentAttachmentRoutes, requireAgentAttachments } from './agent-attachments.js';
 
 const Cursor = z.string().regex(/^\d{1,16}$/).refine(value => Number.isSafeInteger(Number(value)), 'Invalid cursor')
   .transform(value => String(Number(value)));
 const PageQuery = z.object({ after: Cursor.optional(), before: Cursor.optional(), limit: z.coerce.number().int().min(1).max(200).optional() })
   .refine(value => !(value.after && value.before), 'Use after or before, not both');
-const MessageBody = z.object({ content: z.string().min(1).max(40_000).refine(value => value.trim().length > 0, 'content is required'), requestId: z.string().min(1).max(256) });
+const MessageBody = z.object({ content: z.string().max(40_000), requestId: z.string().min(1).max(256), attachments: AgentAttachmentReferences.optional() })
+  .refine(value => value.content.trim().length > 0 || Boolean(value.attachments?.length), 'content or attachments are required');
 const ReadBody = z.object({ cursor: Cursor });
 const AuthFrame = z.object({ type: z.literal('auth'), token: z.string().nullable().optional(), after: Cursor.optional() });
 const SubscribeFrame = z.object({ type: z.literal('subscribe'), after: Cursor.optional() });
 const SubmissionReceipt = z.object({ id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  status: z.enum(['queued', 'placed', 'done', 'unanswered']), messageId: z.string() });
+  status: z.enum(['queued', 'placed', 'done', 'unanswered']), messageId: z.string(), attachmentIds: z.array(z.string()).optional() });
 
 type AgentOptions = { baseUrl?: string; apiKey?: string };
 const parse = <T>(schema: z.ZodType<T>, value: unknown): T => {
@@ -34,13 +36,26 @@ async function readState() {
 export async function registerAgentRoutes(app: FastifyInstance, options: AgentOptions = {}) {
   const baseUrl = options.baseUrl || env.SYBIL_AGENT_BASE_URL;
   const apiKey = options.apiKey ?? env.SYBIL_AGENT_API_KEY;
-  const proxyJson = async (path: string, method = 'GET', body?: unknown) => {
+  // An open development proxy must not expose a token-protected attachment runtime's
+  // history/model context using its server-side credential.
+  const guardOpenProxy = async (signal?: AbortSignal) => {
+    if (env.ADMIN_TOKEN) return;
+    try {
+      const response = await fetch(new URL('/api/conversations/root', baseUrl), {
+        headers: { Authorization: `Bearer ${apiKey}` }, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000), redirect: 'error',
+      });
+      const descriptor = await response.json() as { capabilities?: { attachments?: unknown } };
+      if (!response.ok || descriptor?.capabilities?.attachments) throw new Error('Private runtime');
+    } catch { throw Object.assign(new Error('Authenticated Sybil access is required for this Agent runtime.'), { statusCode: 503, code: 'attachments_unavailable' }); }
+  };
+  const proxyJson = async (path: string, method = 'GET', body?: unknown, signal?: AbortSignal) => {
     if (!apiKey) throw app.httpErrors.serviceUnavailable('Sybil Agent is not configured');
+    await guardOpenProxy(signal);
     let response: Response;
     try {
       response = await fetch(new URL(path, baseUrl), { method,
         headers: { Authorization: `Bearer ${apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(15_000),
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
       });
     } catch { throw app.httpErrors.badGateway('Sybil Agent is unavailable'); }
     let data: unknown;
@@ -55,7 +70,9 @@ export async function registerAgentRoutes(app: FastifyInstance, options: AgentOp
     const result = await proxyJson('/api/conversations/root');
     reply.code(result.status);
     if (result.status !== 200) return result.data;
-    return { ...result.data as object, websocket: '/v1/agent/ws' };
+    const descriptor: Record<string, unknown> = { ...result.data as Record<string, unknown>, websocket: '/v1/agent/ws' };
+    if (!env.ADMIN_TOKEN) delete descriptor.capabilities;
+    return descriptor;
   });
   app.get('/v1/agent/messages', async (req, reply) => {
     reply.header('Cache-Control', 'no-store');
@@ -71,10 +88,12 @@ export async function registerAgentRoutes(app: FastifyInstance, options: AgentOp
     reply.header('Cache-Control', 'no-store');
     requireAdmin(req);
     const body = parse(MessageBody, req.body);
+    if (body.attachments?.length) await requireAgentAttachments(proxyJson);
     const result = await proxyJson('/api/conversations/root/messages', 'POST', { ...body, channel: 'sybil', whenBusy: 'followUp', wait: false });
     if (result.status >= 200 && result.status < 300) {
       const receipt = SubmissionReceipt.safeParse(result.data);
-      if (!receipt.success || receipt.data.messageId !== `inbound:sybil:${body.requestId}`) {
+      if (!receipt.success || receipt.data.messageId !== `inbound:sybil:${body.requestId}`
+        || (body.attachments?.length && JSON.stringify(receipt.data.attachmentIds) !== JSON.stringify(body.attachments.map(item => item.id)))) {
         throw app.httpErrors.badGateway('Sybil Agent returned an invalid message receipt');
       }
     }
@@ -99,10 +118,11 @@ export async function registerAgentRoutes(app: FastifyInstance, options: AgentOp
     return readState();
   });
 
-  attachAgentSocket(app, baseUrl, apiKey);
+  await registerAgentAttachmentRoutes(app, { baseUrl, apiKey, proxyJson });
+  attachAgentSocket(app, baseUrl, apiKey, guardOpenProxy);
 }
 
-function attachAgentSocket(app: FastifyInstance, baseUrl: string, apiKey?: string) {
+function attachAgentSocket(app: FastifyInstance, baseUrl: string, apiKey: string | undefined, guardOpenProxy: () => Promise<void>) {
   const sockets = new WebSocketServer({ noServer: true, maxPayload: 16 * 1024 });
   const cleanup = new Set<() => void>();
   const upgrade = (request: IncomingMessage, socket: Duplex, head: Buffer) => {
@@ -114,7 +134,7 @@ function attachAgentSocket(app: FastifyInstance, baseUrl: string, apiKey?: strin
     if (url.search) { socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n'); return; }
     sockets.handleUpgrade(request, socket, head, browser => {
       let upstream: WebSocket | undefined;
-      let authenticated = false, disposed = false, alive = true;
+      let authenticated = false, authenticating = false, disposed = false, alive = true;
       const send = (value: unknown) => {
         if (browser.readyState !== WebSocket.OPEN) return;
         if (browser.bufferedAmount > 2 * 1024 * 1024) { browser.close(1013, 'Slow consumer; reconnect with cursor'); return; }
@@ -130,14 +150,18 @@ function attachAgentSocket(app: FastifyInstance, baseUrl: string, apiKey?: strin
       };
       cleanup.add(dispose);
       browser.on('close', dispose); browser.on('error', dispose);
-      browser.on('message', (raw, isBinary) => {
+      browser.on('message', async (raw, isBinary) => {
         try {
           if (isBinary) throw new Error('JSON text frames are required');
           const frame = JSON.parse(raw.toString());
           if (!authenticated) {
+            if (authenticating) { browser.close(4400, 'Authentication is still pending'); return; }
+            authenticating = true;
             const auth = parse(AuthFrame, frame);
             if (env.ADMIN_TOKEN && auth.token !== env.ADMIN_TOKEN) { browser.close(4401, 'Invalid token'); return; }
             if (!apiKey) { browser.close(4503, 'Sybil Agent is not configured'); return; }
+            try { await guardOpenProxy(); } catch { browser.close(4503, 'Authenticated Sybil access is required'); return; }
+            if (disposed || browser.readyState !== WebSocket.OPEN) return;
             authenticated = true; clearTimeout(authTimeout);
             const target = new URL('/api/ws', baseUrl); target.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
             upstream = new WebSocket(target, { headers: { Authorization: `Bearer ${apiKey}` }, handshakeTimeout: 10_000, maxPayload: 16 * 1024 * 1024 });

server/src/index.ts

@@ -79,6 +79,7 @@ app.setErrorHandler((err, req, reply) => {
     error: true,
     message: e.message ?? String(e),
     statusCode,
+    ...(typeof e.code === 'string' ? { code: e.code } : {}),
   });
 });
 

server/tests/agent-attachments.test.ts

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import { createServer, request as httpRequest, type ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+import test from 'node:test';
+import Fastify from 'fastify';
+import sensible from '@fastify/sensible';
+process.env.ADMIN_TOKEN = 'attachments-browser-token-test';
+process.env.DATABASE_URL = 'file:/tmp/sybil-attachment-proxy-unused.sqlite';
+const [{ registerAgentRoutes }, { env }] = await Promise.all([import('../src/agent.js'), import('../src/env.js')]);
+const auth = { authorization: `Bearer ${process.env.ADMIN_TOKEN}` }, key = 'runtime-private-test-key';
+const file = { id:'att_12345678-1234-4234-8234-123456789abc',kind:'text',filename:'résumé.txt',mimeType:'text/plain',sizeBytes:4,sha256:'a'.repeat(64),workspacePath:'/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/résumé.txt' };
+const bodies: any[] = [];
+let capable=true, badReceipt=false, errorStatus=0, uploadCalls=0;
+let holdDescriptor=false, holdDownload=false;const held:ServerResponse[]=[], closed:ServerResponse[]=[];
+const source=createServer(async(req,res)=>{
+  assert.equal(req.headers.authorization,`Bearer ${key}`);
+  const chunks: Buffer[]=[];
+  try { for await(const chunk of req) chunks.push(chunk); } catch { return; }
+  const bytes=Buffer.concat(chunks);res.setHeader('Content-Type','application/json');
+  if(req.url==='/api/conversations/root'){if(holdDescriptor){held.push(res);res.once('close',()=>closed.push(res));return;}res.end(JSON.stringify({id:'1',...(capable?{capabilities:{attachments:{version:1}}}:{})}));return;}
+  if(errorStatus){res.statusCode=errorStatus;res.end(JSON.stringify({error:true,message:'Storage quota reached',statusCode:errorStatus,code:'attachment_quota_exceeded',remainingBytes:12,quotaBytes:1024,requiredBytes:99}));return;}
+  if(req.url?.endsWith('/attachments')){uploadCalls++;assert.match(req.headers['content-type']!,/^multipart\/form-data; boundary=/);assert.ok(bytes.includes(Buffer.from('résumé.txt')));bodies.push(bytes.toString());res.statusCode=201;res.end(JSON.stringify({attachment:file}));return;}
+  if(req.url?.endsWith('/content')){if(holdDownload){held.push(res);res.once('close',()=>closed.push(res));return;}res.writeHead(200,{'Content-Type':'text/plain; charset=utf-8','Content-Length':'4','Content-Disposition':"attachment; filename=notes.txt; filename*=UTF-8''notes.txt"});res.end('data');return;}
+  if(req.method==='POST'){const body=JSON.parse(bytes.toString());bodies.push(body);res.statusCode=202;res.end(JSON.stringify({id:1,status:'queued',messageId:`inbound:sybil:${body.requestId}`,...(!badReceipt?{attachmentIds:body.attachments.map((f:any)=>f.id)}:{})}));return;}
+  res.end(JSON.stringify({conversationId:'1',messages:[{id:'inbound:sybil:send',role:'user',content:'Attached: résumé.txt.',metadata:{agentAttachments:[file]}},{id:'tool:2',role:'tool',metadata:{kind:'tool_call'}}],cursor:'2',hasMore:false}));
+});
+source.listen(0,'127.0.0.1');await once(source,'listening');
+const app=Fastify();await app.register(sensible);await registerAgentRoutes(app,{baseUrl:`http://127.0.0.1:${(source.address() as {port:number}).port}`,apiKey:key});
+await app.listen({port:0,host:'127.0.0.1'});const base=`http://127.0.0.1:${(app.server.address() as {port:number}).port}`;
+test.after(async()=>{await app.close();source.closeAllConnections();await new Promise<void>(r=>source.close(()=>r()));});
+function form(){const body=new FormData();body.append('file',new Blob(['data'],{type:'text/plain'}),'résumé.txt');body.append('uploadId','12345678-1234-4234-8234-123456789abc');return body;}
+
+test('auth precedes parsing/forwarding; capability gates old or unsafe upstream and open backend',async()=>{
+  const before=uploadCalls;
+  assert.equal((await fetch(base+'/v1/agent/attachments',{method:'POST',body:form()})).status,401);assert.equal(uploadCalls,before);
+  capable=false;assert.equal((await fetch(base+'/v1/agent/attachments',{method:'POST',headers:auth,body:form()})).status,503);
+  assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload:{content:'',requestId:'x',attachments:[{id:file.id}]}})).statusCode,503);
+  capable=true;const saved=env.ADMIN_TOKEN;env.ADMIN_TOKEN=undefined;
+  try {assert.equal((await fetch(base+'/v1/agent/attachments',{method:'POST',body:form()})).status,503);assert.equal((await app.inject({url:'/v1/agent'})).statusCode,503);assert.equal((await app.inject({url:'/v1/agent/messages'})).statusCode,503);}finally{env.ADMIN_TOKEN=saved;}
+});
+
+test('multipart forwards Unicode filename/uploadId with private auth; quota details and authenticated originals survive',async()=>{
+  const response=await fetch(base+'/v1/agent/attachments',{method:'POST',headers:auth,body:form()});assert.equal(response.status,201);assert.deepEqual(await response.json(),{attachment:file});assert.match(bodies.at(-1),/12345678-1234-4234-8234-123456789abc/);
+  errorStatus=507;try{const full=await fetch(base+'/v1/agent/attachments',{method:'POST',headers:auth,body:form()});assert.equal(full.status,507);assert.equal((await full.json() as any).remainingBytes,12);}finally{errorStatus=0;}
+  assert.equal((await fetch(base+`/v1/agent/attachments/${file.id}/content`)).status,401);
+  const download=await fetch(base+`/v1/agent/attachments/${file.id}/content`,{headers:auth});assert.equal(download.status,200);assert.equal(await download.text(),'data');assert.match(download.headers.get('cache-control')!,/no-store/);assert.equal(download.headers.get('x-content-type-options'),'nosniff');
+  assert.equal((await app.inject({url:'/v1/agent/attachments/not-an-id/content',headers:auth})).statusCode,404);
+});
+
+test('ID-only sends require matching receipts; history retains attachment metadata and raw tools',async()=>{
+  const payload={content:'',requestId:'send',attachments:[{id:file.id}]};
+  assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload})).statusCode,202);assert.deepEqual(bodies.at(-1),{...payload,channel:'sybil',whenBusy:'followUp',wait:false});
+  badReceipt=true;try{assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload})).statusCode,502);}finally{badReceipt=false;}
+  for(const attachments of [[{...file}],[{id:file.id,workspacePath:'/etc/passwd'}],[{id:file.id},{id:file.id}],Array(9).fill({id:file.id})]) assert.equal((await app.inject({method:'POST',url:'/v1/agent/messages',headers:auth,payload:{...payload,attachments}})).statusCode,400);
+  const page=(await app.inject({url:'/v1/agent/messages',headers:auth})).json();assert.deepEqual(page.messages[0].metadata.agentAttachments,[file]);assert.equal(page.messages[1].role,'tool');
+});
+
+test('proxy rejects oversized declared bodies and chunked bodies',async()=>{
+  const before=uploadCalls;
+  const large=await app.inject({method:'POST',url:'/v1/agent/attachments',headers:{...auth,'content-type':'multipart/form-data; boundary=x','content-length':String(9*1024*1024)}});assert.equal(large.statusCode,413);assert.equal(uploadCalls,before);
+  const chunks=Readable.from((async function*(){for(let i=0;i<145;i++)yield Buffer.alloc(64*1024);})());
+  const result=await fetch(base+'/v1/agent/attachments',{method:'POST',headers:{...auth,'content-type':'multipart/form-data; boundary=x'},body:chunks as unknown as RequestInit['body'],duplex:'half'} as RequestInit & {duplex:string});
+  assert.equal(result.status,413);assert.equal((await result.json() as any).code,'attachment_limit_exceeded');
+});
+
+async function eventually(check:()=>boolean){const end=Date.now()+3000;while(!check()&&Date.now()<end)await new Promise(r=>setTimeout(r,10));assert.ok(check(),'Expected cancellation to finish');}
+test('disconnect releases upload/download slots exactly once, cancels upstream and never continues after capability cancellation',async()=>{
+  const before=uploadCalls;
+  holdDescriptor=true;
+  for(let n=0;n<3;n++){
+    const expected=held.length+1,terminal=closed.length+1;
+    const req=httpRequest(base+'/v1/agent/attachments',{method:'POST',headers:{...auth,'content-type':'multipart/form-data; boundary=x'}},()=>{});req.on('error',()=>{});req.end('--x--');
+    await eventually(()=>held.length===expected);req.destroy();await eventually(()=>closed.length===terminal);
+  }
+  holdDescriptor=false;assert.equal(uploadCalls,before,'canceled capability checks never forward the upload');
+  assert.equal((await fetch(base+'/v1/agent/attachments',{method:'POST',headers:auth,body:form()})).status,201);
+  holdDownload=true;
+  for(let n=0;n<5;n++){
+    const expected=held.length+1,terminal=closed.length+1;
+    const req=httpRequest(base+`/v1/agent/attachments/${file.id}/content`,{headers:auth},()=>{});req.on('error',()=>{});req.end();
+    await eventually(()=>held.length===expected);req.destroy();await eventually(()=>closed.length===terminal);
+  }
+  holdDownload=false;assert.equal((await fetch(base+`/v1/agent/attachments/${file.id}/content`,{headers:auth})).status,200);
+});

web/public/sw.js

@@ -3,21 +3,9 @@ self.addEventListener("install", () => {
 });
 
 self.addEventListener("activate", (event) => {
-  event.waitUntil(
+  // Navigations through this worker wait for activation. Awaiting a client
-    (async () => {
+  // reload here deadlocks first visits, including the token sign-in screen.
-      await self.clients.claim();
+  event.waitUntil(self.clients.claim());
-      const windows = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
-      await Promise.all(
-        windows.map(async (client) => {
-          try {
-            await client.navigate(client.url);
-          } catch {
-            // The client may have closed while the new worker was activating.
-          }
-        })
-      );
-    })()
-  );
 });
 
 self.addEventListener("fetch", (event) => {

web/src/components/agent/agent-attachment.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "preact/hooks";
+import { Copy, Download, FileText, Image, LoaderCircle } from "lucide-preact";
+import { attachmentSize, type AgentAttachment } from "@/lib/agent-attachments";
+
+type Props = { file: AgentAttachment; download(file: AgentAttachment, signal?: AbortSignal): Promise<Blob> };
+/** Authenticated bytes only; no native credential, remote href, or public file serving. */
+export function AgentAttachmentCard({ file, download }: Props) {
+  const [preview, setPreview] = useState<string>();
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const controller = useRef<AbortController>();
+  useEffect(() => () => { controller.current?.abort(); }, []);
+  useEffect(() => () => { if (preview) URL.revokeObjectURL(preview); }, [preview]);
+  const retrieve = async (show: boolean) => {
+    if (busy) return;
+    const request = new AbortController(); controller.current = request; setBusy(true); setError(undefined);
+    try {
+      const blob = await download(file, request.signal); if (request.signal.aborted) return;
+      const url = URL.createObjectURL(blob);
+      if (show && file.kind === "image" && ["image/png", "image/jpeg", "image/gif", "image/webp"].includes(blob.type)) setPreview(url);
+      else {
+        const anchor = document.createElement("a"); anchor.href = url; anchor.download = file.filename; anchor.click();
+        setTimeout(() => URL.revokeObjectURL(url), 1000);
+      }
+    } catch (failure) { if (!request.signal.aborted) setError(failure instanceof Error ? failure.message : "Download failed."); }
+    finally { if (!request.signal.aborted) setBusy(false); }
+  };
+  return <div className="agent-attachment">
+    <div className="agent-attachment__title"><FileText size={15} /><span>{file.filename}</span><small>{attachmentSize(file.sizeBytes)}</small></div>
+    {file.workspacePath ? <div className="agent-attachment__path"><code title={file.workspacePath}>{file.workspacePath}</code><button type="button" aria-label={`Copy path for ${file.filename}`} title={copied ? "Copied" : "Copy workspace path"} onClick={() => { void navigator.clipboard.writeText(file.workspacePath!).then(() => setCopied(true)).catch(() => setError("Could not copy the path.")); }}><Copy size={13} /></button></div> : null}
+    {preview ? <img className="agent-attachment__preview" src={preview} alt={file.filename} /> : null}
+    <div className="agent-attachment__actions">
+      {file.kind === "image" ? <button type="button" disabled={busy} onClick={() => preview ? setPreview(undefined) : void retrieve(true)}><Image size={13} />{preview ? "Hide preview" : "Preview"}</button> : null}
+      <button type="button" disabled={busy} onClick={() => void retrieve(false)}>{busy ? <LoaderCircle size={13} className="animate-spin" /> : <Download size={13} />}Download</button>
+    </div>
+    {error ? <span className="agent-attachment__error" role="alert">{error} Retry using the buttons above.</span> : null}
+  </div>;
+}

web/src/components/agent/agent-conversation.css

@@ -194,83 +194,6 @@
   color:hsl(189 79% 75%);
 }
 
-.agent-room__tool {
-  margin:0 0 0 35px;
-  max-width:calc(89% - 35px);
-  border:1px solid hsl(256 35% 47%/.23);
-  border-radius:11px;
-  background:hsl(246 32% 12%/.56);
-  color:hsl(255 26% 75%);
-  font-size:11px;
-}
-
-.agent-room__tool summary {
-  display:flex;
-  align-items:center;
-  gap:9px;
-  min-height:37px;
-  padding:8px 11px;
-  cursor:pointer;
-  list-style:none;
-}
-
-.agent-room__tool summary::-webkit-details-marker {
-  display:none;
-}
-
-.agent-room__tool-icon {
-  display:grid;
-  place-items:center;
-  color:hsl(267 69% 76%);
-}
-
-.agent-room__tool-title {
-  min-width:0;
-  flex:1;
-  overflow:hidden;
-  text-overflow:ellipsis;
-  white-space:nowrap;
-  text-transform:capitalize;
-}
-
-.agent-room__tool-state {
-  color:hsl(254 18% 51%);
-  font-size:9px;
-}
-
-.agent-room__tool.is-running .agent-room__tool-state {
-  color:hsl(184 54% 72%);
-}
-
-.agent-room__tool.is-failed .agent-room__tool-state {
-  color:hsl(351 71% 76%);
-}
-
-.agent-room__tool-chevron {
-  color:hsl(255 20% 52%);
-  transition:transform .15s;
-}
-
-.agent-room__tool[open] .agent-room__tool-chevron {
-  transform:rotate(180deg);
-}
-
-.agent-room__tool-body {
-  padding:0 11px 11px;
-}
-
-.agent-room__tool-body pre {
-  max-height:210px;
-  overflow:auto;
-  white-space:pre-wrap;
-  overflow-wrap:anywhere;
-  font:10px/1.6 ui-monospace,monospace;
-  margin:8px 0 0;
-  padding:9px;
-  border-radius:6px;
-  background:hsl(239 42% 6%/.7);
-}
-
 .agent-room__typing,.agent-room__waiting {
   display:flex;
   align-items:center;
@@ -503,10 +426,6 @@
     height:23px;
     border-radius:8px;
   }
-  .agent-room__tool {
-    margin-left:30px;
-    max-width:calc(96% - 30px);
-  }
   .agent-room__typing,.agent-room__waiting {
     margin-left:30px;
     font-size:10px;
@@ -536,3 +455,24 @@
     transition:none!important;
   }
 }
+
+.agent-room__attach { display: grid; place-items: center; align-self: end; width: 38px; height: 46px; color: #c4b5fd; border-radius: 12px; }
+.agent-room__attach:hover { background: #a78bfa22; }
+.agent-room__uploads { display: flex; flex-wrap: wrap; gap: 8px; padding: 8px 0; }
+.agent-room__upload { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; max-width: 100%; padding: 9px 12px; border: 1px solid #a78bfa44; border-radius: 12px; background: #211b36; font-size: 12px; }
+.agent-room__upload strong { display: block; overflow-wrap: anywhere; font-weight: 500; }
+.agent-room__upload small { color: #c4b5fd; }
+.agent-room__upload button { padding: 5px; color: #ddd6fe; }
+.agent-room__upload-path { flex-basis: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 10px; color: #b9a7d1; }
+.agent-attachment { margin-top: 10px; padding: 10px; border: 1px solid #a78bfa44; border-radius: 10px; background: #0e0a1933; font-size: 12px; min-width: 0; }
+.agent-attachment__title { display: flex; align-items: center; gap: 6px; }
+.agent-attachment__title span { overflow-wrap: anywhere; }
+.agent-attachment__title small { margin-left: auto; white-space: nowrap; opacity: .7; }
+.agent-attachment__path { display: flex; gap: 6px; margin-top: 6px; }
+.agent-attachment__path code { min-width: 0; overflow-wrap: anywhere; font-size: 10px; opacity: .75; }
+.agent-attachment__path button { flex-shrink: 0; }
+.agent-attachment__actions { display: flex; gap: 14px; margin-top: 8px; }
+.agent-attachment__actions button { display: flex; align-items: center; gap: 5px; color: #ddd6fe; }
+.agent-attachment__actions button:disabled { opacity: .5; }
+.agent-attachment__preview { display: block; max-height: 260px; max-width: 100%; margin-top: 8px; border-radius: 6px; }
+.agent-attachment__error { display: block; width: 100%; color: #fda4af; font-size: 12px; margin-top: 5px; }

web/src/components/agent/agent-conversation.tsx

@@ -1,9 +1,12 @@
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
-import { ArrowDown, ChevronDown, Clock3, LoaderCircle, Menu, RefreshCw, SendHorizontal, WifiOff, Wrench } from "lucide-preact";
+import { ArrowDown, Clock3, LoaderCircle, Menu, Paperclip, X, RefreshCw, SendHorizontal, WifiOff } from "lucide-preact";
 import type { Message } from "@/lib/api";
 import type { AgentRoomHookResult } from "@/hooks/use-agent-room";
+import { agentTranscriptMessages } from "@/lib/agent-room-presentation";
 import { MarkdownContent } from "@/components/markdown/markdown-content";
 import { Button } from "@/components/ui/button";
+import { agentAttachments, attachmentSize } from "@/lib/agent-attachments";
+import { AgentAttachmentCard } from "./agent-attachment";
 import "./agent-conversation.css";
 
 type Props = {
@@ -46,30 +49,7 @@ function toolName(value: unknown) {
   return typeof value === "string" ? value.replace(/_/g, " ") : "Tool";
 }
 
-function AgentToolCard({ message }: { message: Message }) {
+function AgentBubble({ message, animate, onRetry, download }: { message: Message; animate: boolean; onRetry: (id: string) => void; download: AgentRoomHookResult["downloadAttachment"] }) {
-  const info = metadata(message);
-  const active = info.status === "initiated";
-  const failed = info.status === "failed";
-  const title = toolName(info.toolName || message.name);
-  const preview = typeof info.resultPreview === "string" ? info.resultPreview : typeof info.error === "string" ? info.error : "";
-  return (
-    <details className={`agent-room__tool${active ? " is-running" : ""}${failed ? " is-failed" : ""}`} data-agent-message-id={message.id}>
-      <summary>
-        <span className="agent-room__tool-icon"><Wrench size={14} aria-hidden="true" /></span>
-        <span className="agent-room__tool-title">{title}</span>
-        <span className="agent-room__tool-state">{active ? "Running" : failed ? "Failed" : "Done"}</span>
-        <ChevronDown className="agent-room__tool-chevron" size={14} aria-hidden="true" />
-      </summary>
-      <div className="agent-room__tool-body">
-        {info.args && typeof info.args === "object" ? <pre aria-label="Tool input">{JSON.stringify(info.args, null, 2)}</pre> : null}
-        {preview ? <pre aria-label={failed ? "Tool error" : "Tool result"}>{preview}</pre> : null}
-        {!info.args && !preview ? <p>{active ? "This tool is still running." : "No additional details."}</p> : null}
-      </div>
-    </details>
-  );
-}
-
-function AgentBubble({ message, animate, onRetry }: { message: Message; animate: boolean; onRetry: (id: string) => void }) {
   const own = message.role === "user";
   const info = metadata(message);
   const status = typeof info.status === "string" ? info.status : "complete";
@@ -81,7 +61,9 @@ function AgentBubble({ message, animate, onRetry }: { message: Message; animate:
       <div className="agent-room__message-content">
         <div className={`message-bubble${own ? " message-bubble--user" : ""}`}>
           {own ? <p className="agent-room__plain-message">{message.content}</p> : <MarkdownContent markdown={message.content} openLinksInNewTab />}
+          {agentAttachments(message.metadata).map(file => <AgentAttachmentCard key={file.id} file={file} download={download} />)}
         </div>
+        {own && failed && typeof info.error === "string" ? <div className="agent-attachment__error" role="alert">{info.error}</div> : null}
         <div className="agent-room__message-meta">
           <span>{own ? "You" : "Sybil"}</span>
           {date ? <time dateTime={message.createdAt} title={date.toLocaleString()}>{timeFormat.format(date)}</time> : null}
@@ -100,6 +82,16 @@ function AgentBubble({ message, animate, onRetry }: { message: Message; animate:
 export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Props) {
   const [draft, setDraft] = useState(savedDraft);
   const draftRef = useRef(draft);
+  const [uploadError, setUploadError] = useState<string>();
+  const pickerRef = useRef<HTMLInputElement>(null);
+  const reselectRef = useRef<HTMLInputElement>(null);
+  const reselectId = useRef<string>();
+  const uploads = room.uploadQueue.snapshot();
+  const pendingUploads = uploads.some(file => file.status !== "ready");
+  const addFiles = (files: Iterable<File>) => {
+    try { room.uploadQueue.add(files); setUploadError(undefined); } catch (error) { setUploadError(error instanceof Error ? error.message : String(error)); }
+  };
+  const removeFile = (id: string) => { try { room.uploadQueue.remove(id); setUploadError(undefined); } catch (error) { setUploadError(String(error)); } };
   const seenMessageIdsRef = useRef(new Set(room.messages.map(message => message.id)));
   const enteringMessageIdsRef = useRef(new Set<string>());
   const animatedEntryIdsRef = useRef(new Set<string>());
@@ -245,34 +237,35 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
   };
   const submit = () => {
     const content = draftRef.current.trim();
-    if (!content) return;
+    if ((!content && !uploads.length) || pendingUploads || (uploads.length && !room.attachmentCapability)) return;
-    const delivery = room.sendMessage(content);
+    let attachments;
-    updateDraft("");
+    try { attachments = room.uploadQueue.ready(); } catch (error) { setUploadError(String(error)); return; }
-    jumpToLatest();
+    const delivery = room.sendMessage(content, attachments, () => { updateDraft(""); setUploadError(undefined); jumpToLatest(); });
-    void delivery.catch(() => {});
+    void delivery.catch(error => { if (draftRef.current === content) setUploadError(error instanceof Error ? error.message : String(error)); });
     textareaRef.current?.focus();
   };
 
   const messages = useMemo(() => {
+    const transcript = agentTranscriptMessages(room.messages);
     let previousDay = "";
-    for (const message of room.messages) {
+    for (const message of transcript) {
-      if (!seenMessageIdsRef.current.has(message.id) && historyReadyRef.current && !room.isLoading && message.role !== "tool") {
+      if (!seenMessageIdsRef.current.has(message.id) && historyReadyRef.current && !room.isLoading) {
         enteringMessageIdsRef.current.add(message.id);
       }
       seenMessageIdsRef.current.add(message.id);
     }
     if (!room.isLoading) historyReadyRef.current = true;
-    return room.messages.filter(message => message.role !== "system").map(message => {
+    return transcript.map(message => {
       const date = dateOf(message.createdAt), day = dayKey(date), separator = previousDay !== day;
       previousDay = day;
       return (
         <div className="agent-room__entry" key={message.id} data-agent-entry-id={message.id}>
           {separator ? <div className="agent-room__day"><span>{dayLabel(date)}</span></div> : null}
-          {message.role === "tool" ? <AgentToolCard message={message} /> : <AgentBubble message={message} animate={enteringMessageIdsRef.current.has(message.id)} onRetry={retryMessage} />}
+          <AgentBubble message={message} animate={enteringMessageIdsRef.current.has(message.id)} onRetry={retryMessage} download={room.downloadAttachment} />
         </div>
       );
     });
-  }, [room.messages, room.isLoading, room.retryMessage]);
+  }, [room.messages, room.isLoading, room.retryMessage, room.downloadAttachment]);
 
   const activity = room.activity;
   const running = room.isTyping;
@@ -327,21 +320,42 @@ export function AgentConversation({ room, onOpenSidebar, isVisible = true }: Pro
         {!atBottom ? <button className="agent-room__jump" onClick={jumpToLatest}><ArrowDown size={15} /><span>{room.unreadCount ? `${room.unreadCount} new message${room.unreadCount === 1 ? "" : "s"}` : "Jump to latest"}</span></button> : null}
       </div>
 
-      <div className="agent-room__composer-area">
+      <div className="agent-room__composer-area"
+        onDragOver={event => { if (room.attachmentCapability && event.dataTransfer?.types.includes("Files")) event.preventDefault(); }}
+        onDrop={event => { if (room.attachmentCapability && event.dataTransfer?.files.length) { event.preventDefault(); addFiles(event.dataTransfer.files); } }}>
         <div className="agent-room__composer-inner">
           {room.error ? <div className="agent-room__error" role="alert"><WifiOff size={15} /><span>{room.error}</span><button onClick={room.retry}>Retry</button></div> : null}
+          {uploadError ? <div className="agent-room__error" role="alert">{uploadError}</div> : null}
+          <input ref={reselectRef} type="file" hidden aria-label="Reselect attachment" onChange={event => {
+            const file = event.currentTarget.files?.[0], id = reselectId.current; event.currentTarget.value = "";
+            if (file && id) void room.uploadQueue.reselect(id, file).then(() => setUploadError(undefined)).catch(error => setUploadError(error instanceof Error ? error.message : String(error)));
+          }} />
+          {uploads.length ? <div className="agent-room__uploads" aria-label="Selected attachments">{uploads.map(row => <div className="agent-room__upload" key={row.uploadId}>
+            <div><strong>{row.filename}</strong><small>{attachmentSize(row.sizeBytes)} · <span role="status">{row.status === "ready" ? "Uploaded" : row.status === "uploading" ? "Uploading…" : row.status === "waiting" ? "Waiting…" : row.status === "reselect" ? "Reselect file" : "Upload failed"}</span></small></div>
+            {row.status === "reselect" ? <button type="button" onClick={() => { reselectId.current = row.uploadId; reselectRef.current?.click(); }}>Reselect file</button> : null}
+            {row.status === "failed" ? <button type="button" onClick={() => room.uploadQueue.retry(row.uploadId)}>Retry upload</button> : null}
+            <button type="button" aria-label={`Remove ${row.filename}`} onClick={() => removeFile(row.uploadId)}><X size={15} /></button>
+            {row.error ? <span className="agent-attachment__error" role="alert">{row.error}</span> : null}
+            {row.attachment?.workspacePath ? <code className="agent-room__upload-path" title={row.attachment.workspacePath}>{row.attachment.workspacePath}</code> : null}
+          </div>)}</div> : null}
           <form className="agent-room__composer" onSubmit={event => { event.preventDefault(); submit(); }}>
+            {room.attachmentCapability ? <>
+              <input ref={pickerRef} type="file" multiple hidden aria-label="Choose attachments" onChange={event => { if (event.currentTarget.files) addFiles(event.currentTarget.files); event.currentTarget.value = ""; }} />
+              <button type="button" className="agent-room__attach" aria-label="Attach files" title="Attach files (8 files, 32 MiB total)" onClick={() => pickerRef.current?.click()}><Paperclip size={19} /></button>
+            </> : null}
             <textarea
               ref={textareaRef}
               value={draft}
               rows={1}
+              maxLength={40000}
+              onPaste={event => { if (room.attachmentCapability && event.clipboardData?.files.length) { event.preventDefault(); addFiles(event.clipboardData.files); } }}
               onInput={event => updateDraft(event.currentTarget.value)}
               onKeyDown={event => { if (event.key === "Enter" && !event.shiftKey && !event.isComposing) { event.preventDefault(); submit(); } }}
               placeholder="Message Sybil Agent…"
               aria-label="Message Sybil Agent"
               enterkeyhint="send"
             />
-            <button type="submit" className="agent-room__send" disabled={!draft.trim()} aria-label="Send message"><SendHorizontal size={19} /></button>
+            <button type="submit" className="agent-room__send" disabled={(!draft.trim() && !uploads.length) || pendingUploads || Boolean(uploads.length && !room.attachmentCapability)} aria-label="Send message"><SendHorizontal size={19} /></button>
           </form>
         </div>
       </div>

web/src/components/auth/auth-screen.tsx

@@ -26,7 +26,7 @@ export function AuthScreen({ authTokenInput, setAuthTokenInput, isSigningIn, aut
           </div>
           <div>
             <h1 className="text-lg font-semibold text-violet-50">Sign in to Sybil</h1>
-            <p className="mt-1 text-sm text-muted-foreground">Use your backend admin token.</p>
+            <p className="mt-1 text-sm text-muted-foreground">Enter your admin token.</p>
           </div>
         </div>
 
@@ -34,28 +34,27 @@ export function AuthScreen({ authTokenInput, setAuthTokenInput, isSigningIn, aut
           className="space-y-3"
           onSubmit={(event) => {
             event.preventDefault();
-            void onSignIn(authTokenInput.trim() || null);
+            const token = authTokenInput.trim();
+            if (token) void onSignIn(token);
           }}
         >
           <Input
             type="password"
             autoComplete="off"
+            aria-label="Admin token"
             placeholder="ADMIN_TOKEN"
+            required
             value={authTokenInput}
             onInput={(event) => setAuthTokenInput(event.currentTarget.value)}
             disabled={isSigningIn}
             className="bg-[hsl(235_48%_6%_/_0.84)] text-violet-50"
           />
-          <Button className="w-full" type="submit" disabled={isSigningIn}>
+          <Button className="w-full" type="submit" disabled={isSigningIn || !authTokenInput.trim()}>
             {isSigningIn ? "Signing in..." : "Sign in"}
           </Button>
-          <Button className="w-full" type="button" variant="secondary" disabled={isSigningIn} onClick={() => void onSignIn(null)}>
-            Continue without token
-          </Button>
         </form>
 
-        {authError ? <p className="mt-3 text-sm text-red-600">{authError}</p> : null}
+        {authError ? <p role="alert" className="mt-3 text-sm text-red-600">{authError}</p> : null}
-        <p className="mt-3 text-xs text-muted-foreground">If `ADMIN_TOKEN` is set in `/server/.env`, token login is required.</p>
       </div>
     </div>
   );

web/src/hooks/use-agent-room.ts

@@ -9,11 +9,17 @@ import {
 import { AGENT_OUTBOX_STORAGE_KEY, createAgentOptimisticOutbox } from "@/lib/agent-optimistic-outbox";
 import { createAgentRoomPresenter } from "@/lib/agent-room-presentation";
 
+import { AGENT_ATTACHMENT_DRAFT_KEY, createAgentUploadQueue, type AgentAttachment, type AgentAttachmentCapability } from "@/lib/agent-attachments";
+
 export type AgentRoomConnection = "connecting" | "connected" | "reconnecting" | "offline";
 export type AgentRoomHookResult = {
   messages: Message[]; activity: AgentActivity | null; unreadCount: number;
   connection: AgentRoomConnection; error: string | null; isLoading: boolean; isTyping: boolean;
-  sendMessage(content: string): Promise<void>; retryMessage(messageId: string): Promise<void>; markRead(): void; retry(): void;
+  attachmentCapability?: AgentAttachmentCapability;
+  uploadAttachment(file: File, uploadId: string, signal: AbortSignal): Promise<AgentAttachment>;
+  downloadAttachment(file: AgentAttachment, signal?: AbortSignal): Promise<Blob>;
+  uploadQueue: ReturnType<typeof createAgentUploadQueue>;
+  sendMessage(content: string, attachments?: AgentAttachment[], onPersisted?: () => void): Promise<void>; retryMessage(messageId: string): Promise<void>; markRead(): void; retry(): void;
 };
 const errorText = (error: unknown) => error instanceof Error ? error.message : String(error);
 
@@ -23,10 +29,24 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
   const room = view.room;
   const current = useRef(room);
   const [connection, setConnection] = useState<AgentRoomConnection>("offline");
+  const [attachmentCapability, setAttachmentCapability] = useState<AgentAttachmentCapability>();
   const [error, setError] = useState<string | null>(null);
   const [isLoading, setLoading] = useState(enabled);
   const [revision, setRevision] = useState(0);
   const client = useRef<AgentRoomClient | null>(null);
+  const [, renderUploads] = useState(0);
+  const capabilityRef = useRef(attachmentCapability); capabilityRef.current = enabled ? attachmentCapability : undefined;
+  const uploadQueue = useRef<ReturnType<typeof createAgentUploadQueue> | null>(null);
+  if (!uploadQueue.current) uploadQueue.current = createAgentUploadQueue({
+    capability: () => capabilityRef.current,
+    upload: (file, id, signal) => { if (!client.current) throw new Error("Agent connection is unavailable."); return client.current.upload(file, id, signal); },
+    changed: () => renderUploads(n => n + 1),
+    storage: {
+      read: () => { try { return JSON.parse(sessionStorage.getItem(AGENT_ATTACHMENT_DRAFT_KEY) || "null"); } catch { return null; } },
+      write: rows => { try { sessionStorage.setItem(AGENT_ATTACHMENT_DRAFT_KEY, JSON.stringify(rows)); } catch { throw new Error("Could not save attachment retry details. Allow session storage before uploading."); } },
+    },
+  });
+  useEffect(() => () => uploadQueue.current?.dispose(), []);
   const mark = useRef<((cursor: string) => void) | null>(null);
   const [outboxRevision, setOutboxRevision] = useState(0);
   const update = useCallback((change: (state: AgentRoomState) => AgentRoomState) => {
@@ -36,9 +56,9 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
   if (!outbox.current) {
     const stored = (key: string) => { try { return JSON.parse(sessionStorage.getItem(key) || "null"); } catch { return null; } };
     outbox.current = createAgentOptimisticOutbox({
-      submit: (content, requestId) => {
+      submit: (content, requestId, attachments) => {
         if (!client.current) throw new Error("Agent connection is unavailable.");
-        return client.current.submit(content, requestId);
+        return client.current.submit(content, requestId, attachments);
       },
       changed: () => setOutboxRevision(value => value + 1),
       storage: {
@@ -60,7 +80,7 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
 
   useEffect(() => {
     if (!enabled) {
-      client.current = null; mark.current = null;
+      client.current = null; mark.current = null; setAttachmentCapability(undefined);
       update(() => createAgentRoomState()); setLoading(false); setConnection("offline"); setError(null);
       return;
     }
@@ -112,7 +132,7 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
     }, controller.signal);
     const refreshActivity = async () => {
       const descriptor = await api.descriptor(controller.signal);
-      if (active) presenter.push({ type: "activity", conversationId: descriptor.id, activity: descriptor.activity });
+      if (active) { setAttachmentCapability(descriptor.capabilities?.attachments?.version === 1 ? descriptor.capabilities.attachments : undefined); presenter.push({ type: "activity", conversationId: descriptor.id, activity: descriptor.activity }); }
     };
 
     const connect = () => {
@@ -214,9 +234,17 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
     // here would incorrectly mark a socket message that has not rendered yet.
     mark.current?.(renderedCursor);
   }, [enabled, isLoading, renderedCursor]);
-  const sendMessage = useCallback(async (content: string) => {
+  const sendMessage = useCallback(async (content: string, attachments?: AgentAttachment[], onPersisted?: () => void) => {
     if (!enabled || !outbox.current) throw new Error("Agent connection is unavailable.");
-    await outbox.current.send(content);
+    await outbox.current.send(content, attachments, () => { uploadQueue.current!.clear(); onPersisted?.(); });
+  }, [enabled]);
+  const uploadAttachment = useCallback((file: File, uploadId: string, signal: AbortSignal) => {
+    if (!enabled || !client.current) return Promise.reject(new Error("Agent connection is unavailable."));
+    return client.current.upload(file, uploadId, signal);
+  }, [enabled]);
+  const downloadAttachment = useCallback((file: AgentAttachment, signal?: AbortSignal) => {
+    if (!enabled || !client.current) return Promise.reject(new Error("Agent connection is unavailable."));
+    return client.current.download(file, signal);
   }, [enabled]);
   const retryMessage = useCallback(async (messageId: string) => {
     if (!enabled || !outbox.current) throw new Error("Agent connection is unavailable.");
@@ -225,5 +253,5 @@ export function useAgentRoom(enabled: boolean): AgentRoomHookResult {
   const retry = useCallback(() => { setRevision(value => value + 1); }, []);
   const messages = useMemo(() => outbox.current?.display(agentDisplayMessages(room)) || agentDisplayMessages(room), [room.messages, room.activity, outboxRevision]);
   return { messages: enabled ? messages : [], activity: room.activity, unreadCount: agentUnreadCount(room), connection, error, isLoading,
-    isTyping: enabled && view.isTyping, sendMessage, retryMessage, markRead, retry };
+    attachmentCapability, uploadQueue: uploadQueue.current!, uploadAttachment, downloadAttachment, isTyping: enabled && view.isTyping, sendMessage, retryMessage, markRead, retry };
 }

web/src/hooks/use-session-auth.ts

@@ -18,8 +18,11 @@ function persistToken(token: string | null) {
 }
 
 function normalizeAuthError(message: string) {
-  if (message.includes("missing bearer token") || message.includes("invalid bearer token")) {
+  if (message.includes("invalid bearer token")) {
-    return "Authentication failed. Enter the ADMIN_TOKEN configured in server/.env.";
+    return "Incorrect token. Please try again.";
+  }
+  if (message.includes("missing bearer token")) {
+    return "Enter your admin token.";
   }
   return message;
 }
@@ -43,10 +46,10 @@ export function useSessionAuth() {
     persistToken(tokenCandidate);
   };
 
-  const handleAuthFailure = (message: string) => {
+  const handleAuthFailure = (message: string | null) => {
     setIsAuthenticated(false);
     setAuthMode(null);
-    setAuthError(normalizeAuthError(message));
+    setAuthError(message ? normalizeAuthError(message) : null);
     setAuthToken(null);
     persistToken(null);
   };
@@ -81,7 +84,8 @@ export function useSessionAuth() {
         await completeSessionCheck(token);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        handleAuthFailure(message);
+        // A first visit without a token is an invitation to sign in, not a failed attempt.
+        handleAuthFailure(!token && message.includes("missing bearer token") ? null : message);
       } finally {
         setIsCheckingSession(false);
       }

web/src/lib/agent-attachments.ts

@@ -0,0 +1,117 @@
+/** Agent descriptors are independent of ordinary chat's inline attachment schema. */
+export type AgentAttachment = {
+  id: string; kind: "image" | "text" | "file"; filename: string; mimeType: string;
+  sizeBytes: number; sha256: string; workspacePath?: string;
+};
+export type AgentAttachmentCapability = {
+  version: 1; maxCount: number; maxTotalBytes: number; maxImageBytes: number; maxFileBytes: number;
+  imageMimeTypes: string[]; quotaBytes: number; usedBytes: number; remainingBytes: number;
+  maxConcurrentUploads: number; maxConcurrentDecodes: number;
+};
+export function parseAgentAttachment(value: unknown): AgentAttachment {
+  const item = value as AgentAttachment | null;
+  if (!item || !/^att_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(item.id)
+    || !["image", "text", "file"].includes(item.kind) || typeof item.filename !== "string" || !item.filename
+    || typeof item.mimeType !== "string" || !Number.isSafeInteger(item.sizeBytes) || item.sizeBytes < 0 || item.sizeBytes > 8 * 1024 * 1024
+    || typeof item.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(item.sha256)
+    || (item.workspacePath !== undefined && (typeof item.workspacePath !== "string" || !item.workspacePath.startsWith("/"))))
+    throw new Error("Agent returned an invalid attachment descriptor.");
+  return { id: item.id, kind: item.kind, filename: item.filename, mimeType: item.mimeType, sizeBytes: item.sizeBytes, sha256: item.sha256,
+    ...(item.workspacePath ? { workspacePath: item.workspacePath } : {}) };
+}
+export function agentAttachments(metadata: unknown): AgentAttachment[] {
+  const values = (metadata as { agentAttachments?: unknown } | null)?.agentAttachments;
+  if (!Array.isArray(values) || values.length > 8) return [];
+  try { return values.map(parseAgentAttachment); } catch { return []; }
+}
+export function attachmentCaption(content: string, files: AgentAttachment[]): string {
+  return content.trim() ? content : `Attached: ${files.map(file => file.filename).join(", ")}.`;
+}
+export function attachmentSize(bytes: number): string { return bytes < 1024 ? `${bytes} B` : bytes < 1024 ** 2 ? `${Math.ceil(bytes / 1024)} KiB` : `${(bytes / 1024 ** 2).toFixed(1)} MiB`; }
+export const AGENT_ATTACHMENT_DRAFT_KEY = "sybil.agent.attachment-draft.v1";
+export type AgentUpload = {
+  uploadId: string; filename: string; sizeBytes: number; mimeType: string; sha256?: string; file?: File;
+  status: "waiting" | "uploading" | "ready" | "failed" | "reselect"; attachment?: AgentAttachment; error?: string;
+};
+export type AgentUploadStorage = { read(): unknown; write(rows: Omit<AgentUpload, "file">[]): void };
+
+/** One active transfer. Durable identities/descriptors survive navigation and reload; bytes stay in memory. */
+export function createAgentUploadQueue(options: {
+  capability(): AgentAttachmentCapability | undefined;
+  upload(file: File, uploadId: string, signal: AbortSignal): Promise<AgentAttachment>;
+  changed(): void; storage?: AgentUploadStorage; newId?: () => string;
+}) {
+  const rows = new Map<string, AgentUpload>();
+  let running: { id: string; controller: AbortController } | undefined, disposed = false;
+  const persist = () => options.storage?.write([...rows.values()].map(({ file: _file, ...row }) => ({ ...row })));
+  const publish = () => { if (!disposed) options.changed(); };
+  const save = () => { if (disposed) return; try { persist(); } catch { /* Pre-transfer persist below is mandatory. Already-uploaded identities remain in memory. */ } publish(); };
+  const restored = options.storage?.read();
+  if (Array.isArray(restored)) for (const value of restored.slice(0, 8)) {
+    if (!value || typeof value.uploadId !== "string" || !/^[a-f0-9-]{36}$/i.test(value.uploadId)
+      || typeof value.filename !== "string" || typeof value.mimeType !== "string" || !Number.isSafeInteger(value.sizeBytes) || value.sizeBytes < 0 || value.sizeBytes > 8 * 1024 * 1024) continue;
+    try {
+      const attachment = value.attachment ? parseAgentAttachment(value.attachment) : undefined;
+      rows.set(value.uploadId, { uploadId: value.uploadId, filename: value.filename, sizeBytes: value.sizeBytes, mimeType: value.mimeType,
+        ...(typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256) ? { sha256: value.sha256 } : {}),
+        ...(attachment ? { attachment, status: "ready" } : { status: "reselect", error: "Reselect the same file to resume this upload. Its retry ID has been retained." }) });
+    } catch { /* Ignore invalid storage, never turn it into a server path/reference. */ }
+  }
+  const digest = async (file: File) => [...new Uint8Array(await crypto.subtle.digest("SHA-256", await file.arrayBuffer()))].map(n => n.toString(16).padStart(2, "0")).join("");
+  const pump = () => {
+    if (disposed || running) return;
+    const row = [...rows.values()].find(row => row.status === "waiting" && row.file);
+    if (!row) return;
+    const controller = new AbortController(); running = { id: row.uploadId, controller }; row.status = "uploading"; publish();
+    void (async () => {
+      row.sha256 ||= await digest(row.file!);
+      if (rows.get(row.uploadId) !== row || controller.signal.aborted) return;
+      // Persist the upload identity AND original byte hash before any network request.
+      persist();
+      const value = await options.upload(row.file!, row.uploadId, controller.signal);
+      if (rows.get(row.uploadId) !== row || controller.signal.aborted) return;
+      const attachment = parseAgentAttachment(value);
+      if (attachment.sha256 !== row.sha256 || attachment.sizeBytes !== row.sizeBytes || attachment.filename !== row.filename.normalize("NFC"))
+        throw new Error("The uploaded file receipt does not match this file. Retry to confirm.");
+      row.attachment = attachment; row.status = "ready"; delete row.error;
+    })().catch(error => {
+      if (rows.get(row.uploadId) !== row || controller.signal.aborted) return;
+      row.status = "failed"; row.error = error instanceof Error ? error.message : String(error);
+    }).finally(() => { running = undefined; save(); pump(); });
+  };
+  return {
+    add(files: Iterable<File>) {
+      const cap = options.capability(); if (!cap || cap.version !== 1) throw new Error("Attachments are not available on this Agent.");
+      const selected = Array.from(files);
+      if (rows.size + selected.length > Math.min(8, cap.maxCount)) throw new Error("Attach at most 8 files per message.");
+      if ([...rows.values()].reduce((n, r) => n + r.sizeBytes, 0) + selected.reduce((n, f) => n + f.size, 0) > Math.min(32 * 1024 * 1024, cap.maxTotalBytes))
+        throw new Error("Attachments exceed 32 MiB per message.");
+      for (const file of selected) {
+        const image = cap.imageMimeTypes.includes(file.type);
+        const limit = image ? Math.min(6 * 1024 * 1024, cap.maxImageBytes) : Math.min(8 * 1024 * 1024, cap.maxFileBytes);
+        if (file.size > limit) throw new Error(`${file.name} exceeds the ${image ? "6" : "8"} MiB file limit.`);
+      }
+      const added = selected.map(file => ({ uploadId: (options.newId || (() => crypto.randomUUID()))(), file, filename: file.name, sizeBytes: file.size, mimeType: file.type, status: "waiting" as const }));
+      for (const row of added) rows.set(row.uploadId, row);
+      try { persist(); } catch (error) { for (const row of added) rows.delete(row.uploadId); throw error; }
+      publish(); pump();
+    },
+    async reselect(id: string, file: File) {
+      const row = rows.get(id); if (!row || row.status !== "reselect") return;
+      if (file.name !== row.filename || file.size !== row.sizeBytes || file.type !== row.mimeType) throw new Error("Choose the same filename, type and size to resume this upload.");
+      const hash = await digest(file);
+      if (row.sha256 && row.sha256 !== hash) throw new Error("The selected file has different contents. Choose the original file or remove this attachment.");
+      if (rows.get(id) !== row) return;
+      row.sha256 = hash; row.file = file; row.status = "waiting"; delete row.error; persist(); publish(); pump();
+    },
+    remove(id: string) { const row = rows.get(id); rows.delete(id); try { persist(); } catch (error) { if (row) rows.set(id, row); throw error; } if (running?.id === id) running.controller.abort(); publish(); },
+    retry(id: string) { const row = rows.get(id); if (row?.status === "failed") { row.status = row.file ? "waiting" : "reselect"; delete row.error; save(); pump(); } },
+    snapshot(): AgentUpload[] { return [...rows.values()].map(row => ({ ...row })); },
+    ready(): AgentAttachment[] {
+      if ([...rows.values()].some(row => row.status !== "ready")) throw new Error("Wait for uploads, reselect or retry failed files, or remove them before sending.");
+      return [...rows.values()].map(row => row.attachment!);
+    },
+    clear() { rows.clear(); running?.controller.abort(); save(); },
+    dispose() { disposed = true; running?.controller.abort(); try { persist(); } catch { /* Existing stored retry IDs remain usable. */ } },
+  };
+}

web/src/lib/agent-optimistic-outbox.ts

@@ -1,10 +1,11 @@
 import type { Message } from "./api";
+import { agentAttachments, attachmentCaption, parseAgentAttachment, type AgentAttachment } from "./agent-attachments.ts";
 
 export const AGENT_OUTBOX_STORAGE_KEY = "sybil.agent.optimistic-outbox.v1";
 export type AgentDeliveryStatus = "sending" | "queued" | "complete" | "failed" | "unconfirmed";
 export type AgentOutboxRow = {
   id: string; requestId: string; content: string; createdAt: string;
-  status: AgentDeliveryStatus; error?: string; seenOnServer: boolean; confirmed: boolean;
+  attachments?: AgentAttachment[]; status: AgentDeliveryStatus; error?: string; seenOnServer: boolean; confirmed: boolean;
 };
 export type AgentOutboxStorage = {
   read(): unknown; write(rows: AgentOutboxRow[]): void;
@@ -20,7 +21,7 @@ const validRequestId = (value: unknown): value is string => typeof value === "st
 
 /** Local rows use the server's identity from their first render through final echo. */
 export function createAgentOptimisticOutbox(options: {
-  submit(content: string, requestId: string): Promise<Receipt>;
+  submit(content: string, requestId: string, attachments?: AgentAttachment[]): Promise<Receipt>;
   storage: AgentOutboxStorage;
   changed(): void;
   newId?: () => string;
@@ -40,12 +41,14 @@ export function createAgentOptimisticOutbox(options: {
   const restored = options.storage.read();
   if (Array.isArray(restored)) {
     for (const value of restored.slice(0, 100)) {
-      if (!value || typeof value.content !== "string" || !value.content.trim() || !validRequestId(value.requestId)) continue;
+      if (!value || typeof value.content !== "string" || (!value.content.trim() && !value.attachments?.length) || !validRequestId(value.requestId)) continue;
+      let attachments: AgentAttachment[] = [];
+      try { if (value.attachments !== undefined) { if (!Array.isArray(value.attachments) || value.attachments.length > 8) continue; attachments = value.attachments.map(parseAgentAttachment); } } catch { continue; }
       const time = typeof value.createdAt === "string" && Number.isFinite(Date.parse(value.createdAt)) ? value.createdAt : timestamp();
       latestTime = Math.max(latestTime, Date.parse(time));
       const status: AgentDeliveryStatus = ["failed", "queued", "complete", "unconfirmed"].includes(value.status) ? value.status : "unconfirmed";
       const row: AgentOutboxRow = { id: idFor(value.requestId), requestId: value.requestId, content: value.content, createdAt: time,
-        status, seenOnServer: Boolean(value.seenOnServer), confirmed: false,
+        ...(attachments.length ? { attachments } : {}), status, seenOnServer: Boolean(value.seenOnServer), confirmed: false,
         ...(typeof value.error === "string" && value.error ? { error: value.error.slice(0, 240) } : {}) };
       rows.set(row.id, row);
     }
@@ -78,7 +81,8 @@ export function createAgentOptimisticOutbox(options: {
   };
   const saveBestEffort = () => { try { persist(); } catch { /* Existing receipt IDs stay in memory; acknowledged messages remain sent. */ } };
   const publish = () => options.changed();
-  const dispatch = (row: AgentOutboxRow): Promise<void> => {
+  const matches = (row: AgentOutboxRow, message: Message) => !row.attachments?.length || JSON.stringify(agentAttachments(message.metadata).map(file => file.id)) === JSON.stringify(row.attachments.map(file => file.id));
+  const dispatch = (row: AgentOutboxRow, onPersisted?: () => void): Promise<void> => {
     const running = inFlight.get(row.id);
     if (running) return running;
     if (row.confirmed || row.seenOnServer) return Promise.resolve();
@@ -92,9 +96,10 @@ export function createAgentOptimisticOutbox(options: {
       row.status = "failed"; row.error = errorText(error); publish();
       return Promise.reject(error);
     }
+    onPersisted?.();
     // Both durable local storage and the visible row exist before POST begins.
     publish();
-    const pending = Promise.resolve().then(() => options.submit(row.content, row.requestId)).then(receipt => {
+    const pending = Promise.resolve().then(() => options.submit(row.content, row.requestId, row.attachments)).then(receipt => {
       if (receipt.messageId && receipt.messageId !== row.id) throw new Error("Agent returned a different message identity.");
       if (!row.confirmed) {
         row.seenOnServer = true;
@@ -115,20 +120,21 @@ export function createAgentOptimisticOutbox(options: {
   // their newly assigned identity/time must survive the next reload too.
   saveBestEffort();
   return {
-    send(content: string): Promise<void> {
+    send(content: string, attachments: AgentAttachment[] = [], onPersisted?: () => void): Promise<void> {
-      if (!content.trim()) return Promise.reject(new Error("Enter a message."));
+      if (!content.trim() && !attachments.length) return Promise.reject(new Error("Enter a message."));
       const requestId = newId();
-      const row: AgentOutboxRow = { id: idFor(requestId), requestId, content, createdAt: timestamp(), status: "sending", seenOnServer: false, confirmed: false };
+      const row: AgentOutboxRow = { id: idFor(requestId), requestId, content, ...(attachments.length ? { attachments: attachments.map(parseAgentAttachment) } : {}), createdAt: timestamp(), status: "sending", seenOnServer: false, confirmed: false };
       rows.set(row.id, row);
-      return dispatch(row);
+      return dispatch(row, onPersisted);
     },
     retry(messageId: string): Promise<void> {
       const row = rows.get(messageId);
       return row ? dispatch(row) : Promise.reject(new Error("This message is no longer pending."));
     },
     reconcile(room: RoomMessages): void {
-      const committed = new Map(room.messages.map(message => [message.id, message]));
+      const compatible = (message: Message) => { const row = rows.get(message.id); return !row || matches(row, message); };
-      const queued = new Set((room.activity?.queuedMessages || []).map(message => message.id));
+      const committed = new Map(room.messages.filter(compatible).map(message => [message.id, message]));
+      const queued = new Set((room.activity?.queuedMessages || []).filter(compatible).map(message => message.id));
       let changed = false;
       for (const row of rows.values()) {
         if (committed.has(row.id)) {
@@ -143,7 +149,7 @@ export function createAgentOptimisticOutbox(options: {
       if (changed) { saveBestEffort(); publish(); }
     },
     display(serverMessages: readonly Message[]): Message[] {
-      const displayed = new Map(serverMessages.map(message => {
+      const displayed = new Map(serverMessages.filter(message => { const row = rows.get(message.id); return !row || matches(row, message); }).map(message => {
         const row = rows.get(message.id);
         if (!row) return [message.id, message] as const;
         const serverInfo = info(message);
@@ -155,8 +161,8 @@ export function createAgentOptimisticOutbox(options: {
         const echo = confirmedEchoes.get(row.id);
         if (row.confirmed && !echo) continue;
         displayed.set(row.id, echo ? { ...echo, createdAt: row.createdAt } : {
-          id: row.id, createdAt: row.createdAt, role: "user", content: row.content, name: "buzzert",
+          id: row.id, createdAt: row.createdAt, role: "user", content: row.attachments?.length ? attachmentCaption(row.content, row.attachments) : row.content, name: "buzzert",
-          metadata: { kind: "message", status: row.status, channel: "sybil", requestId: row.requestId, ...(row.error ? { error: row.error } : {}) },
+          metadata: { kind: "message", status: row.status, channel: "sybil", requestId: row.requestId, ...(row.attachments?.length ? { agentAttachments: row.attachments } : {}), ...(row.error ? { error: row.error } : {}) },
         });
       }
       return [...displayed.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));

web/src/lib/agent-room-presentation.ts

@@ -1,6 +1,11 @@
 import type { AgentRoomEvent, AgentRoomState } from './agent-room';
 import type { Message } from './api';
 
+/** Select transcript rows only; keep tool entries in room state for replay and activity. */
+export function agentTranscriptMessages(messages: readonly Message[]): Message[] {
+  return messages.filter(message => message.role !== 'system' && message.role !== 'tool');
+}
+
 type Scheduler = {
   now(): number;
   schedule(callback: () => void, delay: number): unknown;

web/src/lib/agent-room.ts

@@ -1,4 +1,5 @@
 import type { Message } from "./api";
+import { parseAgentAttachment, type AgentAttachment, type AgentAttachmentCapability } from "./agent-attachments.ts";
 
 export type AgentActivity = {
   state: "idle" | "thinking" | "tool" | "waiting" | "error";
@@ -16,7 +17,7 @@ export type AgentMessagesPage = {
 };
 export type AgentDescriptor = {
   id: string; title: string; model: string; activity: AgentActivity;
-  websocket: string; protocol: string;
+  websocket: string; protocol: string; capabilities?: { attachments?: AgentAttachmentCapability };
 };
 export type AgentReadState = { cursor: string; updatedAt: string | null };
 export type AgentRoomState = {
@@ -126,7 +127,7 @@ export function agentAuthFrame(token: string | null, cursor: string): string {
   return JSON.stringify({ type: "auth", token, after: normalizeAgentCursor(cursor) });
 }
 
-export type AgentSubmission = { id: number; status: "queued" | "placed" | "done" | "unanswered"; messageId: string };
+export type AgentSubmission = { id: number; status: "queued" | "placed" | "done" | "unanswered"; messageId: string; attachmentIds?: string[] };
 export type AgentRoomClientOptions = { baseUrl?: string; token?: () => string | null; fetch?: typeof globalThis.fetch };
 export class AgentRoomClient {
   private readonly baseUrl: string;
@@ -141,7 +142,7 @@ export class AgentRoomClient {
     const headers = new Headers(init.headers);
     const token = this.token();
     if (token) headers.set("Authorization", `Bearer ${token}`);
-    if (init.body !== undefined) headers.set("Content-Type", "application/json");
+    if (init.body !== undefined && !(init.body instanceof FormData)) headers.set("Content-Type", "application/json");
     const response = await this.fetcher(`${this.baseUrl}/v1/agent${path}`, { ...init, headers });
     let value: unknown;
     try { value = await response.json(); }
@@ -160,15 +161,30 @@ export class AgentRoomClient {
   markRead(cursor: string, signal?: AbortSignal): Promise<AgentReadState> {
     return this.request("/read-state", { method: "PUT", body: JSON.stringify({ cursor: normalizeAgentCursor(cursor) }), signal });
   }
-  async submit(content: string, requestId: string): Promise<AgentSubmission> {
+  async submit(content: string, requestId: string, attachments: AgentAttachment[] = []): Promise<AgentSubmission> {
-    const receipt = object(await this.request<unknown>("/messages", { method: "POST", body: JSON.stringify({ content, requestId }) }));
+    const receipt = object(await this.request<unknown>("/messages", { method: "POST", body: JSON.stringify({ content, requestId, ...(attachments.length ? { attachments: attachments.map(({ id }) => ({ id })) } : {}) }) }));
     // An HTTP success alone does not acknowledge delivery. Keep the original
     // outbox receipt key retryable if a proxy or upstream returns malformed data.
     if (!receipt || typeof receipt.id !== "number" || !Number.isSafeInteger(receipt.id) || receipt.id <= 0
       || typeof receipt.status !== "string" || !["queued", "placed", "done", "unanswered"].includes(receipt.status)
-      || receipt.messageId !== `inbound:sybil:${requestId}`) throw new Error("Agent API returned an invalid message receipt. Retry to confirm delivery.");
+      || receipt.messageId !== `inbound:sybil:${requestId}`
+      || (attachments.length && JSON.stringify(receipt.attachmentIds) !== JSON.stringify(attachments.map(file => file.id)))) throw new Error("Agent API returned an invalid message receipt. Retry to confirm delivery.");
     return receipt as AgentSubmission;
   }
+  async upload(file: File, uploadId: string, signal?: AbortSignal): Promise<AgentAttachment> {
+    const body = new FormData(); body.append("uploadId", uploadId); body.append("file", file, file.name);
+    const value = await this.request<{ attachment: unknown }>("/attachments", { method: "POST", body, signal });
+    return parseAgentAttachment(value.attachment);
+  }
+  async download(attachment: AgentAttachment, signal?: AbortSignal): Promise<Blob> {
+    const file = parseAgentAttachment(attachment), headers = new Headers(), token = this.token();
+    if (token) headers.set("Authorization", `Bearer ${token}`);
+    const response = await this.fetcher(`${this.baseUrl}/v1/agent/attachments/${encodeURIComponent(file.id)}/content`, { headers, signal, cache: "no-store", redirect: "error" });
+    if (!response.ok) { const error = await response.json().catch(() => null); throw new Error(error?.message || "Attachment download failed."); }
+    const blob = await response.blob();
+    if (blob.size !== file.sizeBytes || blob.size > 8 * 1024 * 1024) throw new Error("Attachment download was incomplete.");
+    return blob;
+  }
   websocketUrl(pageUrl: string): string {
     const url = new URL(`${this.baseUrl}/v1/agent/ws`, pageUrl);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";

web/tests/agent-attachments.browser.mjs

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+// Run against a local Vite server with an existing Playwright/Chromium installation:
+// PLAYWRIGHT_MODULE=/path/to/playwright-core/index.mjs CHROME_EXECUTABLE=/path/to/chrome
+// WEB_TEST_URL=http://127.0.0.1:5192 node tests/agent-attachments.browser.mjs
+// Every API and Agent socket is mocked; this does not contact the deployed runtime.
+const { chromium } = await import(process.env.PLAYWRIGHT_MODULE || 'playwright-core');
+const target = new URL(process.env.WEB_TEST_URL || 'http://127.0.0.1:5192/');
+assert.ok(target.protocol === 'http:' && ['localhost','127.0.0.1','[::1]'].includes(target.hostname), 'Use a loopback development server');
+const browser=await chromium.launch({executablePath:process.env.CHROME_EXECUTABLE || undefined,headless:true,
+  ...(process.env.BROWSER_NO_SANDBOX === '1' ? {args:['--no-sandbox']} : {})});
+const context=await browser.newContext({viewport:{width:1200,height:900},permissions:['clipboard-write']});
+await context.addInitScript(()=>localStorage.setItem('sybil_admin_token','browser-fixture-token'));
+const page=await context.newPage(), errors=[], uploads=[], sends=[], downloads=[];
+page.on('pageerror',e=>errors.push(e.stack || e.message));
+const cap={version:1,maxCount:8,maxTotalBytes:33554432,maxImageBytes:6291456,maxFileBytes:8388608,imageMimeTypes:['image/png','image/jpeg','image/gif','image/webp'],quotaBytes:1073741824,usedBytes:0,remainingBytes:1073741824,maxConcurrentUploads:2,maxConcurrentDecodes:1};
+const idle={state:'idle',isThinking:false,queued:0,backgroundWorkers:0,tools:[],queuedMessages:[]};
+let failedUpload=true, failedSend=true, live, cursor=0;const history=[];
+const image=Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a2ioAAAAASUVORK5CYII=','base64');
+const attachment=(name='notes.txt')=>({id:`att_12345678-1234-4234-8234-${name==='picture.png'?'123456789abd':'123456789abc'}`,filename:name,mimeType:name==='picture.png'?'image/png':'text/plain',kind:name==='picture.png'?'image':'text',sizeBytes:name==='picture.png'?image.length:4,sha256:createHash('sha256').update(name==='picture.png'?image:Buffer.from('data')).digest('hex'),workspacePath:`/data/workspace/uploads/test/${name}`});
+await page.route('**/api/**',async route=>{
+ const req=route.request(),url=new URL(req.url()),p=url.pathname,m=req.method();let value;
+ if(p.startsWith('/api/v1/agent'))assert.equal(req.headers().authorization,'Bearer browser-fixture-token');
+ if(p.endsWith('/attachments')&&m==='POST'){
+  const body=req.postDataBuffer().toString();uploads.push(body);
+  if(failedUpload){failedUpload=false;await route.fulfill({status:507,json:{message:'Storage quota reached',code:'attachment_quota_exceeded'}});return;}
+  await route.fulfill({status:201,json:{attachment:attachment(body.includes('picture.png')?'picture.png':'notes.txt')}});return;
+ }
+ if(p.endsWith('/content')){downloads.push(req.url());await route.fulfill({contentType:p.includes('789abd')?'image/png':'text/plain',body:p.includes('789abd')?image:'data'});return;}
+ if(p.endsWith('/agent/messages')&&m==='POST'){
+  const body=req.postDataJSON();sends.push(body);
+  if(failedSend){failedSend=false;await route.fulfill({status:503,json:{message:'Temporarily unavailable'}});return;}
+  const files=(body.attachments||[]).map(f=>attachment(f.id.endsWith('abd')?'picture.png':'notes.txt'));
+  const row={id:`inbound:sybil:${body.requestId}`,role:'user',createdAt:new Date().toISOString(),content:body.content||`Attached: ${files.map(f=>f.filename).join(', ')}.`,metadata:{kind:'message',status:'complete',entryId:++cursor,agentAttachments:files}};history.push(row);
+  live?.send(JSON.stringify({type:'messages',conversationId:'1',messages:[row],cursor:String(cursor),beforeCursor:String(cursor),hasMore:false}));
+  await route.fulfill({status:202,json:{id:cursor,status:'queued',messageId:row.id,attachmentIds:files.map(f=>f.id)}});return;
+ }
+ if(p.endsWith('/agent/messages'))value={conversationId:'1',messages:history,cursor:String(cursor),beforeCursor:null,hasMore:false};
+ else if(p.endsWith('/read-state'))value={cursor:String(cursor),updatedAt:null};
+ else if(p.endsWith('/agent'))value={id:'1',title:'Sybil Agent',activity:idle,capabilities:{attachments:cap},protocol:'pi-room.v1',websocket:'/v1/agent/ws'};
+ else if(p.includes('session'))value={mode:'token',authenticated:true};
+ else if(p.endsWith('/tools')||p.endsWith('/chat-tools'))value={tools:[]};
+ else if(p.endsWith('/models'))value={models:[],providers:{}};
+ else if(p.includes('stream'))value=[];
+ else value=[];
+ await route.fulfill({json:value});
+});
+await page.routeWebSocket('**/api/v1/agent/ws',socket=>{live=socket;socket.onMessage(raw=>{if(JSON.parse(String(raw)).type==='auth')socket.send(JSON.stringify({type:'ready',conversationId:'1'}));});});
+try{
+ await page.goto(target.href,{waitUntil:'networkidle'});
+ await page.locator('[data-testid="agent-sidebar-item"]').click();
+ await page.getByRole('button',{name:'Attach files',exact:true}).waitFor();
+ const picker=page.getByLabel('Choose attachments');
+ await picker.setInputFiles({name:'notes.txt',mimeType:'text/plain',buffer:Buffer.from('data')});
+ await page.getByText('Storage quota reached',{exact:true}).waitFor();
+ assert.equal(await page.getByRole('button',{name:'Send message',exact:true}).isDisabled(),true);
+ await page.getByRole('button',{name:'Retry upload',exact:true}).click();
+ await page.getByText('Uploaded',{exact:true}).waitFor();
+ await page.getByRole('button',{name:/^New chat/}).first().click();await page.locator('.agent-room__composer-area').waitFor({state:'detached'});await page.locator('[data-testid="agent-sidebar-item"]').click();await page.getByText('Uploaded',{exact:true}).waitFor();
+ await page.reload({waitUntil:'networkidle'});await page.locator('[data-testid="agent-sidebar-item"]').click();await page.getByText('Uploaded',{exact:true}).waitFor();
+ const uuid=body=>body.match(/name="uploadId"\r\n\r\n([^\r]+)/)?.[1];assert.equal(uuid(uploads[0]),uuid(uploads[1]));
+ await page.getByRole('button',{name:'Remove notes.txt'}).click();assert.equal(await page.locator('.agent-room__upload').count(),0);
+ await picker.setInputFiles([{name:'notes.txt',mimeType:'text/plain',buffer:Buffer.from('data')},{name:'picture.png',mimeType:'image/png',buffer:image}]);
+ await page.waitForFunction(()=>document.querySelectorAll('.agent-room__upload [role="status"]').length===2&&Array.from(document.querySelectorAll('.agent-room__upload [role="status"]')).every(e=>e.textContent==='Uploaded'));
+ await page.getByRole('button',{name:'Send message',exact:true}).click();await page.getByRole('button',{name:'Retry message',exact:true}).waitFor();
+ assert.deepEqual(sends[0].attachments,[{id:attachment().id},{id:attachment('picture.png').id}]);assert.equal(sends[0].content,'');
+ await page.reload({waitUntil:'networkidle'});await page.locator('[data-testid="agent-sidebar-item"]').click();await page.getByRole('button',{name:'Retry message',exact:true}).click();
+ await page.getByText('Attached: notes.txt, picture.png.',{exact:true}).waitFor();assert.equal(sends[1].requestId,sends[0].requestId);
+ await page.getByRole('button',{name:'Preview',exact:true}).click();await page.locator('.agent-attachment__preview').waitFor();assert.ok((await page.locator('.agent-attachment__preview').getAttribute('src')).startsWith('blob:'));
+ await page.getByRole('button',{name:'Hide preview',exact:true}).click();assert.equal(await page.locator('.agent-attachment__preview').count(),0);
+ const download=page.waitForEvent('download');await page.getByRole('button',{name:'Download',exact:true}).first().click();assert.equal((await download).suggestedFilename(),'notes.txt');assert.ok(downloads.every(url=>!url.includes('token')));
+ await page.getByRole('button',{name:'Copy path for notes.txt'}).click();
+ // Real paste/drop DOM events feed the same upload queue.
+ await page.getByRole('textbox',{name:'Message Sybil Agent'}).evaluate(el=>{const data=new DataTransfer();data.items.add(new File(['data'],'notes.txt',{type:'text/plain'}));el.dispatchEvent(new ClipboardEvent('paste',{clipboardData:data,bubbles:true,cancelable:true}));});
+ await page.getByText('Uploaded',{exact:true}).waitFor();await page.getByRole('button',{name:'Remove notes.txt'}).click();
+ await page.locator('.agent-room__composer-area').evaluate(el=>{const data=new DataTransfer();data.items.add(new File(['data'],'notes.txt',{type:'text/plain'}));el.dispatchEvent(new DragEvent('drop',{dataTransfer:data,bubbles:true,cancelable:true}));});
+ await page.getByText('Uploaded',{exact:true}).waitFor();
+ await page.setViewportSize({width:390,height:844});if(process.env.ATTACHMENT_SCREENSHOT)await page.screenshot({path:process.env.ATTACHMENT_SCREENSHOT});
+ assert.equal(await page.evaluate(()=>document.documentElement.scrollWidth>window.innerWidth),false);
+ assert.deepEqual(errors,[]);console.log('PASS browser picker/retry/quota/remove, file-only send/reload, authenticated preview/download, copy, paste/drop, mobile layout');
+}finally{await context.close();await browser.close();}

web/tests/agent-attachments.test.mjs

@@ -0,0 +1,101 @@
+import test from 'node:test';
+import { createHash, randomUUID } from 'node:crypto';
+import assert from 'node:assert/strict';
+import { createAgentUploadQueue, agentAttachments, parseAgentAttachment } from '../src/lib/agent-attachments.ts';
+import { AgentRoomClient } from '../src/lib/agent-room.ts';
+import { createAgentOptimisticOutbox } from '../src/lib/agent-optimistic-outbox.ts';
+import { agentTranscriptMessages } from '../src/lib/agent-room-presentation.ts';
+const file = { id:'att_12345678-1234-4234-8234-123456789abc',kind:'text',filename:'notes.txt',mimeType:'text/plain',sizeBytes:4,sha256:createHash('sha256').update('data').digest('hex'),workspacePath:'/data/workspace/uploads/att_12345678-1234-4234-8234-123456789abc/notes.txt' };
+const cap = {version:1,maxCount:8,maxTotalBytes:32*1024*1024,maxImageBytes:6*1024*1024,maxFileBytes:8*1024*1024,imageMimeTypes:['image/png','image/jpeg','image/gif','image/webp']};
+const tick=()=>new Promise(r=>setTimeout(r,0));
+const waitFor=async check=>{const until=Date.now()+5000;while(!check()){assert.ok(Date.now()<until,'async condition timed out');await tick();}};
+
+test('composer gates unsupported servers, count/type/size and batches before upload; preserves retry ID and remove races',async()=>{
+  let capability, attempts=[], next=0, changed=0, finish;
+  const queue=createAgentUploadQueue({capability:()=>capability,newId:()=>`upload-${++next}`,changed:()=>changed++,upload:async(_file,id,signal)=>{attempts.push({id,signal});if(attempts.length===1)throw new Error('Quota full');return new Promise(resolve=>finish=resolve);}});
+  const input=new File(['data'],'notes.txt',{type:'text/plain'});
+  assert.throws(()=>queue.add([input]),/not available/);capability=cap;
+  assert.throws(()=>queue.add(Array(9).fill(input)),/8 files/);
+  assert.throws(()=>queue.add([new File([new Uint8Array(6*1024*1024+1)],'big.png',{type:'image/png'})]),/6 MiB/);
+  assert.throws(()=>queue.add(Array(5).fill(new File([new Uint8Array(7*1024*1024)],'large.bin'))),/32 MiB/);
+  queue.add([input]);assert.throws(()=>queue.ready(),/Wait/);await waitFor(()=>queue.snapshot()[0].status==='failed');
+  assert.equal(queue.snapshot()[0].status,'failed');assert.match(queue.snapshot()[0].error,/Quota/);
+  queue.retry('upload-1');await waitFor(()=>attempts.length===2);assert.deepEqual(attempts.map(a=>a.id),['upload-1','upload-1']);
+  queue.remove('upload-1');assert.equal(attempts.at(-1).signal.aborted,true);finish(file);await tick();assert.deepEqual(queue.ready(),[]);
+  assert.ok(changed>0);queue.dispose();
+});
+
+test('composer serializes transfers, keeps ready descriptors, and clears without orphaning pending state',async()=>{
+  const done=[];let count=0;
+  const queue=createAgentUploadQueue({capability:()=>cap,changed:()=>{},newId:()=>`id-${++count}`,upload:async()=>new Promise(r=>done.push(r))});
+  queue.add([new File(['data'],'notes.txt'),new File(['data'],'notes.txt')]);await waitFor(()=>done.length===1);assert.deepEqual(queue.snapshot().map(r=>r.status),['uploading','waiting']);
+  done[0](file);await waitFor(()=>done.length===2);assert.deepEqual(queue.snapshot().map(r=>r.status),['ready','uploading']);done[1]({...file,id:file.id.replace('12345678','12345679')});await waitFor(()=>queue.snapshot().every(row=>row.status==='ready'));assert.equal(queue.ready().length,2);queue.clear();assert.deepEqual(queue.ready(),[]);queue.dispose();
+});
+
+test('transport uses auth headers/FormData, ID-only send and checked receipt, authenticated download with no token URLs',async()=>{
+  const calls=[];let acknowledge=true;
+  const client=new AgentRoomClient({baseUrl:'/api',token:()=> 'browser-token',fetch:async(url,init)=>{
+    calls.push({url,init});assert.ok(!url.includes('token'));assert.equal(init.headers.get('Authorization'),'Bearer browser-token');
+    if(url.endsWith('/attachments')){assert.ok(init.body instanceof FormData);assert.equal(init.headers.get('Content-Type'),null);assert.equal(init.body.get('uploadId'),'uuid');return Response.json({attachment:file},{status:201});}
+    if(url.endsWith('/content'))return new Response('data',{headers:{'content-type':'text/plain'}});
+    const body=JSON.parse(init.body);assert.deepEqual(body,{content:'',requestId:'send-id',attachments:[{id:file.id}]});
+    return Response.json({id:1,status:'queued',messageId:'inbound:sybil:send-id',...(acknowledge?{attachmentIds:[file.id]}:{})});
+  }});
+  assert.deepEqual(await client.upload(new File(['data'],'notes.txt'),'uuid'),file);
+  assert.equal((await client.submit('','send-id',[file])).status,'queued');acknowledge=false;await assert.rejects(client.submit('','send-id',[file]),/invalid message receipt/);
+  assert.equal(await (await client.download(file)).text(),'data');assert.equal(calls.at(-1).init.cache,'no-store');assert.equal(calls.at(-1).init.redirect,'error');
+});
+
+test('file-only outbox survives reload and retry without sending paths, confirms matching attachment echoes and retains tool filtering',async()=>{
+  let saved, call, fail=true;
+  const options={storage:{read:()=>saved,write:rows=>saved=structuredClone(rows)},changed:()=>{},newId:()=> 'request',submit:async(content,requestId,attachments)=>{call={content,requestId,attachments};if(fail)throw new Error('lost response');return {status:'queued',messageId:'inbound:sybil:request'};}};
+  let outbox=createAgentOptimisticOutbox(options);await assert.rejects(outbox.send('',[file]));assert.deepEqual(saved[0].attachments,[file]);
+  outbox=createAgentOptimisticOutbox(options);assert.equal(outbox.snapshot().length,1);fail=false;await outbox.retry('inbound:sybil:request');assert.equal(call.content,'');assert.deepEqual(call.attachments,[file]);
+  const row=outbox.display([])[0];assert.equal(row.content,'Attached: notes.txt.');assert.deepEqual(agentAttachments(row.metadata),[file]);
+  outbox.reconcile({messages:[{...row,metadata:{kind:'message',status:'complete'}}]});assert.equal(outbox.snapshot()[0].confirmed,false);
+  const mismatch=outbox.display([{...row,metadata:{kind:'message',status:'complete'}}])[0];assert.deepEqual(agentAttachments(mismatch.metadata),[file]);assert.equal(mismatch.metadata.status,'queued');
+  outbox.reconcile({messages:[{...row,metadata:{...row.metadata,status:'complete'}}]});assert.equal(outbox.snapshot()[0].confirmed,true);
+  const raw=[row,{...row,id:'tool',role:'tool',metadata:{kind:'tool_call'}}];assert.equal(agentTranscriptMessages(raw).length,1);assert.equal(raw.length,2);
+  assert.throws(()=>parseAgentAttachment({...file,workspacePath:'https://bad'}));
+});
+
+test('attachment drafts preserve completed receipts and unresolved IDs/hash across disposal/reload, verified reselection resumes without a new ID',async()=>{
+  let saved=[], attempts=[], complete;
+  const storage={read:()=>saved,write:rows=>saved=structuredClone(rows)};
+  const options={capability:()=>cap,storage,changed:()=>{},upload:async(_file,id,signal)=>{attempts.push({id,signal});return new Promise(r=>complete=r);}};
+  let queue=createAgentUploadQueue(options);queue.add([new File(['data'],'notes.txt',{type:'text/plain'})]);
+  await waitFor(()=>Boolean(complete));const original=attempts[0].id;assert.equal(saved[0].sha256,file.sha256);
+  queue.dispose();assert.equal(attempts[0].signal.aborted,true);
+  queue=createAgentUploadQueue(options);assert.equal(queue.snapshot()[0].status,'reselect');assert.equal(queue.snapshot()[0].uploadId,original);assert.throws(()=>queue.ready(),/Wait/);
+  await assert.rejects(queue.reselect(original,new File(['evil'],'notes.txt',{type:'text/plain'})),/different contents/);assert.equal(attempts.length,1);
+  await queue.reselect(original,new File(['data'],'notes.txt',{type:'text/plain'}));await waitFor(()=>attempts.length===2);assert.equal(attempts[1].id,original);
+  complete(file);await tick();assert.equal(queue.ready()[0].id,file.id);queue.dispose();
+  const restored=createAgentUploadQueue(options);assert.deepEqual(restored.ready(),[file]);assert.equal(attempts.length,2,'completed upload is never repeated');restored.clear();assert.deepEqual(saved,[]);
+});
+
+test('mismatched complete echoes cannot hide local attachment errors or the retry action',async()=>{
+  const box=createAgentOptimisticOutbox({storage:{read:()=>null,write:()=>{}},changed:()=>{},newId:()=> 'mismatch',submit:async()=>{throw new Error('quota failure');}});
+  await assert.rejects(box.send('caption',[file]));const initial=box.display([])[0];
+  for(const attachments of [undefined,[{...file,id:file.id.replace('12345678','12345679')}]]){
+    const echo={...initial,metadata:{kind:'message',status:'complete',...(attachments?{agentAttachments:attachments}:{})}};
+    box.reconcile({messages:[echo]});const shown=box.display([echo])[0];assert.equal(shown.metadata.status,'failed');assert.equal(shown.metadata.error,'quota failure');assert.deepEqual(shown.metadata.agentAttachments,[file]);assert.equal(box.snapshot()[0].confirmed,false);
+  }
+});
+
+test('storage refusal prevents uploads and outbox handoff; no attachment draft is cleared before persistence',async()=>{
+  let uploads=0;const queue=createAgentUploadQueue({capability:()=>cap,storage:{read:()=>null,write:()=>{throw new Error('storage full');}},changed:()=>{},upload:async()=>{uploads++;return file;}});
+  assert.throws(()=>queue.add([new File(['data'],'notes.txt')]),/storage full/);await tick();assert.equal(uploads,0);
+  let cleared=false;const box=createAgentOptimisticOutbox({storage:{read:()=>null,write:()=>{throw new Error('storage full');}},changed:()=>{},submit:async()=>({status:'queued'})});
+  await assert.rejects(box.send('draft',[file],()=>{cleared=true;}));assert.equal(cleared,false);
+});
+
+
+test('a late canceled queue completion cannot overwrite a restored draft',async()=>{
+  let saved=[];const pending=[];
+  const options={capability:()=>cap,changed:()=>{},storage:{read:()=>saved,write:rows=>saved=structuredClone(rows)},upload:async()=>new Promise(resolve=>pending.push(resolve))};
+  const old=createAgentUploadQueue(options);old.add([new File(['data'],'notes.txt',{type:'text/plain'})]);await waitFor(()=>pending.length===1);
+  const oldId=old.snapshot()[0].uploadId;old.dispose();
+  const restored=createAgentUploadQueue(options);restored.remove(oldId);restored.add([new File(['data'],'notes.txt',{type:'text/plain'})]);await waitFor(()=>pending.length===2);
+  pending[1](file);await tick();const current=structuredClone(saved);assert.equal(current[0].status,'ready');assert.notEqual(current[0].uploadId,oldId);
+  pending[0](file);await tick();assert.deepEqual(saved,current);assert.deepEqual(restored.ready(),[file]);restored.dispose();
+});

web/tests/agent-room-presentation.test.mjs

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { applyAgentEvent, applyAgentReadState, createAgentRoomState } from '../src/lib/agent-room.ts';
+import { agentDisplayMessages, agentUnreadCount, applyAgentEvent, applyAgentPage, applyAgentReadState, createAgentRoomState, parseAgentRoomEvent } from '../src/lib/agent-room.ts';
-import { createAgentRoomPresenter } from '../src/lib/agent-room-presentation.ts';
+import { agentTranscriptMessages, createAgentRoomPresenter } from '../src/lib/agent-room-presentation.ts';
 
 const message = (entry, role = 'assistant', extra = {}) => ({ id: `entry:${entry}`, createdAt: '2026-10-14T00:00:00.000Z', role,
   content: `Message ${entry}`, metadata: { kind: 'message', entryId: entry, status: 'complete' }, ...extra });
@@ -27,6 +27,92 @@ function fixture(initial = createAgentRoomState()) {
   return { presenter, advance, frames, last: () => frames.at(-1) };
 }
 
+test('loaded history hides tool calls and results without removing records or changing normal messages', () => {
+  const user = message(1, 'user', { content: 'Explain this tool_call and tool_result JSON.' });
+  const reply = message(5, 'assistant', { content: '**Result**\n\nThe lookup failed; please try another source.' });
+  const tools = ['initiated', 'completed', 'failed'].map((status, index) => message(index + 2, 'tool', {
+    id: `tool:1:lookup-${index}`, name: 'lookup', content: 'Raw tool details',
+    metadata: { kind: 'tool_call', entryId: index + 2, toolCallId: `lookup-${index}`, status,
+      args: { query: 'raw input' }, resultPreview: 'raw output', error: status === 'failed' ? 'raw error' : null },
+  }));
+  const room = applyAgentPage(createAgentRoomState(), page(5, [message(0, 'system'), user, ...tools, reply]));
+  const original = structuredClone(room);
+  const transcript = agentTranscriptMessages(agentDisplayMessages(room));
+
+  assert.deepEqual(transcript, [user, reply]);
+  assert.strictEqual(transcript[0], user);
+  assert.strictEqual(transcript[1], reply);
+  assert.deepEqual(room, original, 'presentation must leave tool records and cursor intact');
+  assert.equal(room.messages.length, 6);
+  assert.equal(agentUnreadCount(room), 1);
+});
+
+test('tool-only history produces no transcript rows regardless of metadata or status', () => {
+  const messages = [null, {}, [], 'legacy metadata', { kind: 'tool_result' }, { kind: 'tool_call', status: 'failed' }]
+    .map((metadata, index) => message(index + 1, 'tool', { metadata, createdAt: `2026-10-${10 + index}T00:00:00.000Z` }));
+  assert.deepEqual(agentTranscriptMessages(Object.freeze(messages)), []);
+  assert.deepEqual(agentTranscriptMessages([]), []);
+});
+
+test('user delivery errors, queued messages, and assistant content remain visible even with tool-like metadata', () => {
+  const users = ['sending', 'queued', 'failed', 'unconfirmed'].map((status, index) => message(index + 1, 'user', {
+    metadata: { kind: 'message', status, error: 'Could not send; retry this message.' },
+  }));
+  const reply = message(5, 'assistant', { content: 'The tool_result contained an error. **Please retry.**',
+    metadata: { kind: 'tool_call', status: 'failed', error: 'Keep this assistant message.' },
+  });
+  const room = applyAgentEvent(applyAgentPage(createAgentRoomState(), page(5, [users[0], ...users.slice(2), reply])),
+    activity(false, { queued: 1, queuedMessages: [users[1]] }));
+  const transcript = agentTranscriptMessages(agentDisplayMessages(room));
+
+  assert.deepEqual(transcript, [...users, reply]);
+  for (const [index, original] of [...users, reply].entries()) assert.strictEqual(transcript[index], original);
+});
+
+for (const status of ['completed', 'failed']) {
+  test(`live ${status} tool updates and replay stay hidden while progress, replies, and cursors survive`, () => {
+    const f = fixture();
+    const user = message(1, 'user');
+    const started = message(2, 'tool', { id: 'tool:1:lookup', name: 'lookup',
+      metadata: { kind: 'tool_call', toolCallId: 'lookup', toolName: 'lookup', entryId: 2, status: 'initiated', args: { query: 'input' } },
+    });
+    const finished = { ...started, content: 'Raw tool output',
+      metadata: { kind: 'tool_call', toolCallId: 'lookup', entryId: 3, status, resultPreview: 'output', error: status === 'failed' ? 'Lookup failed' : null },
+    };
+    const progress = activity(true, { tools: [{ id: 'lookup', name: 'lookup', status: 'running' }], backgroundWorkers: 1 });
+    const receive = event => f.presenter.push(parseAgentRoomEvent(JSON.stringify(event)));
+    f.presenter.push(page(1, [user]), { replay: true });
+    receive(progress); f.advance(250);
+
+    for (const event of [page(2, [started]), page(3, [finished]), page(2, [started])]) {
+      receive(event); f.advance(100);
+      const { room, isTyping } = f.last();
+      assert.deepEqual(agentTranscriptMessages(agentDisplayMessages(room)), [user]);
+      assert.equal(isTyping, true, 'tool visibility must not suppress ongoing progress');
+      assert.deepEqual(room.activity, progress.activity);
+      assert.equal(room.messages.length, 2, 'tool records still merge by their stable ID');
+    }
+    assert.equal(f.last().room.cursor, '3');
+    assert.equal(f.last().room.readCursor, '0');
+    assert.equal(agentUnreadCount(f.last().room), 0);
+    assert.equal(f.last().room.messages[1].metadata.status, status);
+    assert.deepEqual(f.last().room.messages[1].metadata.args, { query: 'input' });
+    assert.equal(f.last().room.messages[1].metadata.resultPreview, 'output');
+
+    const reply = message(4, 'assistant', { content: status === 'failed' ? 'The lookup failed. Please try again.' : 'Here is the answer.' });
+    receive(page(4, [reply])); f.advance(100);
+    assert.deepEqual(agentTranscriptMessages(agentDisplayMessages(f.last().room)), [user, reply]);
+    assert.equal(f.last().isTyping, false, 'the answer still clears the old typing indicator');
+    assert.equal(f.last().room.cursor, '4');
+    assert.equal(agentUnreadCount(f.last().room), 1);
+    f.presenter.update(room => applyAgentReadState(room, { cursor: '4', updatedAt: null }));
+    f.presenter.flush();
+    assert.equal(agentUnreadCount(f.last().room), 0);
+    assert.equal(f.last().room.messages.length, 3);
+    f.presenter.dispose();
+  });
+}
+
 test('a reply and removal of its old thinking indicator publish together even when idle is delayed', () => {
   const f = fixture();
   f.presenter.push(activity(true)); f.advance(250); assert.equal(f.last().isTyping, true);

web/tests/pwa.browser.mjs

@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { resolve, extname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Run after npm run build, with an existing Playwright/Chromium installation:
+// PLAYWRIGHT_MODULE=/path/to/playwright-core/index.mjs CHROME_EXECUTABLE=/path/to/chrome
+// node tests/pwa.browser.mjs
+// This serves the real production bundle and service worker on loopback. No live API is used.
+const { chromium } = await import(process.env.PLAYWRIGHT_MODULE || 'playwright-core');
+const root = fileURLToPath(new URL('../dist/', import.meta.url));
+await readFile(resolve(root, 'sw.js'));
+const types = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.webmanifest': 'application/manifest+json', '.png': 'image/png', '.ttf': 'font/ttf' };
+let sessionMode = 'token';
+const server = createServer(async (request, response) => {
+  const path = new URL(request.url, 'http://localhost').pathname;
+  if (path.startsWith('/api/')) {
+    let status = 200;
+    let body;
+    if (sessionMode === 'unavailable') {
+      status = 503;
+      body = { message: 'Service temporarily unavailable' };
+    } else if (sessionMode !== 'open' && request.headers.authorization !== 'Bearer local-login-fixture') {
+      status = request.headers.authorization ? 403 : 401;
+      body = { message: status === 401 ? 'missing bearer token' : 'invalid bearer token' };
+    } else {
+      body = {
+        '/api/v1/auth/session': { authenticated: true, mode: sessionMode },
+        '/api/v1/workspace-items': { items: [] },
+        '/api/v1/models': { providers: {} },
+        '/api/v1/chat-tools': { tools: [] },
+        '/api/v1/active-runs': { chats: [], searches: [] },
+      }[path] ?? {};
+    }
+    response.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    response.end(JSON.stringify(body));
+    return;
+  }
+  const file = resolve(root, '.' + (path === '/' ? '/index.html' : path));
+  if (!file.startsWith(root.endsWith(sep) ? root : root + sep)) { response.writeHead(404); response.end(); return; }
+  try {
+    const bytes = await readFile(file);
+    response.writeHead(200, { 'Content-Type': types[extname(file)] || 'application/octet-stream', 'Cache-Control': 'no-store' });
+    response.end(bytes);
+  } catch { response.writeHead(404); response.end(); }
+});
+await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+const browser = await chromium.launch({ executablePath: process.env.CHROME_EXECUTABLE || undefined, headless: true,
+  ...(process.env.BROWSER_NO_SANDBOX === '1' ? { args: ['--no-sandbox'] } : {}) });
+try {
+  const context = await browser.newContext({ serviceWorkers: 'allow' });
+  await context.route('https://fonts.googleapis.com/**', route => route.abort());
+  await context.route('https://fonts.gstatic.com/**', route => route.abort());
+  const page = await context.newPage();
+  const errors = []; page.on('pageerror', error => errors.push(error.message));
+  await page.goto(`http://127.0.0.1:${server.address().port}/`, { waitUntil: 'domcontentloaded', timeout: 15_000 });
+  // Activation must settle before a worker-controlled navigation can finish.
+  await page.waitForFunction(() => navigator.serviceWorker.controller?.state === 'activated', undefined, { timeout: 15_000 });
+  await page.getByPlaceholder('ADMIN_TOKEN').waitFor({ timeout: 5_000 });
+  assert.equal(await page.getByRole('alert').count(), 0);
+  assert.equal(await page.getByRole('button', { name: 'Continue without token' }).count(), 0);
+  assert.equal(await page.getByText(/If.*ADMIN_TOKEN/).count(), 0);
+  assert.equal(await page.getByRole('button', { name: 'Sign in', exact: true }).isDisabled(), true);
+  await page.getByPlaceholder('ADMIN_TOKEN').fill('incorrect-login-fixture');
+  assert.equal(await page.getByRole('button', { name: 'Sign in', exact: true }).isEnabled(), true);
+  await page.getByRole('button', { name: 'Sign in', exact: true }).click();
+  await page.getByRole('alert').waitFor();
+  assert.equal(await page.getByRole('alert').textContent(), 'Incorrect token. Please try again.');
+  await page.reload({ waitUntil: 'domcontentloaded', timeout: 10_000 });
+  await page.getByPlaceholder('ADMIN_TOKEN').waitFor({ timeout: 5_000 });
+  assert.equal(await page.getByRole('alert').count(), 0);
+  assert.equal(await page.evaluate(() => navigator.serviceWorker.controller?.state), 'activated');
+
+  // Invalid saved credentials are a real failure, unlike a first visit without credentials.
+  await page.evaluate(() => localStorage.setItem('sybil_admin_token', 'outdated-login-fixture'));
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await page.getByRole('alert').waitFor();
+  assert.equal(await page.getByRole('alert').textContent(), 'Incorrect token. Please try again.');
+  await page.getByPlaceholder('ADMIN_TOKEN').fill('local-login-fixture');
+  await page.getByRole('button', { name: 'Sign in', exact: true }).click();
+  await page.locator('.workspace-shell').waitFor();
+  assert.equal(await page.evaluate(() => localStorage.getItem('sybil_admin_token')), 'local-login-fixture');
+
+  await page.evaluate(() => localStorage.removeItem('sybil_admin_token'));
+  sessionMode = 'open';
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await page.locator('.workspace-shell').waitFor();
+  assert.equal(await page.getByPlaceholder('ADMIN_TOKEN').count(), 0);
+
+  // Suppress only the expected missing-token response, never connectivity/server failures.
+  sessionMode = 'unavailable';
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await page.getByRole('alert').waitFor();
+  assert.equal(await page.getByRole('alert').textContent(), 'Service temporarily unavailable');
+  assert.deepEqual(errors, []);
+  console.log('PASS service-worker activation/reload, neutral first sign-in, rejected tokens, valid sign-in, automatic open-mode entry, and visible server failures');
+} finally {
+  await browser.close();
+  server.closeAllConnections();
+  await new Promise(resolve => server.close(resolve));
+}

web/tsconfig.json

@@ -6,7 +6,7 @@
     "module": "ESNext",
     "skipLibCheck": true,
     "moduleResolution": "Bundler",
-    "allowImportingTsExtensions": false,
+    "allowImportingTsExtensions": true,
     "resolveJsonModule": true,
     "isolatedModules": true,
     "noEmit": true,