21. Session Resources and Image Attachments

Copy Markdown View Source

Date: 2026-06-10 Status: Accepted Implementation status: Initial image-attachment slice implemented; ACP resource_link local-file ingestion is supported for Session Resource descriptors. Subagent inheritance and non-image Provider projection remain out of scope

Context

T3 Code can present image attachments, but Pixir must keep the Harness boundary clear: Presenter state and Pixir Session truth are not the same thing. Long-running coding agents also cannot treat attached images as ambient prompt forever without losing cache discipline and making compaction misleading.

Decision

Pixir treats user-provided attachments and ACP resource_link blocks as durable Session Resources, not as Presenter-local blobs or ambient prompt context. The first concrete Provider-projected resource kind is an Image Attachment: Pixir preserves the original local payload as canonical, references it from the Log by resource_id, identifies exact bytes with content_sha256, projects the original image to the Provider on the Turn where it is attached, then replays only a descriptor or digest on later Turns unless a Tool-mediated Resource View explicitly rehydrates it.

ACP resource_link is a baseline prompt block. Pixir accepts it as a resource descriptor. When the uri is a readable local file:// target, Pixir copies the bytes into its Session Resource store even if the source file is outside the workspace: the Presenter/user supplied the link explicitly, while read/write/edit remain workspace-confined Tool operations. Remote links are recorded as descriptor-only references; Pixir does not fetch them automatically.

The key boundary is the Leakage Boundary: local persistence inside Pixir is not leakage, because Pixir is local-first; projecting a resource to the Provider is where upload policy, cache behavior, and user intent matter. T3 Code may present and upload images, but Pixir must ingest the resource and own the canonical Log reference. OpenAI input_image is a Provider projection of a Session Resource, not the resource itself.

Non-goals

  • Subagent access to Session Resources is deliberately out of scope for the first slice; it needs its own permission and inheritance decision.
  • The MVP implementation supports T3 Code's current image-only attachment contract and ACP resource_link descriptors. Documents, PDFs, audio, and other binary resources may be stored or described as Session Resources, but Provider projection beyond images remains a future decision.

Considered Options

  • Store only Presenter attachment ids: rejected because Pixir could not resume, fork, compact, or run as a CLI Harness without T3's projection database.
  • Always replay original images: rejected because long-running sessions would become expensive, cache-hostile, and misleading after compaction.
  • Sanitize or mutate local originals by default: rejected because Pixir is a power-user, local-first engineering Harness. The exact local artifact is the canonical evidence; sanitized/downsampled/provider-optimized variants may be explicit future projections.
  • Use an image-specific rehydration tool: rejected for the architecture boundary. Pixir uses a resource-general Resource View concept, with image rehydration as the first supported kind.

Consequences

  • Compaction may summarize Image Attachments, but the summary must state its limitations: a visual digest is not the original image.
  • Missing resource payloads must fail or degrade honestly; Pixir must not pretend the Provider saw an image when only a descriptor or digest was available.
  • Remote resource_link descriptors must not imply that Pixir fetched or inspected the linked bytes.
  • Forks may share content_sha256 while keeping distinct resource_id references and distinct visual observations in each fork's History.

Verification Direction

The first implementation Goal should prove:

  • CONTEXT.md and this ADR define the boundary terms.
  • Pixir can ingest an Image Attachment from ACP/T3 without storing raw base64 in the NDJSON Log.
  • The Log records a resource descriptor with resource_id and content_sha256.
  • Provider input includes input_image on the Turn where the image is attached.
  • Later replay uses descriptor/digest by default.
  • resource_view rehydrates the original image explicitly and records that action.
  • T3 adapter tests show image attachments are forwarded as attachments, not _meta.pixir.presenter_context.
  • A real T3 -> Pixir -> OpenAI smoke can attach an image, receive a vision-grounded answer, and leave provider_usage evidence.

References

  • CONTEXT.md: Session Resource, Image Attachment, Resource View, Leakage Boundary, Presenter, Presenter Projection, Compaction, Prompt Contract.
  • ADR 0003: stateless Turns and local Log as source of truth.
  • ADR 0004: unified Event envelope and canonical vs ephemeral Events.
  • ADR 0017: minimal Harness core and Presenter boundary.
  • ADR 0018: durable History compaction and replay repair.
  • ADR 0019: provider usage and prompt-cache observability.
  • ADR 0020: versioned Prompt Contract and cache-key families.