feat(native-chat): attach files to a structured chat on a paired server

[brennanb2025]

	Files	Added	Deleted	Net
Test	30	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​3207	$\color{#cf222e}{\Huge{\mathbf{−}}}$​51	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​3156
Prod	75	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2880	$\color{#cf222e}{\Huge{\mathbf{−}}}$​273	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​2607

ELI5

When your chat runs on another computer (a paired Orca server), you couldn't give it a file. Pasting a screenshot, dropping a file from Finder/Explorer or using the file picker only showed "Local attachments are not available for remote sessions." Now Orca copies the file to that computer first, and the agent reads it from there.

What Changed

The problem. A structured agent chat (the native chat that talks to Claude or Codex directly, not through a terminal) can run on a paired Orca server. The agent runs on the server, so a path on this machine means nothing to it. That is why the composer refused every client file:

• an image-only paste and the paste button showed the refusal;
• a paste with text and an image silently dropped the image;
• a Finder/Explorer drop and the file picker showed the refusal.

Dragging a file from the workspace's own file tree already worked, because that file is already on the server.

For the user, after this PR. In a structured chat on a paired server:

• Pasted images, text+image pastes, the paste button, dropped files and picked files all attach.
• Each dropped or picked file shows a chip with its name while it uploads. Send waits for those chips, so a message never goes out without a file you attached. Removing a chip while it uploads keeps that file out of the message.
• If a file can't be attached, the composer's notice line says so once, naming the file and the reason (for example the 50 MiB limit). Dropped folders are skipped.
• Image chips and sent images are read back from the server for previews. Large images (over the remote reply budget) show "Preview unavailable" instead of breaking the connection.
• If the server runs an older Orca, the notice line shows the existing "This needs a newer Orca on the computer running this chat. Update Orca there, then try again." Nothing is uploaded and no path from this machine is sent.
• An upload that finishes while a question or approval card has replaced the composer is still attached when the composer comes back.
• A message that names a file the server no longer has (unsent for more than 24 hours, or removed) is not sent. The message goes back into the composer, and the notice says "This attachment expired. Remove it and attach it again."
• Claude can read attached non-image files without asking for permission.

Local chats, SSH chats and terminal-backed chats behave exactly as before.

Mechanism.

• Server-owned store. The server keeps uploads under its own userData: agent-session-attachments/<upload id>/<original file name> (the name is kept because agents read meaning into it; it is sanitized and capped in bytes, Windows device names are avoided). The directory is created when the structured host starts.
• Upload RPCs. agentSessionAttachment.uploadStart, uploadAppend, uploadCommit, uploadAbort fill the store in chunks; upload ids are bound to the client that started them, the number in flight is capped, idle uploads expire after 5 minutes, and uploadStart refuses a chat the server doesn't hold. agentSessionAttachment.read returns a stored image for previews through the existing protected, bounded preview read and reply budget, and refuses anything outside the store. All five sit behind the existing structured-session gate, and the server advertises them as the capability agent-session.attachments.v1.
• Client upload. Main does the byte transfer so the renderer never holds a whole file. Drops and picks go through fs:uploadPathsToAgentSessionAttachments, which reuses the file-import slice streamer; pastes go through the existing clipboard:saveImageAsTempFile with a new target. Every call is pinned to the pairing revision and every chunk to the server process id, so a re-pair or server restart aborts the upload. The browser client's paste is pinned the same way.
• Lifetime: a claim at admission. When the server admits a message from a client (send, queue, steer, retry), it finds the store paths the message names and records a claim (upload × chat) in the same database transaction that saves the message. If a named upload is missing or being deleted, the whole message is refused with a new attachmentExpired reason, which the client turns into the composer restore above. The server's own writes (the /clear carry, restart continuation, queue drain) claim best-effort and never refuse. A cleanup pass (about a minute after the host starts, then every 6 hours) deletes unfinished uploads after 1 hour and unclaimed uploads after 24 hours. It marks an upload for deletion only if no claim exists, in the same single database connection the claims use, so a send and a cleanup can never both win; a cleanup interrupted mid-delete is finished by the next pass. Only exact paths under the server's own store directory count, so text that merely mentions such a path is left alone.
• Agent access. Structured Claude gets the store directory as an added readable directory. Codex's sandbox modes already allow reading it.

Wire compatibility.

• Every method is new; no existing params changed. A new client checks the capability first, so an older server gets the notice instead of a call. An older client never calls the new methods.
• The new refusal reason is an extra value under an existing refusal code; an older client shows its generic "wasn't sent" text.
• The two new journal tables are created if missing with no schema version bump, so an older build keeps opening the database.
• Mobile clients don't call the new methods (not on the mobile allowlist).

Why

• The common pattern. The client uploads the bytes to the server that runs the session; the server keeps them in a store it owns, records which messages use each upload when it admits them, refuses a message whose upload is gone, and sweeps only uploads nothing claims. This PR adopts that mechanism.
• Rejected: deriving "still needed" by scanning chat history for paths. An earlier revision of this PR did that. History rows move or disappear (/clear moves queued messages to a new chat, history rollover deletes rows), the scan was per file on the main thread, and nothing coordinated a deletion with a send in progress. Recording the claim when the message is admitted removes that class of bug.
• Rejected: checking on the client which server a file belongs to. That bookkeeping was lost whenever a message was rebuilt (Retry, Stop-restore, reload) and wrongly stripped valid files after a same-server re-pair. The server is the only party that knows whether a path is one of its uploads, so the claim is the single check.
• Rejected: the server's .orca/drops (what SSH chats use) and the clipboard RPC's temp files. The first writes into the user's worktree; neither has an owner or a lifetime.

Differences from the common pattern

• Uploads travel as chunks over the existing paired-server connection instead of an HTTP upload — intended: that connection is the only channel to a paired server.
• Whether an upload exists is read from disk; there is no separate upload row — intended: the file is the record, and there is nothing to keep in sync.
• A message refused for an expired attachment is appended after anything already in the composer, rather than restored only into an empty composer — intended: it reuses Orca's existing Stop-restore behavior, and never overwrites what the user has typed.
• Claimed uploads live as long as the chat's record, which today is forever because the server never deletes a structured chat — temporary: claims are keyed by chat, so a future chat delete frees its uploads with no new bookkeeping.
• Claude can read every upload in the store, not only this chat's — intended: same breadth as the common pattern; paths are random ids.
• Local chats still pass the real file path — intended: same machine, and the agent should act on the real file.
• SSH chats keep uploading into .orca/drops — temporary: a follow-up can move them onto a host-owned store.
• The terminal-backed native chat on a paired server still refuses client files — temporary: its agent may run on the server's SSH/WSL host, which the store can't reach.
• Removing a chip while it uploads keeps the file out of the message but lets the transfer finish (the server deletes it after 24 hours unclaimed) — temporary: wiring the abort is a follow-up.

Linked Issue

N/A (maintainer follow-up to the paired-server structured chat work).

Visual Proof

Before: the composer showed "Local attachments are not available for remote sessions." for every pasted, dropped or picked file (no screenshot of an older build; the box was shared).

After (live, desktop paired to a server Orca, real Claude):

Pasted image chip	Claude describes the pasted image

Dropped text file → server path	Claude reads the stored file (no permission prompt)

5.5 MB image: preview unavailable, connection stays up	Folder skipped with one notice; over-5 MB image refused by the existing Claude limit

Testing

• Unit tests cover the store (upload, name sanitizing incl. byte cap and Windows device names, chunk order, caller isolation, abort, idle expiry, preview reads refusing paths outside the store), claims (same-transaction claim, expired refusal, /clear carry, cleanup vs claim race, interrupted cleanup), the RPC gate and capability, the main upload pump and clipboard route against a real store, the Claude store-directory hand-off, and the renderer paths (pending chips, chip removal, uploads that finish across a prompt card, input-method composition, rich-text paste, older server, expired-refusal restore, cache eviction never dropping an open composer's attachments).

• Related suites: 491 files / 4,867 tests; every src/main/ipc test and every test that mocks fs: 737 files (one pre-existing timeout in profile-state-backup-rotation.test.ts, same on main); cross-version wire suites 17/17 files (105 tests); tc:node and tc:web pass; changed-code quality gate and localization checks pass.

• Live QA on a paired server (two Orca builds on one Mac, isolated homes and profiles, real Claude; the Mac was shared with other test runs): paste, drop, file picker, send and agent reads all pass; Claude read the stored text file with no permission card in both the default mode and with launch arguments cleared; a 5.5 MB image left the connection up and showed "Preview unavailable"; a dropped folder was skipped with one notice; removing a pending chip left nothing in the draft; a genuinely local chat on the same paired desktop kept real local paths and uploaded nothing.

• Not verified live: an older server (needs a second build; unit tests cover the capability check), Manual permission mode (not offered in that setup), Windows/Linux.

• Not run locally: the tests under src/main/claude (CI runs them) and the real-Claude CLI suite.

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

Review

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Cross-platform: server paths are built with path.join; claim matching accepts either separator and any case on Windows; the commit rename retries on Windows file locks.
• SSH chats and folder workspaces are unchanged.
• The browser client's paste takes the same store route; its drop stays unavailable, as before.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

Merged with main: how this fits #24905 (saved drafts)

Main now keeps a chat's unsent draft across a reload or quit (#24905). This PR now builds on that instead of keeping its own copy:

• Finished attachments are owned by main's saved draft only.
• Attachments still uploading stay in a small per-chat cache (native-chat-pending-attachment-cache.ts). They survive the composer being replaced by a prompt card, keep Send disabled, and drop into the draft when the upload finishes. They are never saved, so a restored draft never brings back an unfinished upload as if it were attached.
• Each uploading attachment carries the same owner its draft would have, so removing a workspace (or closing a tab) also drops its uploads in flight; a late upload can't recreate a deleted draft.
• Two small changes to fix(native-chat): an unsent draft survives a reload or quit #24905's files, so an image stored on a paired server stays valid in a saved draft: the draft keeps such a pasted image whole (instead of a "Not kept" placeholder), and restoring skips the local file-exists check for it (the file exists only on the server; the server's check at Send refuses an upload that has expired, and the message returns to the composer).
• The earlier eviction change to the composer scope cache is reverted to main's version: every uploading attachment ends with its upload, so no size cap is needed.

[brennanb2025]

Review status: ready for review

Update (2026-10-06): current main is merged in at head 30461ade5ff. Main added saved drafts that survive a reload or quit (#24905), so this PR now builds on them: finished attachments belong to the saved draft, and attachments still uploading stay in a small per-chat cache that is never saved, so a restored draft never brings back an unfinished upload. A merge review found that an upload still in flight when its workspace is removed could recreate the deleted draft; that's fixed (each uploading attachment carries its draft's owner and is dropped with the workspace or tab), with tests. Two small changes to #24905's draft files keep an image stored on a paired server valid in a saved draft. Details in the PR body under "Merged with main".

The problem

A structured agent chat (Claude or Codex in Orca's native chat) can run on a paired Orca server: another computer that owns the workspace. The agent runs on that server, so a file path on this machine means nothing to it. Every way of giving the chat a file was refused with "Local attachments are not available for remote sessions.": pasting a screenshot, dropping files from Finder/Explorer, and the file picker. A paste of text plus an image silently lost the image.

What changes for the user

In a structured chat on a paired server:

• Attaching works. Pasted images, dropped files and picked files attach, and the agent reads them.
• Pending chips. A file still uploading shows a chip with its name, and Send waits for it. That holds even if a question or approval card replaces the composer, or the user is mid-way through Japanese or Chinese input.
• Failures. A file that can't be attached is reported once, naming the file and the reason.
• Older server. If the server runs an older Orca, the chat shows the existing "needs a newer Orca on the computer running this chat" notice and nothing is sent.
• Expired attachment. A message naming a file the server no longer has (unsent for more than 24 hours) is not sent. It goes back into the composer with "This attachment expired. Remove it and attach it again."

Local, SSH and terminal-backed chats are unchanged.

How it works

The desktop uploads the bytes to a store the server owns. The server records which messages use each upload in the same database transaction that saves the message. A cleanup pass only deletes uploads nothing has claimed, and it can never race a send.

What the review changed

The first version differed in three main ways, and the review replaced each:

• Deciding what to keep. It scanned chat history for file paths to decide what to keep. History rows move or vanish (/clear, history rollover), so the scan could delete files still in use, and it scanned once per file on the main thread. It is now an explicit claim recorded when the server accepts a message.
• Checking which server owns a file. The desktop kept its own record of which server each file belonged to and checked it before Send. That record was lost on Retry, Stop and reload, and it wrongly stripped valid files after a same-server re-pair. That check is deleted; the server's claim is the only check.
• Large image previews. A preview of an image of about 3 MiB or more was sent as one reply over the server's 4 MiB limit, which dropped the whole connection to that server. Previews now use the existing bounded preview read.

Further fixes:

• A finished upload could be lost when a prompt card replaced the composer. A file could also be left out of the message being sent and land in the next draft.
• A removed chip's file could still be inserted.
• A dropped folder was walked in full before being skipped.
• Browser-client pastes weren't tied to the server they started on.
• Claude now gets read access to the upload store, so it doesn't ask before reading attached files.
• On Windows, an antivirus or indexer briefly locking a fresh upload no longer loses it: the final rename retries.
• File names cut at the byte limit no longer end in a dot or space.
• A cache-eviction case could drop an open composer's attachments.
• Several src/main/ipc test files failed in CI because a new import reached a module that reads a file-system constant on load.

Deferred (not blocking)

• Removing a chip mid-upload keeps the file out of the message but lets the transfer finish. The unclaimed file is deleted after 24 hours.
• An upload cancel or idle expiry can race an in-progress chunk write. It's bounded: the commit fails and leftovers are swept after an hour.
• There is no per-chat or per-server disk quota. The 8 concurrent uploads are shared by all clients.
• Uploads a message has claimed live as long as the chat. The server never deletes structured chats today, so a future chat delete is what frees them.
• On macOS, a store path the user retypes in a different case isn't claimed.
• A reply refused while the chat view is closed loses its error text.
• Minor cleanups: some test duplication, module naming, and the upload registry has a single user.

Verified

• Four review rounds plus the readiness checklist, with no P0 or P1 open.
• Two independent diff reviews.
• 491 related test files (4,867 tests).
• Every src/main/ipc test and every test that stubs the file system: one pre-existing timeout, which also fails on main.
• Cross-version wire suites: 105 of 105.
• At head 30461ad (main 80d4509 merged in): two conflicts, both kept from each side. The list of tests that must run under Node keeps main's two new SSH tests and this PR's two attachment tests. The chat-history wiring takes main's new reopen point (fix(native-chat): a message kept after a quit or close waits in order and follows the chat's next turn #25960, messages kept after a quit wait in order) and keeps this PR's attachment claim. On the merged tree tc:node and tc:web pass with 0 errors, the targeted tests (35 files, 454 tests) pass, and lint is clean on the 98 changed files. CI pending.
• At head d547b1c (main e6bcc5a merged in): tc:node and tc:web pass with 0 errors, the targeted tests (88 files, 971 tests, including main's draft-reload tests) pass, and CI finished fully green: 20 passed, 18 skipped, 0 failed, with all five test runs. Main's [CI] Reduce repeated UI imports in draft storage tests #26145 moved the composer's attachment cache functions into the draft cache module; this PR now uses main's copies, and that module's test reset also clears pending upload chips.
• At head 1b137cf (main c8dcffc merged in): tc:node and tc:web pass with 0 errors, the targeted tests (74 files, 782 tests) pass, and CI finished fully green: 20 passed, 18 skipped, 0 failed, with all five test runs. Main's refactor(native-chat): remove the records-file and per-chat journal imports #26038 removed the journal database's stateDirectory and legacyRecordImportOwed. This PR puts stateDirectory back, written exactly as feat(native-chat): say in the chat why Orca stopped a reply, and offer Continue #25675 writes it, because the attachment store lives beside the database. The attachment sweep now reads the chat list directly, since no chat record is waiting to be imported any more. Main's composer notice card (feat(native-chat): one notice card above the message box for the chat's own errors #25835) shows an error's own words apart from Orca's sentence; a failed image paste into a chat on a paired server now does the same (new test).
• At head 58348b6 (main 988f87e merged in): tc:node and tc:web pass with 0 errors, the targeted tests (34 files, 451 tests) pass, and CI finished fully green: 20 passed, 18 skipped, 0 failed, with all five test runs. This merge kept main's Claude account routing (Claude account profiles: dormant routing and consumers (Step 2 of 4) #24351) beside the PR's attachment-folder grant, so a folder added with --add-dir and the attachment folder are both still granted. It also kept main's rule that an agent without image input gets no image chip (feat(native-chat): Grok as a structured chat over the Agent Client Protocol #25225), while a named file upload into a chat on a paired server still shows its chip (new test).
• At head 4d09aa3 (main d3e1494 merged in): tc:node and tc:web pass with 0 errors, the PR's 73 test files (777 tests) pass, and lint is clean. Main's new send function (fix(native-chat): queued messages carry on in order after any turn, and nothing sends by itself after a restart #24586) keeps the PR's hold on a picked command while an attachment is still uploading; closing a tab clears its uploading chips next to main's new agent-launch bookkeeping (feat(agent-launch): show an agent's tab at once, where the caller asked #25430).
• Kept main's changes in this round: who sent a queued message now travels with the message (feat(native-chat): show which agent a chat message is from, and open it #25888), so the queue step keeps only the PR's "every attachment must still be stored" flag for a person's send; attaching rechecks the destination at the last moment (Fix ownership for terminal and chat file drops (STA-6940, PR 1/6) #25749), and the PR's paired-server path uses that same check; the image preview gains main's copy menu (feat(native-chat): copy chat images from the right-click menu #24161) beside the PR's upload chip. The attachment store's SQLite tests are listed in the Node runtime test project main added ([CI] Speed up unit tests with cross-runtime duration scheduling #25967).
• Fixed in this merge: main (fix(native-chat): honor saved agent Command and Arguments #25721) now grants Claude the folders a user adds with --add-dir in the saved Arguments, and this PR's grant of the attachment folder replaced that list instead of adding to it. Both are granted now, with a test that fails without the fix. Main's stopped-message restore (feat(native-chat): keep a message a Stop took back on screen, with one stop row after it #25051) and its new record-store opening (feat(agent-launch): host-assigned caller identity and a launch record written when the tab exists (unification 1 of 3) #24934) are kept as main has them; the expired-attachment path still returns the message to the composer.
• Live, on a Mac shared with other test runs: a desktop and a server Orca, each with an isolated home and profile, with real Claude.
  • Paste, drop, file picker, send and agent reads all work.
  • Claude read a stored text file with no permission card.
  • A 5.5 MB image kept the connection up and showed "Preview unavailable".
  • A folder drop showed one skip notice.
  • Removing a pending chip left nothing behind.
  • A genuinely local chat on that same paired desktop is unchanged (re-run at 690970c). The repo, workspace and tab were all owned by this computer. The pasted image stayed a local temp file, and the dropped file kept its real path. Neither Orca's upload store gained an entry, and Claude read the file.

Not verified

• S7, the older-server refusal, was not exercised live; unit tests only.
• The Claude read-permission grant was only partly exercised: the server profile runs Claude with bypassed permissions, and Manual mode was not offered, so a prompting mode was never tested live.
• Windows and Linux hosts.
• The real-Claude CLI suite.