@hydraharness/harness-attachment 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @hydraharness/harness-attachment
+
+The durable attachment seam. `ctx.attachments` validates and durably commits immutable image bytes, then returns a serializable `ImageAttachmentRef`; consumers never persist browser paths, object URLs, provider URLs, or base64 in session events.
+
+Unsent composer images remain browser-owned temporary drafts. `validateImage` runs the same admission policy without persisting. `saveImages` owns batch count and aggregate-byte limits, validates every member before writing any member, then commits in order and returns references only after the complete batch succeeds. A later storage failure returns no partial references, although an earlier immutable content-addressed object may remain unreachable until reference-aware garbage collection exists. `AttachmentError.code` uses the closed `AttachmentErrorCode` string union. Its `ImageAdmissionErrorCode` subset marks caller-correctable image-input failures; `isImageAdmissionError` recognizes that subset at runtime so each protocol adapter can map its own error vocabulary. `saveImage` commits one accepted image before any model-visible session event is published, and `readImage` verifies the content-addressed object against its logged metadata. Callers may cancel `readImage`; implementations observe cancellation around backend and verification work and preserve it instead of translating it into a storage failure.
+
+`admitEncodedImages(attachments, images)` is the shared wire entry used by every RPC endpoint that accepts browser uploads (the session prompt endpoint and the command executor): it enforces canonical base64 on every member, then delegates batch admission — limits, validation, ordered commit — to `saveImages`. The base64 upload form is `EncodedImageAttachment`, exported from `@hydraharness/harness-attachment/types` so wire contracts can reference it.
+
+`toolImageReferences(meta)` validates recognized `tool-images` metadata and returns its opaque image references. Unrelated metadata returns an empty list; malformed recognized metadata throws. The [tool-presentation format](../../../docs/subsystems/attachment.md#tool-presentation-images) supports UI images that do not enter model history.
+
+`toolVideoReferences(meta)` applies the same policy to `tool-videos`. A `VideoAttachmentRef` extends stored file metadata with `video/mp4` or `video/webm`; producers save final bytes through `saveFile` or `saveFileStream` before publishing the result and own video-format admission. Session reads verify the stored file and authorize its logged reference; ZIP export includes the exact file bytes. `toolMediaLabels(meta)` reads string-valued provider/model labels for display.
+
+## Model Experience
+
+Indirectly, through the role-neutral core `ImageBlock` and provider adapters that resolve its durable reference.
+
+#### KV Cache effect
+
+Adding an image changes the provider request and therefore invalidates the affected request suffix.
+
+## Known Limitations and Deferred Work
+
+- Version one accepts PNG, JPEG, WebP, and GIF only.
+- Retention and garbage collection are deferred because resumed and forked sessions may share immutable objects.
+- Generic files, audio, video, and persistent unsent drafts require separate lifecycle and provider contracts.

package/lib/index.js

@@ -0,0 +1,217 @@
+import { Service } from "@hydraharness/cordis";
+import { Buffer } from "node:buffer";
+//#region lib/types/error.js
+/** Runtime membership for structurally compatible errors crossing package boundaries. */
+const IMAGE_ADMISSION_ERROR_CODE_SET = new Set([
+	"TOO_MANY_IMAGES",
+	"IMAGES_TOO_LARGE",
+	"UNSUPPORTED_IMAGE_TYPE",
+	"INVALID_IMAGE_BASE64",
+	"INVALID_IMAGE",
+	"IMAGE_TYPE_MISMATCH",
+	"IMAGE_TOO_LARGE",
+	"IMAGE_TOO_MANY_PIXELS",
+	"IMAGE_DIMENSION_TOO_LARGE"
+]);
+/**
+* Stable failures suitable for host RPC error mapping.
+*
+* Deliberately re-implements the `HarnessError` shape instead of extending it:
+* the base lives in `@hydraharness/harness-llm`, which itself depends on this
+* package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+* would create a dependency cycle. Consumers route on `code`, never on the
+* prototype chain, so the shapes stay interchangeable at the wire boundary.
+*/
+var AttachmentError = class extends Error {
+	/** Stable machine-routing failure code. */
+	code;
+	/**
+	* @param message - human-readable failure description without raw bytes or host paths.
+	* @param code - stable machine-routing code.
+	* @param options - optional chained cause.
+	*/
+	constructor(message, code, options) {
+		super(message, options);
+		this.name = "AttachmentError";
+		this.code = code;
+	}
+};
+/**
+* Distinguish caller-correctable image admission failures from storage faults.
+* @param error - failure raised while validating or persisting an image batch.
+* @returns whether the caller can correct the proposed image content or batch.
+*/
+function isImageAdmissionError(error) {
+	return error instanceof Error && "code" in error && typeof error.code === "string" && IMAGE_ADMISSION_ERROR_CODE_SET.has(error.code);
+}
+//#endregion
+//#region lib/types/brand.js
+/** Attachment identifier brand. @module @hydraharness/harness-attachment/brand */
+/**
+* Brand a validated storage identifier.
+* @param value - backend-produced opaque identifier.
+* @returns the branded identifier.
+*/
+function AttachmentId(value) {
+	return value;
+}
+//#endregion
+//#region lib/types/admission.js
+/** Wire-form admission of base64-encoded image uploads. @module @hydraharness/harness-attachment/admission */
+/** Decode one upload payload while rejecting non-canonical base64 forms. */
+function decodeBase64(data) {
+	const decoded = Buffer.from(data, "base64");
+	if (data.length === 0 || decoded.toString("base64") !== data) throw new AttachmentError("Image upload is not canonical base64.", "INVALID_IMAGE_BASE64");
+	return new Uint8Array(decoded);
+}
+/**
+* Admit one generic file upload, including zero-byte files.
+* @param attachments - attachment store that owns durable file storage.
+* @param file - canonical base64 upload and optional display name.
+* @returns the durable file reference.
+*/
+async function admitEncodedFile(attachments, file) {
+	const decoded = Buffer.from(file.data, "base64");
+	if (file.data.length > 0 && decoded.toString("base64") !== file.data) throw new AttachmentError("File upload is not canonical base64.", "INVALID_FILE_BASE64");
+	return attachments.saveFile({
+		data: new Uint8Array(decoded),
+		...file.name === void 0 ? {} : { name: file.name }
+	});
+}
+/** Store input for one decoded upload. */
+function saveInput(image) {
+	return {
+		data: decodeBase64(image.data),
+		mediaType: image.mediaType,
+		...image.name === void 0 ? {} : { name: image.name }
+	};
+}
+/**
+* Admit one wire image batch: enforce canonical base64 on every member, then
+* delegate batch admission — count and aggregate-byte limits, media-type and
+* per-image validation, ordered commit — to {@link AttachmentStore.saveImages}.
+* The shared entry for every RPC endpoint accepting browser uploads.
+* @param attachments - the deployment attachment store owning batch policy.
+* @param images - base64-encoded uploads in caller order.
+* @returns durable references in the same order as `images`.
+* @throws AttachmentError on a non-canonical payload or a refused batch.
+*/
+async function admitEncodedImages(attachments, images) {
+	return attachments.saveImages(images.map(saveInput));
+}
+//#endregion
+//#region lib/types/presentation.js
+/**
+* Read image references from recognized tool presentation metadata.
+* @param meta - untrusted durable presentation metadata.
+* @returns validated image references, or an empty list for other metadata.
+* @throws TypeError when recognized metadata contains an invalid reference.
+*/
+function toolImageReferences(meta) {
+	if (typeof meta !== "object" || meta === null || !("kind" in meta) || meta.kind !== "tool-images") return [];
+	const images = meta.images;
+	if (!Array.isArray(images) || images.some((image) => {
+		if (typeof image !== "object" || image === null) return true;
+		const ref = image;
+		return typeof ref.attachmentId !== "string" || ref.attachmentId.length === 0 || ![
+			"image/png",
+			"image/jpeg",
+			"image/webp",
+			"image/gif"
+		].includes(ref.mediaType ?? "") || ![
+			ref.bytes,
+			ref.width,
+			ref.height
+		].every((value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0) || ref.name !== void 0 && typeof ref.name !== "string";
+	})) throw new TypeError("Invalid tool-image presentation metadata.");
+	return images;
+}
+/**
+* Read durable video references from tool presentation metadata.
+* @param meta - untrusted durable presentation metadata.
+* @returns validated video references, or an empty list for other metadata.
+* @throws TypeError when recognized metadata contains an invalid reference.
+*/
+function toolVideoReferences(meta) {
+	if (typeof meta !== "object" || meta === null || !("kind" in meta) || meta.kind !== "tool-videos") return [];
+	const videos = meta.videos;
+	if (!Array.isArray(videos) || videos.some((video) => {
+		if (typeof video !== "object" || video === null) return true;
+		const ref = video;
+		return typeof ref.attachmentId !== "string" || ref.attachmentId.length === 0 || !["video/mp4", "video/webm"].includes(ref.mediaType ?? "") || typeof ref.bytes !== "number" || !Number.isSafeInteger(ref.bytes) || ref.bytes <= 0 || typeof ref.name !== "string" || ref.name.length === 0 || /[\\/\u0000-\u001f\u007f]/u.test(ref.name);
+	})) throw new TypeError("Invalid tool-video presentation metadata.");
+	return videos;
+}
+/**
+* Read the actual generating route's display labels from durable metadata.
+* @param meta - tool presentation metadata.
+* @returns only string-valued provider and model labels.
+*/
+function toolMediaLabels(meta) {
+	if (typeof meta !== "object" || meta === null) return {};
+	return {
+		..."model" in meta && typeof meta.model === "string" ? { model: meta.model } : {},
+		..."provider" in meta && typeof meta.provider === "string" ? { provider: meta.provider } : {}
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/** Durable attachment storage seam (`ctx.attachments`). @module @hydraharness/harness-attachment */
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+var AttachmentStore = class extends Service {
+	constructor(ctx) {
+		super(ctx, "attachments");
+	}
+	/**
+	* Validate one ordered image batch before committing any member.
+	* Validation failures start no writes; storage failures return no partial
+	* references, although already published content-addressed objects may stay
+	* unreachable until a future retention policy collects them.
+	* @param inputs - encoded images in their owning message order.
+	* @returns durable references in the exact input order.
+	*/
+	async saveImages(inputs) {
+		const { maxImagesPerMessage, maxMessageImageBytes, mediaTypes } = this.imageLimits;
+		if (inputs.length > maxImagesPerMessage) throw new AttachmentError("Image batch exceeds the configured image-count limit.", "TOO_MANY_IMAGES");
+		if (inputs.reduce((sum, input) => sum + input.data.byteLength, 0) > maxMessageImageBytes) throw new AttachmentError("Image batch exceeds the configured aggregate image-byte limit.", "IMAGES_TOO_LARGE");
+		for (const input of inputs) if (!mediaTypes.includes(input.mediaType)) throw new AttachmentError(`Image type ${input.mediaType} is not accepted by this deployment.`, "UNSUPPORTED_IMAGE_TYPE");
+		for (const input of inputs) await this.validateImage(input);
+		const refs = [];
+		for (const input of inputs) refs.push(await this.saveImage(input));
+		return refs;
+	}
+	/**
+	* Persist one file verbatim and return its durable reference.
+	* @param input - complete file bytes and optional display name.
+	* @returns the content-addressed durable reference.
+	*/
+	saveFile(input) {
+		return Promise.reject(new AttachmentError("The mounted attachment provider cannot store files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Persist streamed file bytes without requiring one complete input buffer.
+	* @param input - ordered byte chunks, cancellation, and optional display name.
+	* @returns the content-addressed durable reference.
+	*/
+	saveFileStream(input) {
+		return Promise.reject(new AttachmentError("The mounted attachment provider cannot store files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Read one durable file as verified byte chunks.
+	* @param ref - durable file reference to verify.
+	* @param signal - optional cancellation signal.
+	* @returns an async sequence of exact file bytes.
+	*/
+	async *readFileStream(ref, signal) {
+		signal?.throwIfAborted();
+		await Promise.reject(new AttachmentError("The mounted attachment provider cannot read files.", "ATTACHMENT_FILES_UNSUPPORTED"));
+	}
+	/**
+	* Resolve a durable file to a host path when this provider is host-backed.
+	* @param ref - durable file reference.
+	* @returns an absolute host path, or undefined when unavailable.
+	*/
+	fileHostPath(ref) {}
+};
+//#endregion
+export { AttachmentError, AttachmentId, AttachmentStore, AttachmentStore as default, admitEncodedFile, admitEncodedImages, isImageAdmissionError, toolImageReferences, toolMediaLabels, toolVideoReferences };

package/lib/invariant.js

@@ -0,0 +1,17 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion for `@hydraharness/harness-attachment`. @module @hydraharness/harness-attachment/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-attachment";
+/** Cordis companion plugin name. */
+const name = "attachment-invariant";
+/** Service required before package ownership can be reserved. */
+const inject = ["invariants"];
+/** No runtime invariant: this stateless seam owns types while implementations enforce immutable-store checks. */
+const install = () => {};
+/**
+* Register the package invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the registration disposer.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/admission.d.ts

@@ -0,0 +1,22 @@
+/** Wire-form admission of base64-encoded image uploads. @module @hydraharness/harness-attachment/admission */
+import type { AttachmentStore } from './index.ts';
+import type { EncodedFileAttachment, EncodedImageAttachment, FileAttachmentRef, ImageAttachmentRef } from './types.ts';
+/**
+ * Admit one generic file upload, including zero-byte files.
+ * @param attachments - attachment store that owns durable file storage.
+ * @param file - canonical base64 upload and optional display name.
+ * @returns the durable file reference.
+ */
+export declare function admitEncodedFile(attachments: AttachmentStore, file: EncodedFileAttachment): Promise<FileAttachmentRef>;
+/**
+ * Admit one wire image batch: enforce canonical base64 on every member, then
+ * delegate batch admission — count and aggregate-byte limits, media-type and
+ * per-image validation, ordered commit — to {@link AttachmentStore.saveImages}.
+ * The shared entry for every RPC endpoint accepting browser uploads.
+ * @param attachments - the deployment attachment store owning batch policy.
+ * @param images - base64-encoded uploads in caller order.
+ * @returns durable references in the same order as `images`.
+ * @throws AttachmentError on a non-canonical payload or a refused batch.
+ */
+export declare function admitEncodedImages(attachments: AttachmentStore, images: readonly EncodedImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+//# sourceMappingURL=admission.d.ts.map

package/lib/types/admission.js

@@ -0,0 +1,46 @@
+/** Wire-form admission of base64-encoded image uploads. @module @hydraharness/harness-attachment/admission */
+import { Buffer } from 'node:buffer';
+import { AttachmentError } from "./error.js";
+/** Decode one upload payload while rejecting non-canonical base64 forms. */
+function decodeBase64(data) {
+    const decoded = Buffer.from(data, 'base64');
+    if (data.length === 0 || decoded.toString('base64') !== data) {
+        throw new AttachmentError('Image upload is not canonical base64.', 'INVALID_IMAGE_BASE64');
+    }
+    return new Uint8Array(decoded);
+}
+/**
+ * Admit one generic file upload, including zero-byte files.
+ * @param attachments - attachment store that owns durable file storage.
+ * @param file - canonical base64 upload and optional display name.
+ * @returns the durable file reference.
+ */
+export async function admitEncodedFile(attachments, file) {
+    const decoded = Buffer.from(file.data, 'base64');
+    if ((file.data.length > 0 && decoded.toString('base64') !== file.data)) {
+        throw new AttachmentError('File upload is not canonical base64.', 'INVALID_FILE_BASE64');
+    }
+    return attachments.saveFile({ data: new Uint8Array(decoded), ...(file.name === undefined ? {} : { name: file.name }) });
+}
+/** Store input for one decoded upload. */
+function saveInput(image) {
+    return {
+        data: decodeBase64(image.data),
+        mediaType: image.mediaType,
+        ...image.name === undefined ? {} : { name: image.name },
+    };
+}
+/**
+ * Admit one wire image batch: enforce canonical base64 on every member, then
+ * delegate batch admission — count and aggregate-byte limits, media-type and
+ * per-image validation, ordered commit — to {@link AttachmentStore.saveImages}.
+ * The shared entry for every RPC endpoint accepting browser uploads.
+ * @param attachments - the deployment attachment store owning batch policy.
+ * @param images - base64-encoded uploads in caller order.
+ * @returns durable references in the same order as `images`.
+ * @throws AttachmentError on a non-canonical payload or a refused batch.
+ */
+export async function admitEncodedImages(attachments, images) {
+    return attachments.saveImages(images.map(saveInput));
+}
+//# sourceMappingURL=admission.js.map

package/lib/types/brand.d.ts

@@ -0,0 +1,11 @@
+/** Attachment identifier brand. @module @hydraharness/harness-attachment/brand */
+import type { Branded } from '@hydraharness/harness-brand';
+/** Opaque content-addressed identifier for one immutable attachment object. */
+export type AttachmentId = Branded<'AttachmentId'>;
+/**
+ * Brand a validated storage identifier.
+ * @param value - backend-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+export declare function AttachmentId(value: string): AttachmentId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,10 @@
+/** Attachment identifier brand. @module @hydraharness/harness-attachment/brand */
+/**
+ * Brand a validated storage identifier.
+ * @param value - backend-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+export function AttachmentId(value) {
+    return value;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/error.d.ts

@@ -0,0 +1,35 @@
+/** Attachment failure class. @module @hydraharness/harness-attachment/error */
+declare const IMAGE_ADMISSION_ERROR_CODES: readonly ["TOO_MANY_IMAGES", "IMAGES_TOO_LARGE", "UNSUPPORTED_IMAGE_TYPE", "INVALID_IMAGE_BASE64", "INVALID_IMAGE", "IMAGE_TYPE_MISMATCH", "IMAGE_TOO_LARGE", "IMAGE_TOO_MANY_PIXELS", "IMAGE_DIMENSION_TOO_LARGE"];
+/** Caller-correctable attachment failure codes raised while admitting image input. */
+export type ImageAdmissionErrorCode = typeof IMAGE_ADMISSION_ERROR_CODES[number];
+/** Stable attachment failure codes used for protocol error routing. */
+export type AttachmentErrorCode = ImageAdmissionErrorCode | 'INVALID_FILE_BASE64' | 'INVALID_ATTACHMENT_REF' | 'ATTACHMENT_CORRUPT' | 'ATTACHMENT_WRITE_FAILED' | 'ATTACHMENT_NOT_FOUND' | 'ATTACHMENT_READ_FAILED' | 'ATTACHMENT_FILES_UNSUPPORTED';
+/**
+ * Stable failures suitable for host RPC error mapping.
+ *
+ * Deliberately re-implements the `HarnessError` shape instead of extending it:
+ * the base lives in `@hydraharness/harness-llm`, which itself depends on this
+ * package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+ * would create a dependency cycle. Consumers route on `code`, never on the
+ * prototype chain, so the shapes stay interchangeable at the wire boundary.
+ */
+export declare class AttachmentError extends Error {
+    /** Stable machine-routing failure code. */
+    readonly code: AttachmentErrorCode;
+    /**
+     * @param message - human-readable failure description without raw bytes or host paths.
+     * @param code - stable machine-routing code.
+     * @param options - optional chained cause.
+     */
+    constructor(message: string, code: AttachmentErrorCode, options?: ErrorOptions);
+}
+/**
+ * Distinguish caller-correctable image admission failures from storage faults.
+ * @param error - failure raised while validating or persisting an image batch.
+ * @returns whether the caller can correct the proposed image content or batch.
+ */
+export declare function isImageAdmissionError(error: unknown): error is AttachmentError & {
+    readonly code: ImageAdmissionErrorCode;
+};
+export {};
+//# sourceMappingURL=error.d.ts.map

package/lib/types/error.js

@@ -0,0 +1,49 @@
+/** Attachment failure class. @module @hydraharness/harness-attachment/error */
+const IMAGE_ADMISSION_ERROR_CODES = [
+    'TOO_MANY_IMAGES',
+    'IMAGES_TOO_LARGE',
+    'UNSUPPORTED_IMAGE_TYPE',
+    'INVALID_IMAGE_BASE64',
+    'INVALID_IMAGE',
+    'IMAGE_TYPE_MISMATCH',
+    'IMAGE_TOO_LARGE',
+    'IMAGE_TOO_MANY_PIXELS',
+    'IMAGE_DIMENSION_TOO_LARGE',
+];
+/** Runtime membership for structurally compatible errors crossing package boundaries. */
+const IMAGE_ADMISSION_ERROR_CODE_SET = new Set(IMAGE_ADMISSION_ERROR_CODES);
+/**
+ * Stable failures suitable for host RPC error mapping.
+ *
+ * Deliberately re-implements the `HarnessError` shape instead of extending it:
+ * the base lives in `@hydraharness/harness-llm`, which itself depends on this
+ * package (`ImageBlock` references `ImageAttachmentRef`), so sharing the base
+ * would create a dependency cycle. Consumers route on `code`, never on the
+ * prototype chain, so the shapes stay interchangeable at the wire boundary.
+ */
+export class AttachmentError extends Error {
+    /** Stable machine-routing failure code. */
+    code;
+    /**
+     * @param message - human-readable failure description without raw bytes or host paths.
+     * @param code - stable machine-routing code.
+     * @param options - optional chained cause.
+     */
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = 'AttachmentError';
+        this.code = code;
+    }
+}
+/**
+ * Distinguish caller-correctable image admission failures from storage faults.
+ * @param error - failure raised while validating or persisting an image batch.
+ * @returns whether the caller can correct the proposed image content or batch.
+ */
+export function isImageAdmissionError(error) {
+    return error instanceof Error
+        && 'code' in error
+        && typeof error.code === 'string'
+        && IMAGE_ADMISSION_ERROR_CODE_SET.has(error.code);
+}
+//# sourceMappingURL=error.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,77 @@
+/** Durable attachment storage seam (`ctx.attachments`). @module @hydraharness/harness-attachment */
+import { Context, Service } from '@hydraharness/cordis';
+import type { ImageAttachmentLimits, ImageAttachmentRef, FileAttachmentRef, SaveFileAttachment, SaveFileStreamAttachment, SaveImageAttachment, StoredImageAttachment } from './types.ts';
+export { AttachmentId } from './brand.ts';
+export { AttachmentError, isImageAdmissionError } from './error.ts';
+export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts';
+export { admitEncodedFile, admitEncodedImages } from './admission.ts';
+export { toolImageReferences, toolVideoReferences, toolMediaLabels } from './presentation.ts';
+export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, EncodedFileAttachment, ImageAttachmentLimits, ImageAttachmentRef, FileAttachmentRef, ImageMediaType, ToolImagePresentationMeta, VideoAttachmentRef, ToolVideoPresentationMeta, SaveImageAttachment, SaveFileAttachment, SaveFileStreamAttachment, StoredImageAttachment, } from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        attachments: AttachmentStore;
+    }
+}
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+export declare abstract class AttachmentStore extends Service {
+    constructor(ctx: Context);
+    /** Deployment-resolved image policy used by authoritative and fast-path validation. */
+    abstract readonly imageLimits: ImageAttachmentLimits;
+    /**
+     * 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 one ordered image batch before committing any member.
+     * Validation failures start no writes; storage failures return no partial
+     * references, although already published content-addressed objects may stay
+     * unreachable until a future retention policy collects them.
+     * @param inputs - encoded images in their owning message order.
+     * @returns durable references in the exact input order.
+     */
+    saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+    /**
+     * Validate and durably commit one image before its owning session event is appended.
+     * @param input - encoded bytes, declared media type, and optional display name.
+     * @returns a durable content-addressed reference.
+     */
+    abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+    /**
+     * 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 canonical reference.
+     * @throws the signal reason when aborted, or a storage error when verification fails.
+     */
+    abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+    /**
+     * Persist one file verbatim and return its durable reference.
+     * @param input - complete file bytes and optional display name.
+     * @returns the content-addressed durable reference.
+     */
+    saveFile(input: SaveFileAttachment): Promise<FileAttachmentRef>;
+    /**
+     * Persist streamed file bytes without requiring one complete input buffer.
+     * @param input - ordered byte chunks, cancellation, and optional display name.
+     * @returns the content-addressed durable reference.
+     */
+    saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>;
+    /**
+     * Read one durable file as verified byte chunks.
+     * @param ref - durable file reference to verify.
+     * @param signal - optional cancellation signal.
+     * @returns an async sequence of exact file bytes.
+     */
+    readFileStream(ref: FileAttachmentRef, signal?: AbortSignal): AsyncIterable<Uint8Array>;
+    /**
+     * Resolve a durable file to a host path when this provider is host-backed.
+     * @param ref - durable file reference.
+     * @returns an absolute host path, or undefined when unavailable.
+     */
+    fileHostPath(ref: FileAttachmentRef): string | undefined;
+}
+export default AttachmentStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,79 @@
+/** Durable attachment storage seam (`ctx.attachments`). @module @hydraharness/harness-attachment */
+import { Service } from '@hydraharness/cordis';
+import { AttachmentError } from "./error.js";
+export { AttachmentId } from "./brand.js";
+export { AttachmentError, isImageAdmissionError } from "./error.js";
+export { admitEncodedFile, admitEncodedImages } from "./admission.js";
+export { toolImageReferences, toolVideoReferences, toolMediaLabels } from "./presentation.js";
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+export class AttachmentStore extends Service {
+    constructor(ctx) {
+        super(ctx, 'attachments');
+    }
+    /**
+     * Validate one ordered image batch before committing any member.
+     * Validation failures start no writes; storage failures return no partial
+     * references, although already published content-addressed objects may stay
+     * unreachable until a future retention policy collects them.
+     * @param inputs - encoded images in their owning message order.
+     * @returns durable references in the exact input order.
+     */
+    async saveImages(inputs) {
+        const { maxImagesPerMessage, maxMessageImageBytes, mediaTypes } = this.imageLimits;
+        if (inputs.length > maxImagesPerMessage) {
+            throw new AttachmentError('Image batch exceeds the configured image-count limit.', 'TOO_MANY_IMAGES');
+        }
+        const totalBytes = inputs.reduce((sum, input) => sum + input.data.byteLength, 0);
+        if (totalBytes > maxMessageImageBytes) {
+            throw new AttachmentError('Image batch exceeds the configured aggregate image-byte limit.', 'IMAGES_TOO_LARGE');
+        }
+        for (const input of inputs) {
+            if (!mediaTypes.includes(input.mediaType)) {
+                throw new AttachmentError(`Image type ${input.mediaType} is not accepted by this deployment.`, 'UNSUPPORTED_IMAGE_TYPE');
+            }
+        }
+        for (const input of inputs)
+            await this.validateImage(input);
+        const refs = [];
+        for (const input of inputs)
+            refs.push(await this.saveImage(input));
+        return refs;
+    }
+    /**
+     * Persist one file verbatim and return its durable reference.
+     * @param input - complete file bytes and optional display name.
+     * @returns the content-addressed durable reference.
+     */
+    saveFile(input) {
+        void input;
+        return Promise.reject(new AttachmentError('The mounted attachment provider cannot store files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Persist streamed file bytes without requiring one complete input buffer.
+     * @param input - ordered byte chunks, cancellation, and optional display name.
+     * @returns the content-addressed durable reference.
+     */
+    saveFileStream(input) {
+        void input;
+        return Promise.reject(new AttachmentError('The mounted attachment provider cannot store files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Read one durable file as verified byte chunks.
+     * @param ref - durable file reference to verify.
+     * @param signal - optional cancellation signal.
+     * @returns an async sequence of exact file bytes.
+     */
+    async *readFileStream(ref, signal) {
+        signal?.throwIfAborted();
+        void ref;
+        await Promise.reject(new AttachmentError('The mounted attachment provider cannot read files.', 'ATTACHMENT_FILES_UNSUPPORTED'));
+    }
+    /**
+     * Resolve a durable file to a host path when this provider is host-backed.
+     * @param ref - durable file reference.
+     * @returns an absolute host path, or undefined when unavailable.
+     */
+    fileHostPath(ref) { void ref; return undefined; }
+}
+export default AttachmentStore;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned invariant companion for `@hydraharness/harness-attachment`. @module @hydraharness/harness-attachment/invariant */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "attachment-invariant";
+/** Service required before package ownership can be reserved. */
+export declare const inject: string[];
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,16 @@
+/** Package-owned invariant companion for `@hydraharness/harness-attachment`. @module @hydraharness/harness-attachment/invariant */
+const PACKAGE_NAME = '@hydraharness/harness-attachment';
+/** Cordis companion plugin name. */
+export const name = 'attachment-invariant';
+/** Service required before package ownership can be reserved. */
+export const inject = ['invariants'];
+/** No runtime invariant: this stateless seam owns types while implementations enforce immutable-store checks. */
+const install = () => { };
+/**
+ * Register the package invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the registration disposer.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/types/presentation.d.ts

@@ -0,0 +1,26 @@
+/** Durable images shown with a tool result without entering model history. */
+import type { ImageAttachmentRef, VideoAttachmentRef } from './types.ts';
+/**
+ * Read image references from recognized tool presentation metadata.
+ * @param meta - untrusted durable presentation metadata.
+ * @returns validated image references, or an empty list for other metadata.
+ * @throws TypeError when recognized metadata contains an invalid reference.
+ */
+export declare function toolImageReferences(meta: unknown): readonly ImageAttachmentRef[];
+/**
+ * Read durable video references from tool presentation metadata.
+ * @param meta - untrusted durable presentation metadata.
+ * @returns validated video references, or an empty list for other metadata.
+ * @throws TypeError when recognized metadata contains an invalid reference.
+ */
+export declare function toolVideoReferences(meta: unknown): readonly VideoAttachmentRef[];
+/**
+ * Read the actual generating route's display labels from durable metadata.
+ * @param meta - tool presentation metadata.
+ * @returns only string-valued provider and model labels.
+ */
+export declare function toolMediaLabels(meta: unknown): {
+    model?: string;
+    provider?: string;
+};
+//# sourceMappingURL=presentation.d.ts.map

package/lib/types/presentation.js

@@ -0,0 +1,58 @@
+/**
+ * Read image references from recognized tool presentation metadata.
+ * @param meta - untrusted durable presentation metadata.
+ * @returns validated image references, or an empty list for other metadata.
+ * @throws TypeError when recognized metadata contains an invalid reference.
+ */
+export function toolImageReferences(meta) {
+    if (typeof meta !== 'object' || meta === null || !('kind' in meta) || meta.kind !== 'tool-images')
+        return [];
+    const images = meta.images;
+    if (!Array.isArray(images) || images.some((image) => {
+        if (typeof image !== 'object' || image === null)
+            return true;
+        const ref = image;
+        return typeof ref.attachmentId !== 'string' || ref.attachmentId.length === 0
+            || !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(ref.mediaType ?? '')
+            || ![ref.bytes, ref.width, ref.height].every(value => typeof value === 'number' && Number.isSafeInteger(value) && value > 0)
+            || (ref.name !== undefined && typeof ref.name !== 'string');
+    }))
+        throw new TypeError('Invalid tool-image presentation metadata.');
+    return images;
+}
+/**
+ * Read durable video references from tool presentation metadata.
+ * @param meta - untrusted durable presentation metadata.
+ * @returns validated video references, or an empty list for other metadata.
+ * @throws TypeError when recognized metadata contains an invalid reference.
+ */
+export function toolVideoReferences(meta) {
+    if (typeof meta !== 'object' || meta === null || !('kind' in meta) || meta.kind !== 'tool-videos')
+        return [];
+    const videos = meta.videos;
+    if (!Array.isArray(videos) || videos.some((video) => {
+        if (typeof video !== 'object' || video === null)
+            return true;
+        const ref = video;
+        return typeof ref.attachmentId !== 'string' || ref.attachmentId.length === 0
+            || !['video/mp4', 'video/webm'].includes(ref.mediaType ?? '')
+            || typeof ref.bytes !== 'number' || !Number.isSafeInteger(ref.bytes) || ref.bytes <= 0
+            || typeof ref.name !== 'string' || ref.name.length === 0 || /[\\/\u0000-\u001f\u007f]/u.test(ref.name);
+    }))
+        throw new TypeError('Invalid tool-video presentation metadata.');
+    return videos;
+}
+/**
+ * Read the actual generating route's display labels from durable metadata.
+ * @param meta - tool presentation metadata.
+ * @returns only string-valued provider and model labels.
+ */
+export function toolMediaLabels(meta) {
+    if (typeof meta !== 'object' || meta === null)
+        return {};
+    return {
+        ...'model' in meta && typeof meta.model === 'string' ? { model: meta.model } : {},
+        ...'provider' in meta && typeof meta.provider === 'string' ? { provider: meta.provider } : {},
+    };
+}
+//# sourceMappingURL=presentation.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,89 @@
+/** Durable attachment vocabulary. @module @hydraharness/harness-attachment/types */
+import type { AttachmentId } from './brand.ts';
+export type { AttachmentId } from './brand.ts';
+/** Raster image formats accepted by the version-one attachment path. */
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Durable, serializable metadata for one immutable image object. */
+export 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;
+}
+/** Tool-result presentation images, excluded from derived model messages. */
+export interface ToolImagePresentationMeta {
+    kind: 'tool-images';
+    images: ImageAttachmentRef[];
+}
+/** Stored video bytes presented to users without entering model history. */
+export interface VideoAttachmentRef extends FileAttachmentRef {
+    mediaType: 'video/mp4' | 'video/webm';
+}
+/** Tool-result videos read through session-authorized attachment access. */
+export interface ToolVideoPresentationMeta {
+    kind: 'tool-videos';
+    videos: VideoAttachmentRef[];
+}
+/** Durable reference to verbatim stored file bytes. */
+export interface FileAttachmentRef {
+    attachmentId: AttachmentId;
+    name: string;
+    bytes: number;
+}
+/** Base64-encoded file upload. */
+export interface EncodedFileAttachment {
+    data: string;
+    name?: string;
+}
+/** Request to persist exact file bytes. */
+export interface SaveFileAttachment {
+    data: Uint8Array;
+    name?: string;
+}
+/** Streamed request to persist exact file bytes. */
+export interface SaveFileStreamAttachment {
+    data: AsyncIterable<Uint8Array>;
+    signal?: AbortSignal;
+    name?: string;
+}
+/** Deployment-resolved limits used by upload admission and request buffering. */
+export 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[];
+}
+/** Base64-encoded image upload accompanying one wire request. */
+export 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. */
+export 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. */
+export interface StoredImageAttachment {
+    ref: ImageAttachmentRef;
+    data: Uint8Array;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,3 @@
+/** Durable attachment vocabulary. @module @hydraharness/harness-attachment/types */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hydraharness/harness-attachment",
+  "description": "Durable immutable attachment storage seam for the Hydra harness",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/attachment/attachment"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-brand": "^0.1.1-rc.10"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-brand": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10"
+  }
+}