Omniscio

Chat attachments (PDFs, text docs, images, Office docs, pasted text) (part 2)

Part 2 of the Chat attachments page: the send pipeline that partitions every attachment and delivers it, how non-Claude engines receive attachments as files in the workdir, how a large paste becomes a chip instead of flooding the composer, and where the attachment files live on disk.

On this page

What it is

This is part 2 of the Chat attachments (PDFs, text docs, images, Office docs, pasted text) page. It covers the machinery behind an attachment: how the send pipeline sorts each one and delivers it to the model, how non-Claude engines get the same content as files inside the project, and how a very large paste turns into a chip rather than flooding the box you are typing in.

Where to find it

Nothing here has a screen of its own — it is what happens after you press send in the composer described in the first half of this page. The one visible consequence is where a document ends up: it is written into the session’s own project folder, and that file path is what the agent is handed.

How it behaves

How it works

Send pipeline (one round of SESSION_SEND_RESPONSE), implemented at session-service.ts (sendResponse method — grep async sendResponse( for the current line):

  1. Partition. partitionAttachments walks the IPC payload's images[] array (the field is historically named images but actually carries any attachment type) and returns five arrays: images, pdfs, textDocs, officeDocs, dropped. Classification is MIME-first with extension fallback — .pdf extension counts as a PDF even if the MIME is generic, the text-doc set is whitelist-driven (exact MIMEs text/markdown, text/plain, text/csv, text/html, text/xml, text/tab-separated-values, application/json, application/xml, text/calendar, plus extensions .md .markdown .txt .csv .json .html .xml .tsv .log .ics), and Office docs are routed by every office MIME/extension — the modern OOXML trio plus the anydoc-read set (application/msword, application/vnd.ms-excel, application/vnd.ms-powerpoint, the three application/vnd.oasis.opendocument.*, application/epub+zip, and application/rtf/text/rtf), all sourced from one @shared/attachment-mime module (OPENXML_OFFICE_* + ANYDOC_EXTRA_DOC_*) so the renderer allow-list and the main-process partition can't disagree on what an office file is. Anything else lands in dropped and is silently discarded — but in practice nothing reaches dropped because the renderer's allow-list and the IPC schema's enum already filter the input.

  2. Per-bucket handling. For each image the main process calls saveAttachment (UI chip metadata) and pushes a { data, mimeType } entry into inlineImages. For each PDF it does the same plus saves the bytes to <workdir>/.claude/amc-attachments/<sessionId>/<name> via saveDocToWorkdir and pushes a parallel entry into documentBlocks. For each text doc it saves to workdir and records the absolute path in savedDocPaths (no inline content block — text docs are too cheap to embed when a path will do). For each Office doc it saves the binary as chip metadata in userData (so the user sees the original filename in the message row), then calls extractOfficeText to extract Markdown via the anydoc reader (with the in-process mammoth/adm-zip extractor as a fallback for .docx/.pptx, and .xlsx on its own dedicated extractor), writes the extracted Markdown to workdir as <original-basename>.md, and pushes that .md path into savedDocPaths — the agent reads the .md (not the binary), and the prompt prefix points at the .md. On extraction error the binary stays as a chip, the .md is not created, the filename goes onto a failedOfficeExtractions list, and after the bucket loop a system-source warning row is inserted in conversation_messages and pushed via SESSION_OUTPUT so the renderer renders it immediately.

  3. Prompt build. Operator-attached doc paths and auto-injected .claude/docs/ paths are deduped via a Set and prepended via buildPromptWithAttachments — operator paths come first so they read naturally above any project-wide knowledge files. If the operator sent only attachments and no text, the prompt becomes DEFAULT_IMAGE_MESSAGE ("What's in this image?") so the model has something to act on, but the UI/DB store the empty displayText so the chat history looks the way the user typed it.

    The renderer's sendResponse payload (session-store) carries three optional fields: displayText is a hidden-from-bubble override (the backend persists displayText ?? text; Ask-page follow-ups pass the question while re-captured context stays in text); pastedTexts is omitted entirely when empty so a caller with no chips sends a byte-identical payload, and the backend splices each chip's content into text; answersCard is sent only when an inbox card's answer box set it.

  4. CLI delivery. The 9-arg processManager.writeToStdin(sessionId, prompt, isAutoResponse, attachments, displayText, images?, metadata?, documents?, pastedAttachments?) call carries the partitioned arrays through to NDJSON write, where they become Anthropic Messages API content blocks in documents → images → text order (per Anthropic's vision best-practice: content blocks first, then the textual instruction). The 9th argument pastedAttachments carries the splice-range metadata for pasted-text chips that get spliced back into the prompt body.

  5. Failure cleanup. If writeToStdin throws (bad NDJSON, stdin closed, etc.), the main process best-effort unlinks every path in savedDocPaths — so a retry from the user doesn't fight collision suffixes from a failed prior attempt.

The reason text docs go through path-injection rather than as document blocks is two-fold: first, the Anthropic API only accepts document blocks for PDFs (vision-rendered), not arbitrary text. Second, dropping a text file on the workdir gives the agent a real file it can Read and edit — an inline content block would be read-only data the agent can quote but not modify. Workdir-saved docs are first-class repo files for the rest of the session.

Cleanup happens at the same point that purges all the rest of a session's data: when retention sweeps it via purgeExpiredData in queries-retention.ts. For each soft-deleted session past the retention cutoff, the function JOINs against projects to recover the folder_path, resolves it through resolveProjectWorkDir, and rm -rfs <workdir>/.claude/amc-attachments/<sessionId>/ alongside the existing <userData>/attachments/<sessionId>/ cleanup. Sessions whose project row was already hard-deleted in the same transaction get logged and skipped — recovering the workdir requires the project row, and orphans are rare enough to be cleaned by hand.

Archiving (soft-delete) is separate: it does NOT remove attachment files. The bytes survive the session row until retention catches up — which is what allows un-archive to keep working.

One shared preparation for every send road

Every road that sends attachments — the Claude send, the other-engine send, the new-session launch and Send Later — prepares them through ONE function, prepareAttachments. It partitions, writes the userData chip twin, saves each file under <workdir>/.claude/amc-attachments/<sessionId>/ and extracts Office files to .md. The only switch is whether images also become files (other engines) or stay inline content blocks (Claude). The per-file saves and Office extractions run concurrently, and the results are assembled in a fixed order (images → PDFs → text docs → Office) so the prompt and the chips always read the same way.

  • The userData twin is unconditional. Every attachment writes its <userData>/attachments twin before, and independent of, the workdir copy or the Office extraction. That twin is the UI-chip copy AND the only copy the backup mirror captures (collectAttachments is rooted there); the workdir file is engine scratch no backup sweeps.
  • No project folder is not a drop. A session with no project folder saves into <userData>/attachments/.claude/amc-attachments/<sessionId>/ and the agent still gets the path. (Before the shared prep, the Claude send silently lost text and Office paths in that case.)
  • Send Later carries Office files. Its old private copy had no Office branch, so a scheduled .docx never reached the agent; it now reaches it as extracted Markdown like every other road.

Cloud sessions — the files go to the machine the agent runs on

A cloud session's agent runs on its cloud machine, not this computer, so a path on this computer means nothing to it. The preparation above stays machine-blind; the cloud road is only a router. Every cloud turn crosses ONE seam — the SSH spawn in spawn-cluster-manager.ts, because a supervised cloud child is never reused — and right before the prompt is written there, routeSessionAttachments:

  • finds each prompt line that is EXACTLY an existing file under THIS session's own attachment folders (the workdir one and the userData fallback) — a path elsewhere, another session's folder, or a .. escape is never shipped;
  • copies it over ssh to <remote working dir>/.claude/amc-attachments/<sessionId>/<name> (the machine is awake at this point, which is why the copy is here and not at preparation time — a reply to a parked session prepares its files before the machine wakes);
  • plants /.claude/amc-attachments/ in the remote repo's info/exclude before writing, so neither the agent's own git add nor the work capture carries the files home;
  • swaps the line to the remote path, and posts one visible warning row naming any file it could not copy.

Images and PDFs on a cloud Claude session also still ride inline in the message itself. Only engines that run the claude binary are admitted to the cloud today, so this one seam covers every cloud session. A person's OWN (non-cloud) ssh remote is routed the same way on each spawn, and a warm turn there — which reuses the live process and never crosses the spawn seam — is routed in the message router's dispatcher (writeToStdin in user-message-router.ts) before the send's decision body. The copy runs on the same per-session send chain a crew lead's memory claim uses, so the body keeps its single synchronous window (the F004 contract) and a plain send right behind it can never overtake a send that is still copying files. Only a live, non-supervised ssh session whose message names its own attachment files waits for anything; every other send is untouched.

Non-Claude engines — attachments via workdir paths

The send pipeline above is the Claude path (Anthropic content blocks + inline images). Non-Claude engines have no inline image/document protocol, so they receive attachments as files in the workdir with their paths injected into the prompt: the shared prepareWorkdirAttachments saves each attachment (images, PDFs, text docs, and office docs as extracted .md) under <workdir>/.claude/amc-attachments/<sessionId>/, and buildPromptWithAttachments prepends the paths so the agent opens them with its own file tools.

  • Codex sends image paths on its dedicated localImage channel and injects doc paths into the prompt.
  • One-shot CLIs (Cursor, OpenCode, Antigravity) have no separate image channel, so ALL paths (images + docs) ride the prompt; pasted-text chips splice in the same way. Before the cursor-attachments fix this send branch dropped images + pastedTexts entirely — they're now delivered and persisted on the operator row (provider-registry contract, the-send-verb-is-one-shared-port).
  • The slim ACP engines (Hermes, Kimi Code) send an image inline as an ACP image block when their CLI advertised image support on its start-up handshake, and post a visible note in the session when it did not (the image is then withheld — never a silent drop). They do not deliver documents; the compose area warns before the send (engine-onboarding contract, abilities-are-discovered-not-assumed).

Because delivery is by file path, document/text/code attachments work for any file-capable agent; image vision depends on the engine's own multimodal file handling (best-effort on a CLI that may not interpret an image file).

How pasted-text attachments work

Pasted-text is the one bucket that doesn't come from the file system — it comes from a paste against the textarea (Ctrl+V, or Windows Win+V / the emoji panel / an IME). The composer's paste handler in useSessionPanel.ts classifies the clipboard payload by length and routes it:

  • raw.length > 5,000 (PASTE_AS_ATTACHMENT_THRESHOLD, strict >) — chip path. e.preventDefault(), capture the textarea's selectionStart as the insert position, push a PastedTextAttachment row into pendingPastedTexts, render a chip with the first line as preview. The textarea content is unchanged — the user keeps typing around the chip.
  • 5,000 chars or fewer — fall through to the existing "trim-equality" branch (a no-op for clean text, a programmatic splice for trimmed text), then to the native browser paste, which inserts the text directly into the textarea.

Keep a long paste in the box: Ctrl+Shift+V (Cmd+Shift+V on a Mac). Paste with that shortcut instead of Ctrl+V and a long paste goes straight into the box as text you can edit, with no chip — in the session composer and in every other box that uses the same paste handling. The shortcut also pastes plain text, so formatted content is not converted. If the paste would not fit under the box's 500,000-character limit it is still attached as a chip, and a short message says why. The first time a long paste becomes a chip, a tip names the shortcut; choose Don't show again to stop it.

A warning before the box is full. Once a message reaches 450,000 characters (90% of the 500,000-character limit), a small line under the box shows how many characters are left; at the limit it turns red and says nothing more will fit, so you are never left wondering why typing or pasting stopped working. Both ideas are adapted from T3 Code (MIT).

The threshold is a compromise: small pastes feel natural inline (a function signature, an error line); huge pastes (a 50-line stack trace, a JSON blob, a chat transcript) would otherwise visually overwhelm the composer. 5,000 chars roughly corresponds to a screen of dense code — anything bigger gets the chip treatment.

A second door — beforeinput (mobile AND desktop). The handler above hangs off the React paste ClipboardEvent, which most desktop Ctrl+V fires with the full clipboard text. But several paste sources commit text through the editing path instead — a native beforeinput event (inputType: insertText / insertFromPaste) with no paste event at all: mobile soft keyboards (Android GBoard especially), AND on the desktop the Windows clipboard-history popup (Win+V), the emoji panel, and various IMEs. Without a second listener the chip path never runs for those: no chip, and the browser truncates/floods the big insert ("it just cuts it off on the chat box"). useLargePasteBeforeInput listens at that beforeinput door — a single insert over the 5,000-char threshold is unambiguously a paste, so it cancels the truncating native insert and routes the text through the same addPastedText chip path. One further wrinkle (fixed 2026-07-10): some mobile IMEs also truncate the text they hand that beforeinput event on event.data / dataTransfer, so chipping the event payload alone still lost text (the "capped at ~5,000 tokens on mobile" report). After preventDefault() the hook therefore asks navigator.clipboard.readText() for the authoritative full document. The paste lands first (fixed 2026-10-12): the chip is placed at once from the event payload, and the clipboard read only upgrades THAT chip in place when it comes back longer — because on Android Chrome the read can sit behind a permission prompt, and while the hook used to wait for it, a send in that gap went out with the typed text alone ("it auto sent after pasting"). The upgrade replaces the chip only while it still holds the untouched payload (an edit made meanwhile wins), and an unavailable / denied / shorter read leaves the payload chip as it is, so it is never worse than before. The session composer arms it on every platform (enabled: true): the earlier browser-only gate wrongly assumed paste always fires on the desktop app, so a large Win+V paste flooded the desktop composer instead of chipping (fixed 2026-08-04). It can't double-fire with the paste handler because a canceled paste event emits no follow-up beforeinput. The Quick Launch composers (the "Ask Omniscio" tab and the New Session box) now arm the same fallback too — each co-located with its own textarea, routing large inserts into the shared engine's usePastedTextComposer.addChip — so a big mobile paste chips there as well instead of truncating (fixed 2026-08-10; before this the QL boxes had the paste-path chip engine but not this second door). See composer-paste-engine-contract.md.

The clipboard-history picker is a third door. Pasting a copy from Omniscio's clipboard-history picker (Win+V) into a session composer arrives over IPC rather than as a paste / beforeinput event, but a text over the same 5,000-char threshold still collapses into a chip: handleClipboardInsertText routes it through the same addPastedText path (in both composer modes) instead of dumping the whole block inline. See clipboard-history.md.

Splice on send (no delimiter). When the user finally hits send, spliceTypedTextWithPastedChips walks the pendingPastedTexts array (sorted by insertPosition, ties broken by ordinal) and inserts each chip's content at its captured offset. There is no wrapper, no --- pasted --- marker, no fenced code block — the bytes land in the prompt body exactly where the user pasted them, indistinguishable from typed text. The function returns both the spliced string AND a parallel array of {id, ordinal, start, end, preview} range metadata; the splice points are pre-computed once so the renderer never has to walk the chips again.

Race-safety on send failure. executeSend clears the chip strip BEFORE awaiting the IPC, mirroring the existing pendingImages flow — the user's textarea snaps back to empty immediately so a fast re-paste doesn't double-fire. If sendResponseAndNavigate returns success: false, the chips (with their original ids, contents, and insert positions) are restored from the snapshot held in the closure. Without this restore the user would lose the only copy of what they pasted, which would be much worse than the cosmetic flicker.

Per-session isolation. sessionPastedTextDrafts (a Map<sessionId, PendingPastedText[]> outside the React tree) holds chips across panel unmounts the same way sessionDrafts and sessionImageDrafts hold textarea text and image chips — so mid-paste navigation between two sessions doesn't leak chips between them. Archive clears the per-session entry so unarchive doesn't bring stale chips back.

Durable across reload. As of 2026-06, a pending pasted image or pasted-text chip also survives a full app reload / mobile tab-reap — the same durability the typed text beside it already had. Both in-memory Maps are serialized to one JSON blob in a sessions.draft_attachments column (the sibling of draft_text), written debounced when attachments change, re-read when the session's panel mounts, and cleared the instant you send (restored if the send fails). localStorage is deliberately NOT used for this layer — base64 image data URLs blow its ~5 MB quota — so it's SQLite-only; the image's base64 is dropped before storage and re-derived from its dataUrl on restore. This replaced the old "Pasted attachments clear if you reload" composer warning, which is now gone. Full mechanics + the test-locked invariants: attachment-draft-persistence-contract.md.

Persistence in chat history. The spliced prompt body is what Claude sees, and what gets stored in conversation_messages.body. Alongside it, the splice's range metadata is serialized to a new pasted_attachments JSON column on the same row (migration v121). When the message renders in history, the markdown viewer paints a chip overlay at each [start, end] range — collapsing the inline blob back into a Quote-icon chip the user can click to expand. This means the agent always sees the literal text in context, but the operator's view of their own message stays compact.

The first half of this page covers the user-facing half — the attachment routes, the chips, the caps and the large-draft warnings. The composer surfaces that fire a send with attachments already in place are on the quick responses page, files dropped into a project’s docs folder ride the same delivery path and are covered in project docs auto injection, and what to do when a send appears to work but nothing comes back is in session stuck in needs you.

Last verified 2026-10-16