fix(adapters): preserve orphan tool image carriers

[lidge-jun]

Summary

• Stack layer 4, depends on fix(protocols): make image reference boundaries explicit #3591 → test(protocols): cover external image wire roundtrips #3589 → fix(chat): preserve external screenshot tool results and image detail #3586. Review this layer's diff only.
• Preserve orphan screenshot results in Anthropic and Command Code as provenance-labeled user image content; never serialize base64 pixels into prompt text or silently omit the image.
• Reuse existing image mapping/normalization. Keep valid tool-result batches before orphan carriers and preserve exact image-free behavior; no fabricated successful tool pairing.
• Add duplicate, unmatched, standalone, barrier and pending-call regression coverage. Native capability/URL policies are unchanged.

Verification

• Current stack, merge bottom-up: fix(chat): preserve external screenshot tool results and image detail #3586 → test(protocols): cover external image wire roundtrips #3589 → fix(protocols): make image reference boundaries explicit #3591 → fix(adapters): preserve orphan tool image carriers #3593 → fix(cursor): prepare active tool screenshot batches #3595 → fix(cursor): attach external tool screenshot provenance #3596. All source slices received independent gpt-6-astra high review with no unresolved findings.

• The layer-2 CI failure was traced to the existing late-spill test's outer wall clock; a scoped clock spy and publication-tail cleanup repair preserves every assertion/timer/budget. No production state code changed. Higher layers were cascaded with explicit leases; range-diff confirms identical image patches. Latest-head CI remains pending.

• Standalone adapter-body reproduction (no network): both native image fields absent before; both present after, exit 0. Anthropic text no longer contains image bytes.

• node node_modules/typescript/bin/tsc --noEmit: exit 0. Both changed test files statically bundle; suites run in GitHub CI only per explicit owner instruction.

• Public docs build: 425 pages, exit 0. Independent seven-file patch review passed.

• Push uses --no-verify solely because the installed hook runs the prohibited local full suite. Exact-head CI and resolved findings are required before merge.

• Owner authorizes admin merge/approval bypass after CI. All merges remain on hold until the expanded all-format audit and Cursor follow-up are complete.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults: no new fetching, credential handling, logging, or tool execution.

Summary by CodeRabbit

• New Features
  • Preserved images from unmatched tool results when converting conversations through Anthropic and Command Code adapters.
  • Maintained image ordering and provenance while retaining existing tool-call pairing behavior.
• Documentation
  • Documented how image-bearing unmatched tool results are represented in proxy-format requests.
• Tests
  • Added coverage for image URLs, data images, unmatched and duplicate results, and conversation boundary scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 5eb4f538-7e73-4c1f-b2c7-bdf6c01b489a

📥 Commits

Reviewing files that changed from the base of the PR and between 7484cc5 and 75dc09e.

📒 Files selected for processing (7)

• devlog/_plan/260905_external_image_roundtrip/003_all_format_audit.md
• devlog/_plan/260905_external_image_roundtrip/040_orphan_image_carriers.md
• docs-site/src/content/docs/reference/proxy-formats.md
• src/adapters/anthropic.ts
• src/adapters/command-code.ts
• tests/adapters/adapter-usage.test.ts
• tests/providers/command-code-provider.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

Anthropic and Command Code adapters now preserve images from orphan tool results in provenance-labeled user carriers. Text-only behavior remains unchanged. Tests cover pairing, barriers, outstanding calls, data URLs, HTTPS URLs, and ordering. Documentation describes the updated contract.

Changes

Orphan image carrier preservation

Layer / File(s)	Summary
Anthropic orphan content handling src/adapters/anthropic.ts, devlog/_plan/260905_external_image_roundtrip/040_orphan_image_carriers.md	Adds orphanToolResultContent at lines 645-657. Image-bearing orphan results become labeled content arrays with mapped image parts and filtered empty text. The assistant accumulator accepts mixed content at line 753. Both orphan paths use the helper at lines 766-767 and 788-789.
Command Code image carrier wiring src/adapters/command-code.ts, devlog/_plan/260905_external_image_roundtrip/040_orphan_image_carriers.md	Extracts and wires images once at lines 111-113. Orphan carriers include the images at lines 122-126. Paired results reuse the wired images at lines 138-139.
Adapter and provider validation tests/adapters/adapter-usage.test.ts, tests/providers/command-code-provider.test.ts	Tests cover standalone, duplicate, unmatched, barrier, and outstanding-call scenarios. They verify image sources, media types, ordering, empty-text filtering, and unchanged image-free text behavior.
Documented behavior and audit records docs-site/src/content/docs/reference/proxy-formats.md, devlog/_plan/260905_external_image_roundtrip/003_all_format_audit.md	Documents provenance-labeled user carriers without fabricated successful calls or embedded image bytes. Records confirmed baseline exit code 1 behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to a244b

Orphan tool-result images are retained without embedding image data in prompt text or fabricating tool pairings, with coverage for the relevant ordering and fallback cases.

Sequence Diagram(s)

sequenceDiagram
  participant ToolHistory
  participant AnthropicAdapter
  participant CommandCodeAdapter
  participant UserCarrier
  ToolHistory->>AnthropicAdapter: provide orphan tool result
  AnthropicAdapter->>UserCarrier: emit provenance text and image content parts
  ToolHistory->>CommandCodeAdapter: provide orphan tool result
  CommandCodeAdapter->>UserCarrier: emit text carrier and wired image carriers

Loading

Suggested reviewers: luvs01

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: preserving orphan tool image carriers in the Anthropic and Command Code adapters. This matches the implementation and test changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files. (3 skipped: 3 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/orphan-image-carriers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 54 / 80

이 PR은 외부 이미지 라운드트립 스택의 4번째 층입니다. 베이스는 dev가 아니라 codex/image-reference-boundaries(#3591)이고, 그 아래는 #3589 → #3586으로 이어집니다. 헤드 브랜치는 codex/orphan-image-carriers입니다. GitHub 상태는 MERGEABLE이고, 라벨은 bug입니다.

하는 일을 쉽게 말하면 이렇습니다. 도구 결과(tool result) 안에 스크린샷 같은 이미지가 들어 있는데, 옆에 짝이 되는 tool_use / tool call이 없을 때가 있습니다. 예전 Anthropic 어댑터는 그 고아 결과를 orphanToolResultText로 글자만 남겼고, 이미지 바이트를 JSON 문자열에 넣거나 사실상 프롬프트 텍스트로 밀어 넣었습니다. Command Code 쪽은 고아 경로에서 이미지를 아예 빼고 텍스트 캐리어만 올렸습니다. 이 PR은 둘 다 “짝을 가짜로 만들어 주지 않으면서” provenance 라벨이 붙은 user 캐리어에 이미지를 네이티브 파트로 남깁니다. 유효한 pending call의 tool_result는 여전히 캐리어보다 앞에 옵니다.

지금 dev HEAD는 3c920af5f(Windows CI shard #3572, package 2.43.0 방향)입니다. 이 층의 코드는 src/adapters/anthropic.ts와 src/adapters/command-code.ts만 손대고, 문서·devlog·테스트가 따라옵니다. dev의 Anthropic은 아직 orphanToolResultText만 쓰고, Command Code orphan 경로는 텍스트만 push합니다. 즉 이 버그 고침은 스택이 dev에 닿기 전까지는 HEAD에 직접 안 들어갑니다. PR 본문도 “expanded all-format audit와 Cursor follow-up이 끝나기 전엔 머지 보류”라고 적어 두었습니다.

테스트는 시나리오를 꽤 넓게 잠급니다. standalone / duplicate / unmatched / user barrier / outstanding other call, data URL과 HTTPS, mixed/empty text, 텍스트에 base64가 안 섞이는지, 가짜 페어링이 없는지까지 봅니다. CI는 linux test shard와 gates는 통과 쪽이고, macos 일부는 아직 pending으로 보입니다. CodeRabbit은 draft로 스킵된 기록이 있어 상태 확인이 한 번 필요합니다.

라인 / 경로로 보면 아래를 보면 됩니다.

경로 src/adapters/anthropic.ts orphanToolResultContent - 이미지 없는 고아는 예전 orphanToolResultText를 그대로 돌려준다. 이미지 있으면 provenance 텍스트 블록 + toAnthropicContentPart 매핑이다. 빈 텍스트 필터는 toAnthropicToolResult와 같은 패턴이다
경로 src/adapters/anthropic.ts orphanBlocks: unknown[] - 예전 Record 배열에서 unknown[]로 바꿨다. spread로 string/array를 합치려는 타입 맞춤이다. 동작은 맞지만 orphanBlocks를 나중에 좁히면 캐스팅이 다시 생길 수 있다
경로 src/adapters/command-code.ts - 이미지 추출을 paired/orphan 분기 앞으로 올렸다. orphan user content에 ...images를 붙이고, paired 경로의 pendingImageCarriers는 이미 매핑된 wire 파트를 재사용한다. 중복 매핑을 피한 점은 좋다
경로 src/adapters/command-code.ts orphan 텍스트 - 여전히 toolResultText로 텍스트를 만든다. 이미지 파트는 옆에 붙지만, 텍스트 쪽 [image] 마커와 네이티브 이미지 파트가 겹쳐 보일 수 있는지 한 번 확인이 필요하다
경로 베이스 스택 #3586 → #3589 → #3591 → 이 PR - dev 직행이 아니다. 아래 층이 바뀌면 이 층도 다시 맞춰야 한다
경로 PR 본문 merge hold - audit(050/060)과 Cursor follow-up 전까지 머지하지 말라고 적혀 있다. 리뷰만 하고 랜딩은 보류가 맞다

메인테이너의 판단이 필요한 지점

• 스택을 아래부터(fix(chat): preserve external screenshot tool results and image detail #3586) 순서대로 dev에 올릴지, audit이 끝날 때까지 네 층을 전부 열어 둘지
• Command Code orphan 텍스트의 [image] 마커와 네이티브 image 파트를 둘 다 남길지, 마커를 줄일지
• 이 층만 먼저 cherry-pick 해서 dev에 올릴 가치가 있는지(비추천: 아래 계약 층에 의존)

너의 추천
지금 당장 dev에 머지하지 마세요. 스택 아래 #3586 → #3589 → #3591이 먼저 안정적으로 랜딩하고, 본문이 말한 all-format audit / Cursor follow-up이 끝난 뒤에 이 층을 exact-head CI 초록으로 올리세요. 코드 방향(고아 이미지를 텍스트로 죽이지 않기)은 맞고 types/config 대형 스플릿에 무효화되는 형태도 아닙니다. 중복 PR로 닫을 대상이 아니라, 순서 대기 중인 정상 bugfix입니다.

이 댓글은 grok-bot이 작성했습니다

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T05:50:25.152434Z	109319b	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.