Skip to content

feat(coding-agents): opt-in typed image attachments for coding-agent integrations - #680

Draft
nik13 wants to merge 13 commits into
feat/attachments-ts-corefrom
feat/attachments-ts-coding
Draft

nik13 wants to merge 13 commits into
feat/attachments-ts-corefrom
feat/attachments-ts-coding

Conversation

@nik13

@nik13 nik13 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Part of TH-2379 (Linear).

Coding-agent image attachments on top of the TypeScript attachment core (#677). Stacked on feat/attachments-ts-core; keep as draft until the attachments reconciliation pass.

What it does

Attachments stay OFF unless FI_ATTACHMENTS_ENABLED is set and the server session allows them. Every path goes through the provider-owned fi-core AttachmentManager, so the deny-wins lattice applies: hide inputs/outputs/input images/error details, content capture off, private turns, FI_PII_REDACTION (gives redaction_unavailable at the core), and server scope. On the Cursor SDK path the instrumentation's own trace config is applied too: any of hideInputs, hideInputMessages, hideInputText, hideInputImages or piiRedaction (option or env) attaches with captureContent:false (policy_denied), which the core cannot relax. agent-core sends FI credentials only to an attachment endpoint on the approved OTLP destination's origin. Every image is preflighted (manager.preflight) before its base64 is read; only an admitted image is read, strictly validated and decoded. Spans carry only fi.attachment.refs, never the bytes. No path, URL or file is fetched.

  • agent-core: createTurnTracer({ attachments }) shares the provider's manager. TurnHandle.images() and ChildHandle.images() take typed inline image blocks, and so does captureAgentImages(manager, span, blocks, options). Two shapes are read: Pi/OMP {type:"image", mimeType, data} and Anthropic {type:"image", source:{type:"base64", media_type, data}}. Each call has a 256 KiB budget that counts only admitted bytes. inspectStatus().attachments reports state and source readiness per adapter id.
  • Pi plugin and oh-my-pi plugin: user prompt images go on the turn root. Tool-result images go on their tool span, with tool_call_id.
  • Claude Code: the hook reads the transcript with the existing secure open (O_NOFOLLOW, owner check, single hard link). Prompt images go on the final root only; a deferred root never uploads. This prompt's tool-result images go on their tool spans. The hook waits for bootstrap for up to 2 s, and only when attachments are enabled. A symlinked transcript causes no read and no egress.
  • Cursor SDK: new attachments: provider.attachments option. Inline { data, mimeType } send images go on the run span. The package default (hidden inputs) still denies capture; { url } images are never read. A type contract pins the inline SDKImage variant on 1.0.37 and 1.3.1.
  • CI: new workflow coding-agent-attachments-tests.yml, which runs on any base branch.

Not supported (fails closed)

  • Codex SDK local_image is a path (LocalFile). It is never read or exported.
  • RemoteUrl, file and provider sources are not supported. Streams and imports are not used: every host hands over complete inline images, so there is no consumed byte stream.
  • Hosts without inline image bytes report source_unavailable: Codex/Cursor hooks, OpenCode, OpenClaw, Hermes, Goose, Gemini, Copilot, Kiro, Antigravity, Augment, Devin, Grok and Muse.
  • pi-coding-agent is not bound, because binding it as well as the Pi plugin would upload the same image twice.
  • Images that arrive before bootstrap completes are skipped, not queued.

Qualification (private GCP VM, deleted afterwards; Node 22.19.0 unless noted)

The VM ran the 99ad622 source, then the two test-only fixes that are now in 5dd669e (the Pi harness, and the XDG fixture isolation).

Suite Result
agent-core full suite 471/471
pi-plugin 47/47
oh-my-pi-plugin 39/39
claude-code (includes 12 attachment tests) 59/59, and 59/59 with a runner-style XDG_CONFIG_HOME (was 34/59 before the fixture fix)
cursor-sdk jest 220/220
pi-coding-agent jest 56/56
Cursor attachment tests and type contract with real @cursor/sdk 1.0.37 and 1.3.1 7/7 on each version, contract passes on each
Real Pi host over loopback HTTPS (broker, OTLP and mock model), 8 scenarios each, on Pi 1.5.0 (workspace pin) and 1.5.2 (latest) 16/16
OMP plugin API over real HTTPS, 8 scenarios 8/8 on Node 22.19.0 and 8/8 on Node 24

In the real-host scenario with attachments enabled, the upload is byte-exact, is parented to the tool span, and its occurrence appears in fi.attachment.refs. Content and complete calls use only the write capability, never the FI keys. These scenarios uploaded nothing: disabled, hide inputs, hide outputs (tool image), hide input images, PII, content off, and scope denied. OTLP never contained the image bytes or the capability.

GitHub CI: the Coding-agent attachments workflow passes on Node 22.19.0 and Node 24 at head 5dd669e. It runs every suite above, plus real Pi 1.5.0 and latest over HTTPS, and the OMP wire test.

Fixture fix: the Claude Code hook tests now set XDG_CONFIG_HOME inside the fixture home. GitHub runners export their own value, which made 25 existing hook tests fail there.

Not run: a real signed-in Claude Code host (BLOCKED, needs host login), a real OMP/Bun host, and product playback.

Fix pass 2026-11-11 (head 4ac7dc3)

Two review findings (P1, blocking), each with regression tests:

  1. Cursor SDK ignored the instrumentation's own hide/PII flags for images. The provider-owned manager never sees the instrumentation's traceConfig, so an image could upload while the prompt text on the same span was masked. Now tracingContext() passes the generated trace config through RunTracer into captureCursorImages. hideInputs, hideInputMessages, hideInputText, hideInputImages and piiRedaction all attach with captureContent:false, matching the OpenAI and Anthropic adapters. Tests: four instrumentation flag cases and four env cases (FI_HIDE_INPUT_IMAGES, FI_PII_REDACTION, FI_HIDE_INPUT_TEXT, FI_HIDE_INPUT_MESSAGES). Each asserts zero base64 reads, zero uploads and no broker calls after bootstrap.
  2. A saved-profile credential could reach an unapproved FI_ATTACHMENTS_ENDPOINT origin. agentAttachmentRuntime now uses an endpoint (from options or env) only when its origin equals config.endpoint's origin. Otherwise it returns no credential headers, and the manager gets a guarded transport that reports endpoint_unconfigured. That way fi-core never builds its own transport from FI_ATTACHMENTS_ENDPOINT. agentAttachmentStatus applies the same rule. Tests: status and runtime origin unit tests, plus a real-TLS child-process test. That test uses a saved profile from setup(configureOnly) and real resolveConfig. The FI_BASE_URL control gives DESTINATION_NOT_APPROVED. The unapproved origin received 0 requests and the state was endpoint_unconfigured. As a positive control, the approved origin received the bootstrap carrying the saved key.

Re-qualification (private GCP VM, deleted and verified gone afterwards; Node 22.19.0 unless noted):

Suite Result
agent-core full suite 473/473 (471 before, plus 2 new tests)
pi-plugin / oh-my-pi-plugin / claude-code 47/47, 39/39, 59/59
cursor-sdk jest / pi-coding-agent jest 228/228, 56/56
Cursor attachment tests with real @cursor/sdk 1.0.37 and 1.3.1, plus the type contract 15/15 on each, contract passes
Real Pi host over HTTPS (1.5.0 floor and latest); OMP wire pass; 8/8
Node 24: agent-core attachments, claude-code attachments, OMP wire pass
Mutation control: 4ac7dc3 tests on the 5dd669e sources agent-core: 3 new tests fail; cursor: 8 new tests fail
Reviewer repros on the fix lattice: uploads:0 for all four flags (control uploads:1, byte-exact). Credential: savedSecretReceived:false, otherOriginRequests:[]

Environment notes from the VM run:

  • The Ubuntu image's default umask 0002 caused UNSAFE_DIRECTORY_MODE failures in agent-core, pi-plugin and omp tests (the hardened file layer rejects group-writable dirs). The same code passes on the same VM under umask 022.
  • The first source tarball lacked integrations/coding-agents/fixtures, which core.test.cjs needs. A rerun with the fixtures gave the 473/473 above.

(Historical, fixed in the resync below.) GitHub CI was red at 4ac7dc3 because the base moved. feat/attachments-ts-core moved to 031178f at 06:14Z, after the last green run (5dd669e, 05:08Z). CI builds the merge ref, and the new core API breaks this lane's existing code:

  • AttachmentRuntimeState has ready and no longer has queued. The existing status().state !== "queued" checks in agent-core attachments.ts and cursor-sdk attachments.ts fail to compile.
  • ManagerOptions.transport is now AttachmentTransport | AttachmentTransportV1. V1 has no upload and takes a key argument. The original delegate.bootstrap/upload calls would fail the same way.

The resync below reconciles the lane to ts-core f0a56b3.

Resync to ts-core f0a56b3 (head bdce56b)

Merged the updated feat/attachments-ts-core (f0a56b3, merge commit ca63722, clean). Never rebased.

  1. db01b09, the minimum the new core forces: the ready state is "ready" (was "queued") in agent-core and cursor-sdk, plus the transport union type. There is no behaviour change. This is the VM control ("ctl").
  2. dbfcd3b, adopting the SDK design APIs:
    • Preflight before any base64 read. captureAgentImages and captureCursorImages call manager.preflight (deny-wins policy, sampling, correlation, budget) first. Only an admitted part is read, strictly validated (exact decoded length, computed without decoding), decoded and handed to ticket.attach. The get data() getter through manager.attach is gone.
    • Budget denials. A too_large or queue_full denial comes only after the policy gate passes, so the adapter reads the part's length and re-preflights once at its exact size. A server max_upload_bytes below 256 KiB therefore still captures smaller images.
    • Refused parts. A malformed or throwing part releases its ticket and reports source_unavailable. An over-budget part now reports too_large (it was source_unavailable).
    • Versioned runtime transport. agentAttachmentRuntime wraps the full AttachmentTransportV1 surface. All 11 calls re-check collection policy and route revalidation; before, the four legacy calls did. The transport is built with createAttachmentHttpTransportV1, or comes from a V1 caller transport or the V1 member a legacy-shaped one carries. The unapproved-endpoint stub is V1-shaped, so it no longer triggers FI_ATTACHMENTS_LEGACY_TRANSPORT.
    • Legacy caller transports. A caller-supplied four-method transport stays four-method on purpose: fi-core still warns once that it is legacy. There is no silent upgrade.
    • Test doubles. In-process doubles are now AttachmentTransportV1. The Pi and OMP HTTPS doubles return F01 status bodies with reason. Suites assert that the V1 path emits no FI_ATTACHMENTS_* warning.
    • New rows: preflight-before-read with an exact-size retry; ticket release on malformed parts; guard coverage of all 11 V1 calls after revocation; the legacy warning.
  3. 4506da8 and bdce56b: test-only. The guard rows use a collectable config. After discard(), ts-core f0a56b3 reports incomplete rather than policy_denied (see the core note below), so the test now asserts that the runtime is closed and that a later image is not uploaded.

Public signatures are unchanged.

Core note (ts-core lane, not changed here): AttachmentManager.shutdown() sets closedReason = "incomplete" even after invalidate("policy_denied"). A discard() (invalidate, then provider shutdown) therefore reports incomplete. The control build fails the original policy_denied assertion the same way (472/473).

Qualification (private GCP VM fagi-omega-staging, loopback only, deleted and verified gone)

Every tree was rebuilt from public refs plus patches, and the tree hashes matched the pushed commits.

Run Result
Head on Node 24.11.1: agent-core full suite (final tree) 477/477
Head on Node 22.19.0: agent-core full suite (final tree) 477/477
Head on Node 24.11.1 and 22.19.0: claude-code, pi-plugin, oh-my-pi-plugin, cursor-sdk jest 59/59, 47/47, 39/39, 229/229 on each Node
Head: real Pi host over HTTPS, Pi 1.5.0 (floor), Node 24 and Node 22.19.0 8/8 scenarios on each
Head: real Pi host, Pi 1.5.2 (latest) 8/8 scenarios
Head: OMP plugin API over HTTPS, Node 24 and Node 22.19.0 8/8 on each
FI_ATTACHMENTS_* warnings on the head 0, except the one intended warning in the legacy-transport row
Lockfile unchanged
Control (lane + compile fix on core f0a56b3, OLD tests): claude-code, pi-plugin, omp, cursor jest, OMP wire 59/59, 47/47, 39/39, 228/228, 8/8. In-process capture still works, but FI_ATTACHMENTS_LEGACY_TRANSPORT fires because the old wrapper dropped the V1 member. The OMP wire also shows FI_ATTACHMENTS_WIRE_REJECTED.
Control: agent-core 472/473 (the core discard state change above)
Control: real Pi host with the old harness 0/8 in each of 3 runs (enabled uploaded 0). With the head's harness (F01 reason bodies plus a stderr check), the same control build passes 8/8. The mechanism was not traced: uploads are counted at initialize, which runs before the changed responses.
Head tests on the control build (attribution) agent-core 28/34, claude-code 9/12, cursor 15/16 (only the new preflight row fails). The OMP wire fails on the new no-legacy-warning assertion.
Mutations on the head 5/5 detected; details below

Mutation detail:

Mutation agent-core rows failing cursor rows failing
Read before preflight 17 9
No release() 2 1
No exact-size retry 1 1
Unguarded putContent the guard row —
Four-method unconfigured stub the origin-binding row —

Mutations ran on the round-2 tree, where the discard row was still failing for an unrelated reason. That row is excluded from the counts above, and the round-3 fix only touches that test. After the mutations were restored, the head passed again.

GitHub CI at bdce56b is green: Coding-agent attachments passes on Node 22.19.0 and Node 24, as does n8n (run 43027104507). On the first attempt, the Node 22 job failed one timing row in test/forks/claude/tracer.test.cjs (a shutdown-deadline race). This lane does not touch that file. The rerun of the failed job passed.

Not run here: real @cursor/sdk 1.0.37/1.3.1 contract rows (captureCursorImages signature unchanged), a signed-in Claude Code host, a real OMP/Bun host, product playback.

🤖 Generated with Claude Code

nik13 and others added 8 commits November 10, 2026 20:00
… agents

Shares the provider-owned fi-core AttachmentManager through createTurnTracer,
adds a bounded typed image-block helper, attachment status in inspectStatus,
and Pi/oh-my-pi bindings for user prompt and tool-result images.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- agent-core: one typed inline image boundary for Pi/OMP and Anthropic base64
  source blocks; per-call budget counts only admitted bytes; status keyed by
  real adapter ids (claude, kiro-cli, ...); drop unused policy helper.
- claude-code: prompt images on the final root and this prompt's tool-result
  images on their tool spans; bounded bootstrap wait only when opted in.
- cursor-sdk: inline { data, mimeType } send images on the run span when
  provider.attachments is passed and inputs are not hidden; URL images are
  never fetched. Type contract pins the inline SDKImage variant.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…attachments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ads, find tool spans by kind

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… follow-up message

Pi forwards tool-result images as a separate user message, so the loopback
model must stop calling the tool once any tool message exists. Also raise the
JSON-mode stdout buffer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GitHub runners export XDG_CONFIG_HOME, so the hook resolved state outside the
fixture home and 25 existing hook tests failed there. Reproduced on a VM with
a runner-style XDG_CONFIG_HOME (34/59) and fixed (59/59).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…redential to approved origin

cursor-sdk: the instrumentation's resolved trace config now reaches
captureCursorImages. Any of hideInputs, hideInputMessages, hideInputText,
hideInputImages or piiRedaction (option or env) attaches with
captureContent:false, so the provider-owned manager cannot upload prompt
images that the instrumentation's own policy hides.

agent-core: the attachment endpoint (options or FI_ATTACHMENTS_ENDPOINT) is
used only when its origin equals the approved OTLP destination's origin.
Otherwise no credential headers are returned and the manager gets a guarded
transport that reports endpoint_unconfigured, so fi-core never builds its own
transport from FI_ATTACHMENTS_ENDPOINT. agentAttachmentStatus applies the same
rule.

Regression tests: four instrumentation flag cases and four env cases for
Cursor; status/runtime origin unit tests and a real TLS saved-profile test
(unapproved origin receives nothing, approved origin is the positive control).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13 and others added 5 commits November 11, 2026 04:16
…nsport union)

Minimal adaptation forced by the merged core: the runtime ready state is
now "ready" (was "queued"), and ManagerOptions.transport is the union of
the legacy four-method shape and AttachmentTransportV1. No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d runtime transport

Adopt the ts-core f0a56b3 attachment API (SDK design sections 1 and 9):

- agent-core captureAgentImages and cursor-sdk captureCursorImages now call
  manager.preflight (deny-wins policy, sampling, correlation, budget) BEFORE
  any base64 read. Only an admitted part is read, strictly validated,
  decoded and handed to ticket.attach. A budget denial (too_large or
  queue_full, which come only after the policy gate) re-preflights once at
  the part's exact decoded length, so a server cap below 256 KiB still
  captures smaller images. A malformed or throwing part releases its ticket
  and reports source_unavailable; an oversized one reports too_large (was
  source_unavailable). The legacy manager.attach getter path is gone.
- agentAttachmentRuntime wraps the full AttachmentTransportV1 surface (all
  11 calls re-check policy and route revalidation), built with
  createAttachmentHttpTransportV1, or the V1 member a caller transport
  carries. The unapproved-endpoint stub is V1-shaped. A caller-supplied
  four-method transport stays four-method, so fi-core still flags it once
  with FI_ATTACHMENTS_LEGACY_TRANSPORT instead of a silent upgrade.
- Tests: in-process doubles are V1 (fi-core test/attachments-v1.cjs or an
  inline V1 double); the Pi and OMP HTTPS doubles return F01 status bodies
  with `reason`; suites assert no FI_ATTACHMENTS_* warning on the V1 path.
  New rows: preflight-before-read with exact-size retry under a small
  server cap, ticket release on malformed parts, guard coverage of all 11
  V1 calls after revocation, and the legacy-transport warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tate after core shutdown

The runtime-guard and legacy-transport rows used a config without a
manifest path, so collectionEnabled() was false and the runtime stayed
disabled. Give them a collectable config (no fence: ENOENT) and assert the
allowed path reaches the V1 delegate before revocation.

discard() invalidates with policy_denied, then shuts the provider down;
ts-core f0a56b3's shutdown() overwrites the closed reason with
incomplete. Assert the runtime is closed either way and that a later
image is not uploaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant