feat(chat-runtime,host-service): every adapter hands the agent its attachments

Closed
SU
15d ago
+697-74

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 from mount.ts):
    • fileId set: use the box's cached copy (handOutAttachmentByFileId), or else importCloudAttachments it 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 gets null.
  • chat-runtime types: AttachmentPart, ResolvedAttachment, ResolveAttachment in harness/types.ts. ACP's resolveAttachment now gets the whole part instead of an attachmentId. AcpAttachment stays 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 image block 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 attachmentId or fileId (it required attachmentId before), so a client can send a cloud part by fileId alone. Mobile's UserMessageBubble keeps 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.0 is 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-version is 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 inside acpHarnesses.ts, because three adapters now use it. It is passed through createChatV3Mount({ 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: attachmentId is now optional, and at least one of the two ids is required. An older host still requires attachmentId, so a fileId-only part sent to it fails validation. That is why clients send parts only at or above ATTACHMENT_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 text fixture, turn/start params now recorded by FixturePlayer): an image becomes localImage; 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.
    • attachedFilesBlock format.
    • 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; fileId wins 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 same health.check sandbox-mode test that fails on #8846: it reads this machine's real boot stamps, because this workspace is a real cloud box.
  • bun run typecheck passes 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 in UserMessageBubble, 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.