feat(chat-runtime,host-service): every adapter hands the agent its attachments
Closed
SU
15d ago+697+697+012345678901234567890123456789-74-74-01234567890123456789
Stacked on #8846 (plan PR 3). It needs that PR's handOutAttachment / handOutAttachmentByFileId and the fileId index. The base is #8846's branch so the diff shows only this change. Retarget to main once #8846 merges.
#8843 (AdapterEvent kind → type) touches the same adapter files. A dry-run merge of this branch with #8843's head is conflict-free (git merge-tree), and the new code here emits no events. If #8843 lands first, I'll rebase this on main.
Summary
PR 4 of the attachments plan (v6), seam 4: every harness gets the file, from whichever id the part carries. Claude SDK and Codex stop dropping attachments, and all three adapters share one host resolver.
Why
- The Claude SDK adapter turned an attachment part into the text
[name]. The Codex adapter dropped it, with the notice "Attachments are not supported by the codex harness". Only ACP sent the file. That is why desktop chat still puts attachments into the text as path tags, and so desktop and mobile can't render each other's attachments. - A cloud part (
fileId) has to resolve on a box whose store is empty, for example a recreated box resuming a session. No adapter could do that.
How it works
- One resolver (
host-service/src/chat-v3/resolveAttachment.ts, passed to ACP, Claude and Codex frommount.ts):fileIdset: use the box's cached copy (handOutAttachmentByFileId), or elseimportCloudAttachmentsit now and use that.- otherwise
attachmentId: the host store entry (handOutAttachment). - Both paths stamp
lastUsedAt. Bytes are read (base64) only for images. Other files go by path, so a 200 MB PDF is not read into memory. A thrown error (for example a failed import) goes to Sentry (reportAttachmentResolveFailure), and the adapter getsnull.
- chat-runtime types:
AttachmentPart,ResolvedAttachment,ResolveAttachmentinharness/types.ts. ACP'sresolveAttachmentnow gets the whole part instead of anattachmentId.AcpAttachmentstays as an alias. attachedFilesBlock(harness/attachedFiles/):# Attached files … - <name>: <path>. Store files are named<id>/<id>.<ext>, so a bare path would give the agent only a UUID.agents.run's terminal-launch block uses it too, so it now lists names as well.- Claude SDK adapter: an image (png/jpeg/gif/webp) goes as a base64
imageblock in the SDK's content-array form. Any other file goes as the attached-files text. A file that can't be resolved goes as[name: could not be read]. - Codex adapter: an image goes as app-server's
{ type: "localImage", path }. Any other file goes as the attached-files text, and an unresolved one as the same "could not be read" text. As the plan says, we send the image even to a text-only model and let app-server reject it. - Order: both adapters chain attachment resolution, so a prompt sent while an earlier one is still resolving goes second. A text-only prompt with nothing queued is still pushed synchronously, the same as before.
- Protocol: the attachment part now needs
attachmentIdorfileId(it requiredattachmentIdbefore), so a client can send a cloud part byfileIdalone. Mobile'sUserMessageBubblekeeps showing parts that have a host id and skips a fileId-only part for now. The mobile PR adds the cloud branch. ATTACHMENT_PARTS_MIN_HOST_VERSION = "1.41.0"in@superset/shared/attachment-limits.desktop-v1.40.0is the latest tag, and this is not in it. If this misses 1.41.0, raise the constant before the desktop PR uses it.hostReadsAttachmentParts(version)in@superset/shared/host-versionis the client-side check, so desktop (#8851) and mobile use the same rule. It coerces the version, so a canary or dev build of 1.41.0 or later counts (tested at, above and below the floor, and for an unknown version).
Where this differs from the plan, or the plan is out of date against main
- The resolver is in its own file,
chat-v3/resolveAttachment.ts, not insideacpHarnesses.ts, because three adapters now use it. It is passed throughcreateChatV3Mount({ api })so the box import has an API client. - No PostHog event. The plan asks for Sentry and PostHog on every resolve failure. host-service has no PostHog client, so this PR sends Sentry only.
- I did not do the "store path outside the worktree" check for Codex and Claude. The plan wants it from PR 3's fixtures and this PR's manual run. Both adapters pass the absolute store path, and the plan's argument (app-server and the SDK read as the host user, not inside the agent's sandbox) is not verified here. See Testing.
tRPC / version compatibility
- No tRPC procedure changes.
- The schema change to the part is looser:
attachmentIdis now optional, and at least one of the two ids is required. An older host still requiresattachmentId, so a fileId-only part sent to it fails validation. That is why clients send parts only at or aboveATTACHMENT_PARTS_MIN_HOST_VERSION. No client on main sends a fileId-only part yet. Parts the host builds itself (#8846) carry both ids.
Testing
- chat-runtime
bun test: 384 pass, 0 fail (the Claude adapter suite is 38/38 after 45ec9752a1). New tests:- Claude: an image part becomes an image block; a non-image becomes name + path; an unreadable part is named; a prompt sent while an attachment resolves goes second.
- Codex (real recorded
textfixture,turn/startparams now recorded byFixturePlayer): an image becomeslocalImage; a non-image becomes name + path; an unreadable one is named. - ACP: the resolver gets the whole part (fileId-only). The existing image / non-image / missing tests were kept and moved to the new resolver type.
attachedFilesBlockformat.- Claude: an empty text part is dropped (commit 45ec9752a1). An attachment-only message can carry one, and the Anthropic API rejects an empty text block.
- host-service
resolveAttachment.test.ts: a host part reads from the store; a fileId part on a box with a cached copy does not import; a fileId part on an empty store imports;fileIdwins when both are set; a missing id gives null; a failed import is reported and gives null; a non-image's bytes are not read. - host-service
bun test: 2651 pass, 1 fail. The failure is the samehealth.checksandbox-mode test that fails on #8846: it reads this machine's real boot stamps, because this workspace is a real cloud box. bun run typecheckpasses in chat, chat-runtime, host-service, cli and apps/desktop. apps/mobile has the same 190 errors with and without this PR (I diffed the error lists; this PR first added 2 inUserMessageBubble, which are fixed). Biome is clean on the changed files.- Not verified: no live Claude or Codex run. I did not check that either agent actually opens an image or a store path outside the worktree, and I did not try a recreated box. Those are the plan's manual checks for this PR and the desktop PR.
Known limitations
- On a host older than 1.41.0, a fileId-only part fails validation. That is what the version gate is for (desktop PR).
- On a box, a cloud part whose copy was never imported and whose file is gone from storage reaches the agent as "could not be read". That is the intended fallback.