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

Presenters 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. A Presenter 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 the current image 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 a Presenter 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 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.
  • Presenter adapter tests show image attachments are forwarded as attachments, not _meta.pixir.presenter_context.
  • An end-to-end Presenter -> Pixir -> Provider 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.