11 KiB
Durable Image Attachments
English | 中文
The attachment seam separates binary image ownership from the session log. A producer gives validated encoded bytes to ctx.attachments; the service publishes an immutable content-addressed reference only after the object is durable. Session events and model-visible ImageBlocks contain that reference and metadata, never a browser object URL, host temporary path, provider URL, or base64 payload.
Unsent browser drafts may stay in memory and native clients may stage them in operating-system temporary storage. Once the host accepts a user message, its images move below <DSH_HOME>/attachments/v1 before the user event is appended. Structured model image output follows the same persist-before-event rule.
Source: packages/attachment/attachment/src/types.ts
Identity and verified metadata
AttachmentId is a branded opaque string. The local backend currently emits sha256:<digest>, but consumers must neither parse that representation nor derive a filesystem path from it.
/** Raster image formats accepted by the version-one attachment path. */
type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
/** Durable, serializable metadata for one immutable image object. */
interface ImageAttachmentRef {
/** Opaque storage identifier; never a filesystem path or bearer URL. */
attachmentId: AttachmentId
/** Media type verified from the stored bytes. */
mediaType: ImageMediaType
/** Exact encoded byte length. */
bytes: number
/** Intrinsic encoded width in pixels. */
width: number
/** Intrinsic encoded height in pixels. */
height: number
/** Optional display name stripped of local path information. */
name?: string
/** Perceived source width before master-version downscaling; present only when it differs from {@link width}. */
sourceWidth?: number
/** Perceived source height before master-version downscaling; present only when it differs from {@link height}. */
sourceHeight?: number
}
/** Deployment-resolved limits used by upload admission and request buffering. */
interface ImageAttachmentLimits {
maxImageBytes: number
maxImagesPerMessage: number
maxMessageImageBytes: number
maxImagePixels: number
/** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
maxImageDimension: number
mediaTypes: readonly ImageMediaType[]
}
The reference records intrinsic dimensions and encoded length so clients can lay out history without decoding first, while every authoritative read still re-checks digest, media signature, dimensions, and metadata against the object.
Commit and verified-read payloads
/** Base64-encoded image upload accompanying one wire request. */
interface EncodedImageAttachment {
/** Declared media type, verified against the decoded bytes during admission. */
mediaType: ImageMediaType
/** Canonical base64 encoding of the image bytes. */
data: string
/** Optional display name; it is never interpreted as a path. */
name?: string
}
/** Request to validate and durably commit one image. */
interface SaveImageAttachment {
data: Uint8Array
/** Caller-declared media type, checked against fully decoded bytes. */
mediaType: ImageMediaType
/** Optional browser/provider display name; it is never interpreted as a path. */
name?: string
}
/** Stored image bytes returned after reference and digest verification. */
interface StoredImageAttachment {
ref: ImageAttachmentRef
data: Uint8Array
}
/** Pixel rectangle in the oriented 2048px master-version coordinate system. */
interface MasterImageCrop {
x: number
y: number
width: number
height: number
}
/** Deterministic request-image policy selected by one exact model route. */
interface ImageRequestPolicy {
/** Maximum width multiplied by height after aspect-preserving projection. */
maxPixels: number
/** Encoded-byte cap before base64 expansion or Files API upload. */
maxBytes: number
/** Optional master-coordinate crop applied before pixel-budget scaling. */
crop?: MasterImageCrop
}
/** Crop coordinates measured by a model on the request preview it received. */
interface PreviewImageCrop {
previewWidth: number
previewHeight: number
x: number
y: number
width: number
height: number
}
/** Cached request version derived from one provider-independent master attachment. */
interface RequestImageAttachment {
/** Cache and upload-index key over the master id, policy, crop, and fixed encoder parameters. */
variantId: ImageVariantId
/** Durable master reference from which this request version was derived. */
master: ImageAttachmentRef
/** Encoded request bytes. */
data: Uint8Array
mediaType: ImageMediaType
bytes: number
width: number
height: number
/** Provider-compatible sample depth proven after request encoding. */
depth: 'uchar'
/** Provider-compatible color space proven after request encoding. */
space: 'srgb'
/** Whether the encoded request version retains an alpha channel. */
hasAlpha: boolean
/** Applied master-coordinate crop, when present. */
crop?: MasterImageCrop
}
saveImage() prepares a provider-independent 2048px, 4MiB master and atomically commits it before returning its reference. saveImages() prepares every validated master once before publishing the batch, so validation rejection leaves no partial objects and publication does not repeat decoding or quality selection. admitEncodedImages() is the wire entry for base64 uploads and delegates count, aggregate-byte, and ordered batch admission to saveImages(). readImage() verifies a master from an authorized session path. readImageRequest() derives and caches one request version under an exact route pixel and byte budget; new entries are fully decoded before publication, while cache hits use a bounded metadata probe. readImageRequests() lets an implementation apply its configured transform concurrency to an ordered batch. The local implementation lazily encodes preferred candidates, singleflights equal request identities, lets each waiter cancel independently, stops shared work when no waiter remains, and defaults to two simultaneous transformations. cropImage() maps model preview coordinates back to the master and returns another durable attachment. The service is retention-neutral: resumed and forked sessions may share objects, so reference-aware garbage collection is deferred rather than tied to one session's deletion.
Cordis API
Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.attachments — AttachmentStore (abstract seam)
Immutable binary attachment service. Implementations validate bytes before publishing a reference.
/**
* Validate one image without persisting it.
* Batch callers validate every member before saving any member.
* @param input - encoded bytes, declared media type, and optional display name.
* @returns completion after the encoded raster has been fully decoded.
*/
abstract validateImage(input: SaveImageAttachment): Promise<void>
/**
* Validate and durably commit one ordered image batch.
* @param inputs - encoded images in owning-message order.
* @returns durable master references in the same order after every member succeeds.
*/
async saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>
/**
* Validate and durably commit one image before its owning session event is appended.
* Implementations may store a prepared master version of the submitted raster;
* the returned reference always describes the stored bytes, while `source`
* preserves the submitted raster's intrinsic facts for callers that report
* or map coordinates against the original.
* @param input - encoded bytes, declared media type, and optional display name.
* @returns the durable content-addressed reference beside the submitted source facts.
*/
abstract saveImage(input: SaveImageAttachment): Promise<SavedImageAttachment>
/**
* Read one image and verify that bytes still match the recorded reference.
* @param ref - durable reference from the session log.
* @param signal - optional cancellation for backend read and verification work.
* @returns the verified bytes and master reference.
* @throws the signal reason when aborted, or a storage error when verification fails.
*/
abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>
/**
* Generate or read one deterministic model-request version from the stored master image.
* @param ref - durable provider-independent master reference.
* @param policy - exact route pixel and encoded-byte budget.
* @param signal - optional cancellation.
* @returns request bytes and the cache/upload identity covering every transform input.
*/
readImageRequest( ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?: AbortSignal, ): Promise<RequestImageAttachment>
/**
* Generate or read an ordered batch of deterministic model-request versions.
* Implementations may use their own bounded transform concurrency while preserving input order.
* @param refs - durable provider-independent master references in request order.
* @param policy - exact route pixel and encoded-byte budget shared by the batch.
* @param signal - optional cancellation.
* @returns request versions in the same order as `refs`.
*/
async readImageRequests( refs: readonly ImageAttachmentRef[], policy: ImageRequestPolicy, signal?: AbortSignal, ): Promise<readonly RequestImageAttachment[]>
/**
* Crop the stored master by coordinates measured on a model request preview and persist the result.
* @param ref - session-authorized master attachment.
* @param crop - preview dimensions and preview-coordinate rectangle.
* @param signal - optional cancellation.
* @returns a new durable attachment reference suitable for a logged tool result.
*/
cropImage( ref: ImageAttachmentRef, crop: PreviewImageCrop, signal?: AbortSignal, ): Promise<SavedImageAttachment>