@openclaw/diffs 2026.7.2-beta.2 → 2026.7.2-beta.3

package/README.md

@@ -220,7 +220,8 @@ diff --git a/src/example.ts b/src/example.ts
 - Multi-file patches start with a changed-files summary card: totals, per-file `+N`/`-N` stats, change badges, and anchor links.
 - Rendered PNG/PDF files keep the per-file header counts but omit the interactive view toggles.
 - The viewer is hosted locally through the gateway under `/plugins/diffs/...`.
-- Artifacts are ephemeral and stored in the plugin temp subfolder (`$TMPDIR/openclaw-diffs`).
+- Viewer HTML and metadata are ephemeral SQLite plugin blobs. The URL token is returned to the caller while SQLite stores only its SHA-256 hash.
+- Rendered PNG/PDF files remain temporary materializations in `$TMPDIR/openclaw-diffs` because delivery APIs require a file path. No JSON metadata sidecars are written or imported.
 - Default viewer URLs use loopback (`127.0.0.1`) unless you set plugin `viewerBaseUrl`, pass `baseUrl`, or use `gateway.bind=custom` + `gateway.customBindHost`.
 - If `gateway.trustedProxies` includes loopback for a same-host proxy (for example Tailscale Serve), raw `127.0.0.1` viewer requests without forwarded client-IP headers fail closed by design.
 - In that topology, prefer `mode=file` / `mode=both` for attachments, or intentionally enable remote viewers and set plugin `viewerBaseUrl` (or pass a proxy/public `baseUrl`) when you need a shareable viewer URL.

package/dist/index.js

@@ -10,8 +10,9 @@ import { normalizeLowercaseStringOrEmpty, normalizeOptionalString } from "opencl
 import crypto from "node:crypto";
 import fs$1 from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { gunzip, gzip } from "node:zlib";
 import { MAX_DATE_TIMESTAMP_MS, timestampMsToIsoString } from "openclaw/plugin-sdk/number-runtime";
-import { root, safeEqualSecret, writeExternalFileWithinRoot } from "openclaw/plugin-sdk/security-runtime";
+import { safeEqualSecret, writeExternalFileWithinRoot } from "openclaw/plugin-sdk/security-runtime";
 import { optionalFiniteNumberSchema, stringEnum } from "openclaw/plugin-sdk/channel-actions";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { readFiniteNumberParam } from "openclaw/plugin-sdk/param-readers";
@@ -472,19 +473,20 @@ function createDiffsHttpHandler(params) {
 			respondText(res, 404, "Diff not found");
 			return true;
 		}
-		if (!await params.store.getArtifact(id, token)) {
-			recordRemoteFailure(viewerFailureLimiter, access);
-			respondText(res, 404, "Diff not found or expired");
-			return true;
-		}
 		try {
-			const html = await params.store.readHtml(id);
+			const viewer = await params.store.readAuthorizedViewer(id, token);
+			if (!viewer) {
+				recordRemoteFailure(viewerFailureLimiter, access);
+				respondText(res, 404, "Diff not found or expired");
+				return true;
+			}
 			resetRemoteFailures(viewerFailureLimiter, access);
 			res.statusCode = 200;
 			setSharedHeaders(res, "text/html; charset=utf-8");
 			res.setHeader("content-security-policy", VIEWER_CONTENT_SECURITY_POLICY);
+			res.setHeader("content-length", String(viewer.html.byteLength));
 			if (req.method === "HEAD") res.end();
-			else res.end(html);
+			else res.end(Buffer.from(viewer.html));
 			return true;
 		} catch (error) {
 			recordRemoteFailure(viewerFailureLimiter, access);
@@ -634,134 +636,167 @@ const DEFAULT_TTL_MS = 1800 * 1e3;
 const MAX_TTL_MS = 360 * 60 * 1e3;
 const SWEEP_FALLBACK_AGE_MS = 1440 * 60 * 1e3;
 const DEFAULT_CLEANUP_INTERVAL_MS = 300 * 1e3;
+const MAX_DECODED_HTML_BYTES = 64 * 1024 * 1024;
+const ARTIFACT_ID_ATTEMPTS = 8;
 const VIEWER_PREFIX = "/plugins/diffs/view";
+const EMPTY_BLOB = /* @__PURE__ */ new Uint8Array();
+function isBlobLimitError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "PLUGIN_BLOB_LIMIT_EXCEEDED";
+}
 var DiffArtifactStore = class {
 	constructor(params) {
+		this.renderingFileIds = /* @__PURE__ */ new Set();
 		this.cleanupInFlight = null;
 		this.nextCleanupAt = 0;
 		this.rootDir = path.resolve(params.rootDir);
+		this.blobStore = params.blobStore;
 		this.logger = params.logger;
 		this.cleanupIntervalMs = params.cleanupIntervalMs === void 0 ? DEFAULT_CLEANUP_INTERVAL_MS : Math.max(0, Math.floor(params.cleanupIntervalMs));
 	}
 	async createArtifact(params) {
-		await this.ensureRoot();
-		const id = crypto.randomBytes(10).toString("hex");
+		const html = Buffer.from(params.html, "utf8");
+		if (html.byteLength > MAX_DECODED_HTML_BYTES) throw new Error(`Diff viewer HTML exceeds ${MAX_DECODED_HTML_BYTES} bytes.`);
+		const compressedHtml = await gzipAsync(html);
 		const token = crypto.randomBytes(24).toString("hex");
-		const artifactDir = this.artifactDir(id);
-		const htmlPath = path.join(artifactDir, "viewer.html");
 		const ttlMs = normalizeTtlMs$1(params.ttlMs);
-		const createdAt = /* @__PURE__ */ new Date();
-		const createdAtIso = createdAt.toISOString();
-		const expiresAt = resolveExpiresAtIso(createdAt.getTime(), ttlMs);
-		const meta = {
-			id,
-			token,
+		const metadata = {
+			version: 1,
+			kind: "viewer",
+			encoding: "gzip",
+			tokenHash: hashToken(token),
 			title: params.title,
 			inputKind: params.inputKind,
 			fileCount: params.fileCount,
-			createdAt: createdAtIso,
-			expiresAt,
-			viewerPath: `${VIEWER_PREFIX}/${id}/${token}`,
-			htmlPath,
+			decodedBytes: html.byteLength,
 			...params.context ? { context: params.context } : {}
 		};
-		const root = await this.artifactRoot();
-		await root.mkdir(id);
-		await root.write(path.posix.join(id, "viewer.html"), params.html);
-		await this.writeMeta(meta);
+		const entry = await this.registerUnique(compressedHtml, metadata, ttlMs);
 		this.scheduleCleanup();
-		return meta;
+		return viewerEntryToMeta(entry, token);
 	}
-	async getArtifact(id, token) {
-		const meta = await this.readMeta(id);
-		if (!meta) return null;
-		if (!safeEqualSecret(token, meta.token)) return null;
-		if (isExpired(meta)) {
-			await this.deleteArtifact(id);
+	async readAuthorizedViewer(id, token) {
+		if (!DIFF_ARTIFACT_ID_PATTERN.test(id) || !DIFF_ARTIFACT_TOKEN_PATTERN.test(token)) return null;
+		const entry = await this.blobStore.lookup(id);
+		if (!entry) {
+			const expired = await this.blobStore.deleteExpiredKey(id);
+			if (expired) await this.deleteExpiredFile(expired);
 			return null;
 		}
-		return meta;
-	}
-	async readHtml(id) {
-		const meta = await this.readMeta(id);
-		if (!meta) throw new Error(`Diff artifact not found: ${id}`);
-		const htmlPath = this.normalizeStoredPath(meta.htmlPath, "htmlPath");
-		return await (await this.artifactRoot()).readText(this.relativeStoredPath(htmlPath));
-	}
-	async updateFilePath(id, filePath) {
-		const meta = await this.readMeta(id);
-		if (!meta) throw new Error(`Diff artifact not found: ${id}`);
-		const normalizedFilePath = this.normalizeStoredPath(filePath, "filePath");
-		const next = {
-			...meta,
-			filePath: normalizedFilePath,
-			imagePath: normalizedFilePath
+		if (!isViewerMetadata(entry.metadata)) return null;
+		if (!safeEqualSecret(hashToken(token), entry.metadata.tokenHash)) return null;
+		const html = await gunzipAsync(entry.bytes, MAX_DECODED_HTML_BYTES);
+		if (html.byteLength !== entry.metadata.decodedBytes) throw new Error(`Diff artifact ${id} decoded size does not match its metadata.`);
+		return {
+			artifact: viewerEntryToMeta(entry, token),
+			html
 		};
-		await this.writeMeta(next);
-		return next;
-	}
-	async updateImagePath(id, imagePath) {
-		return this.updateFilePath(id, imagePath);
-	}
-	allocateFilePath(id, format = "png") {
-		return path.join(this.artifactDir(id), `preview.${format}`);
 	}
 	async createStandaloneFileArtifact(params = {}) {
-		await this.ensureRoot();
-		const id = crypto.randomBytes(10).toString("hex");
-		const artifactDir = this.artifactDir(id);
 		const format = params.format ?? "png";
-		const filePath = path.join(artifactDir, `preview.${format}`);
 		const ttlMs = normalizeTtlMs$1(params.ttlMs);
-		const createdAt = /* @__PURE__ */ new Date();
-		const meta = {
-			kind: "standalone_file",
-			id,
-			createdAt: createdAt.toISOString(),
-			expiresAt: resolveExpiresAtIso(createdAt.getTime(), ttlMs),
-			filePath: this.normalizeStoredPath(filePath, "filePath"),
+		const metadata = {
+			version: 1,
+			kind: "rendered_file",
+			format,
 			...params.context ? { context: params.context } : {}
 		};
-		await (await this.artifactRoot()).mkdir(id);
-		await this.writeStandaloneMeta(meta);
-		this.scheduleCleanup();
-		return {
-			id,
-			filePath: meta.filePath,
-			expiresAt: meta.expiresAt,
-			...meta.context ? { context: meta.context } : {}
-		};
+		for (let attempt = 0; attempt < ARTIFACT_ID_ATTEMPTS; attempt += 1) {
+			const id = crypto.randomBytes(10).toString("hex");
+			if (!await this.registerIfAbsentWithCleanup(id, EMPTY_BLOB, metadata, ttlMs)) continue;
+			const artifactDir = this.artifactDir(id);
+			try {
+				await fs$1.mkdir(this.rootDir, { recursive: true });
+				await fs$1.mkdir(artifactDir);
+				const entry = await this.blobStore.lookup(id);
+				if (!entry || !isRenderedFileMetadata(entry.metadata)) throw new Error(`Diff file artifact expired before materialization: ${id}`);
+				this.renderingFileIds.add(id);
+				this.scheduleCleanup();
+				return {
+					id,
+					filePath: path.join(artifactDir, `preview.${format}`),
+					expiresAt: resolveEntryExpiresAt(entry),
+					...params.context ? { context: params.context } : {}
+				};
+			} catch (error) {
+				await this.blobStore.delete(id).catch(() => false);
+				await fs$1.rm(artifactDir, {
+					recursive: true,
+					force: true
+				}).catch(() => {});
+				if (isFileExists(error)) continue;
+				throw error;
+			}
+		}
+		throw new Error("Failed to allocate a unique diff file artifact id.");
+	}
+	async completeFileArtifact(id) {
+		try {
+			const entry = await this.blobStore.lookup(id);
+			if (!entry || !isRenderedFileMetadata(entry.metadata)) {
+				await fs$1.rm(this.artifactDir(id), {
+					recursive: true,
+					force: true
+				}).catch(() => {});
+				throw new Error(`Diff file artifact expired during rendering: ${id}`);
+			}
+		} finally {
+			this.renderingFileIds.delete(id);
+		}
 	}
-	allocateImagePath(id, format = "png") {
-		return this.allocateFilePath(id, format);
+	async deleteFileArtifact(id) {
+		this.renderingFileIds.delete(id);
+		await this.blobStore.delete(id).catch(() => false);
+		await fs$1.rm(this.artifactDir(id), {
+			recursive: true,
+			force: true
+		}).catch(() => {});
 	}
 	scheduleCleanup() {
 		this.maybeCleanupExpired();
 	}
 	async cleanupExpired() {
-		const entries = await (await this.artifactRoot()).list("", { withFileTypes: true }).catch(() => []);
+		const expired = await this.blobStore.deleteExpired();
+		await Promise.all(expired.map(async (entry) => await this.deleteExpiredFile(entry)));
+		const entries = await fs$1.readdir(this.rootDir, { withFileTypes: true }).catch((error) => {
+			if (isFileNotFound(error)) return [];
+			throw error;
+		});
 		const now = Date.now();
-		await Promise.all(entries.filter((entry) => entry.isDirectory).map(async (entry) => {
-			const id = entry.name;
-			const meta = await this.readMeta(id);
-			if (meta) {
-				if (isExpired(meta)) await this.deleteArtifact(id);
-				return;
-			}
-			const standaloneMeta = await this.readStandaloneMeta(id);
-			if (standaloneMeta) {
-				if (isExpired(standaloneMeta)) await this.deleteArtifact(id);
-				return;
-			}
-			if (now - entry.mtimeMs > SWEEP_FALLBACK_AGE_MS) await this.deleteArtifact(id);
+		await Promise.all(entries.filter((entry) => entry.isDirectory() && DIFF_ARTIFACT_ID_PATTERN.test(entry.name)).map(async (entry) => {
+			if (this.renderingFileIds.has(entry.name) || await this.blobStore.lookup(entry.name)) return;
+			const artifactDir = this.artifactDir(entry.name);
+			const stats = await fs$1.stat(artifactDir).catch(() => null);
+			if (stats && now - stats.mtimeMs > SWEEP_FALLBACK_AGE_MS) await fs$1.rm(artifactDir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
 		}));
 	}
-	async ensureRoot() {
-		await fs$1.mkdir(this.rootDir, { recursive: true });
+	async registerUnique(bytes, metadata, ttlMs) {
+		for (let attempt = 0; attempt < ARTIFACT_ID_ATTEMPTS; attempt += 1) {
+			const id = crypto.randomBytes(10).toString("hex");
+			if (!await this.registerIfAbsentWithCleanup(id, bytes, metadata, ttlMs)) continue;
+			const entry = await this.blobStore.lookup(id);
+			if (entry) return entry;
+		}
+		throw new Error("Failed to allocate a unique diff artifact id.");
 	}
-	async artifactRoot() {
-		await this.ensureRoot();
-		return await root(this.rootDir);
+	async registerIfAbsentWithCleanup(id, bytes, metadata, ttlMs) {
+		try {
+			return await this.blobStore.registerIfAbsent(id, bytes, metadata, { ttlMs });
+		} catch (error) {
+			if (!isBlobLimitError(error)) throw error;
+			await this.cleanupExpired();
+			return await this.blobStore.registerIfAbsent(id, bytes, metadata, { ttlMs });
+		}
+	}
+	async deleteExpiredFile(entry) {
+		if (!isRenderedFileMetadata(entry.metadata) || this.renderingFileIds.has(entry.key)) return;
+		if (await this.blobStore.lookup(entry.key)) return;
+		await fs$1.rm(this.artifactDir(entry.key), {
+			recursive: true,
+			force: true
+		}).catch(() => {});
 	}
 	maybeCleanupExpired() {
 		const now = Date.now();
@@ -776,104 +811,85 @@ var DiffArtifactStore = class {
 		this.cleanupInFlight = cleanupPromise;
 	}
 	artifactDir(id) {
-		return this.resolveWithinRoot(id);
-	}
-	async writeMeta(meta) {
-		await this.writeJsonMeta(meta.id, "meta.json", meta);
-	}
-	async readMeta(id) {
-		const parsed = await this.readJsonMeta(id, "meta.json", "diff artifact");
-		if (!parsed) return null;
-		return parsed;
-	}
-	async writeStandaloneMeta(meta) {
-		await this.writeJsonMeta(meta.id, "file-meta.json", meta);
-	}
-	async readStandaloneMeta(id) {
-		const parsed = await this.readJsonMeta(id, "file-meta.json", "standalone diff");
-		if (!parsed) return null;
-		try {
-			const value = parsed;
-			if (value.kind !== "standalone_file" || typeof value.id !== "string" || typeof value.createdAt !== "string" || typeof value.expiresAt !== "string" || typeof value.filePath !== "string") return null;
-			return {
-				kind: value.kind,
-				id: value.id,
-				createdAt: value.createdAt,
-				expiresAt: value.expiresAt,
-				filePath: this.normalizeStoredPath(value.filePath, "filePath"),
-				...value.context ? { context: normalizeArtifactContext(value.context) } : {}
-			};
-		} catch (error) {
-			this.logger?.warn(`Failed to normalize standalone diff metadata for ${id}: ${String(error)}`);
-			return null;
-		}
-	}
-	async writeJsonMeta(id, fileName, data) {
-		await (await this.artifactRoot()).writeJson(path.posix.join(id, fileName), data, { space: 2 });
-	}
-	async readJsonMeta(id, fileName, context) {
-		try {
-			const raw = await (await this.artifactRoot()).readText(path.posix.join(id, fileName));
-			return JSON.parse(raw);
-		} catch (error) {
-			if (isFileNotFound(error)) return null;
-			this.logger?.warn(`Failed to read ${context} metadata for ${id}: ${String(error)}`);
-			return null;
-		}
-	}
-	async deleteArtifact(id) {
-		await fs$1.rm(this.artifactDir(id), {
-			recursive: true,
-			force: true
-		}).catch(() => {});
-	}
-	resolveWithinRoot(...parts) {
-		const candidate = path.resolve(this.rootDir, ...parts);
-		this.assertWithinRoot(candidate);
-		return candidate;
-	}
-	normalizeStoredPath(rawPath, label) {
-		const candidate = path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(this.rootDir, rawPath);
-		this.assertWithinRoot(candidate, label);
-		return candidate;
-	}
-	relativeStoredPath(storedPath) {
-		return path.relative(this.rootDir, this.normalizeStoredPath(storedPath, "path")).split(path.sep).join(path.posix.sep);
-	}
-	assertWithinRoot(candidate, label = "path") {
-		const relative = path.relative(this.rootDir, candidate);
-		if (relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative)) return;
-		throw new Error(`Diff artifact ${label} escapes store root: ${candidate}`);
+		if (!DIFF_ARTIFACT_ID_PATTERN.test(id)) throw new Error(`Invalid diff artifact id: ${id}`);
+		return path.join(this.rootDir, id);
 	}
 };
+function viewerEntryToMeta(entry, token) {
+	if (!isViewerMetadata(entry.metadata)) throw new Error(`Diff artifact ${entry.key} is not a viewer.`);
+	return {
+		id: entry.key,
+		token,
+		createdAt: timestampMsToIsoString(entry.createdAt) ?? "1970-01-01T00:00:00.000Z",
+		expiresAt: resolveEntryExpiresAt(entry),
+		title: entry.metadata.title,
+		inputKind: entry.metadata.inputKind,
+		fileCount: entry.metadata.fileCount,
+		viewerPath: `${VIEWER_PREFIX}/${entry.key}/${token}`,
+		...entry.metadata.context ? { context: entry.metadata.context } : {}
+	};
+}
+function resolveEntryExpiresAt(entry) {
+	return timestampMsToIsoString(entry.expiresAt ?? MAX_DATE_TIMESTAMP_MS) ?? timestampMsToIsoString(MAX_DATE_TIMESTAMP_MS) ?? "1970-01-01T00:00:00.000Z";
+}
+function hashToken(token) {
+	return crypto.createHash("sha256").update(token).digest("hex");
+}
 function normalizeTtlMs$1(value) {
-	if (!Number.isFinite(value) || value === void 0) return DEFAULT_TTL_MS;
-	const rounded = Math.floor(value);
-	if (rounded <= 0) return DEFAULT_TTL_MS;
-	return Math.min(rounded, MAX_TTL_MS);
+	const rounded = value === void 0 || !Number.isFinite(value) ? 0 : Math.floor(value);
+	const requestedTtlMs = rounded > 0 ? rounded : DEFAULT_TTL_MS;
+	const remainingDateRangeMs = Math.floor(MAX_DATE_TIMESTAMP_MS - Date.now());
+	return Math.min(requestedTtlMs, MAX_TTL_MS, Math.max(1, remainingDateRangeMs));
+}
+function isViewerMetadata(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const metadata = value;
+	return metadata.version === 1 && metadata.kind === "viewer" && metadata.encoding === "gzip" && typeof metadata.tokenHash === "string" && /^[0-9a-f]{64}$/u.test(metadata.tokenHash) && typeof metadata.title === "string" && (metadata.inputKind === "before_after" || metadata.inputKind === "patch") && Number.isSafeInteger(metadata.fileCount) && typeof metadata.fileCount === "number" && metadata.fileCount >= 0 && Number.isSafeInteger(metadata.decodedBytes) && typeof metadata.decodedBytes === "number" && metadata.decodedBytes >= 0 && metadata.decodedBytes <= MAX_DECODED_HTML_BYTES && isArtifactContext(metadata.context);
+}
+function isRenderedFileMetadata(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const metadata = value;
+	return metadata.version === 1 && metadata.kind === "rendered_file" && (metadata.format === "png" || metadata.format === "pdf") && isArtifactContext(metadata.context);
+}
+function isArtifactContext(value) {
+	if (value === void 0) return true;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const context = value;
+	const allowed = /* @__PURE__ */ new Set([
+		"agentId",
+		"sessionId",
+		"messageChannel",
+		"agentAccountId"
+	]);
+	return Object.entries(context).every(([key, entry]) => allowed.has(key) && (entry === void 0 || typeof entry === "string"));
 }
-function resolveExpiresAtIso(createdAtMs, ttlMs) {
-	return timestampMsToIsoString(createdAtMs + ttlMs) ?? timestampMsToIsoString(MAX_DATE_TIMESTAMP_MS) ?? "1970-01-01T00:00:00.000Z";
+async function gzipAsync(input) {
+	return await new Promise((resolve, reject) => {
+		gzip(input, (error, result) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolve(result);
+		});
+	});
 }
-function isExpired(meta) {
-	const expiresAt = Date.parse(meta.expiresAt);
-	if (!Number.isFinite(expiresAt)) return true;
-	return Date.now() >= expiresAt;
+async function gunzipAsync(input, maxOutputLength) {
+	return await new Promise((resolve, reject) => {
+		gunzip(input, { maxOutputLength }, (error, result) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolve(result);
+		});
+	});
+}
+function isFileExists(error) {
+	return error instanceof Error && "code" in error && error.code === "EEXIST";
 }
 function isFileNotFound(error) {
-	const code = error instanceof Error && "code" in error ? error.code : void 0;
-	return code === "ENOENT" || code === "not-found";
-}
-function normalizeArtifactContext(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return;
-	const raw = value;
-	const context = {
-		agentId: normalizeOptionalString(raw.agentId),
-		sessionId: normalizeOptionalString(raw.sessionId),
-		messageChannel: normalizeOptionalString(raw.messageChannel),
-		agentAccountId: normalizeOptionalString(raw.agentAccountId)
-	};
-	return Object.values(context).some((entry) => entry !== void 0) ? context : void 0;
+	return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 //#endregion
 //#region extensions/diffs/src/browser.ts
@@ -2304,12 +2320,12 @@ function createDiffsTool(params) {
 				const artifactFile = await renderDiffArtifactFile({
 					screenshotter,
 					store: params.store,
-					artifactId: artifact.id,
 					html: requireRenderedHtml(rendered.imageHtml, "image"),
 					theme,
-					image
+					image,
+					ttlMs,
+					context: artifactContext
 				});
-				await params.store.updateFilePath(artifact.id, artifactFile.path);
 				return {
 					content: [{
 						type: "text",
@@ -2381,34 +2397,44 @@ function buildFileArtifactMessage(params) {
 	return lines.join("\n");
 }
 async function renderDiffArtifactFile(params) {
-	const standaloneArtifact = params.artifactId ? void 0 : await params.store.createStandaloneFileArtifact({
+	const fileArtifact = await params.store.createStandaloneFileArtifact({
 		format: params.image.format,
 		ttlMs: params.ttlMs,
 		context: params.context
 	});
-	const outputPath = params.artifactId ? params.store.allocateFilePath(params.artifactId, params.image.format) : standaloneArtifact.filePath;
-	await params.screenshotter.screenshotHtml({
-		html: params.html,
-		outputPath,
-		theme: params.theme,
-		image: params.image
-	});
-	return {
-		path: outputPath,
-		bytes: (await fs$1.stat(outputPath)).size,
-		...standaloneArtifact?.id ? { artifactId: standaloneArtifact.id } : {},
-		...standaloneArtifact?.expiresAt ? { expiresAt: standaloneArtifact.expiresAt } : {}
-	};
+	try {
+		await params.screenshotter.screenshotHtml({
+			html: params.html,
+			outputPath: fileArtifact.filePath,
+			theme: params.theme,
+			image: params.image
+		});
+		const stats = await fs$1.stat(fileArtifact.filePath);
+		await params.store.completeFileArtifact(fileArtifact.id);
+		return {
+			path: fileArtifact.filePath,
+			bytes: stats.size,
+			artifactId: fileArtifact.id,
+			expiresAt: fileArtifact.expiresAt
+		};
+	} catch (error) {
+		await params.store.deleteFileArtifact(fileArtifact.id);
+		throw error;
+	}
 }
 function buildArtifactContext(context) {
 	if (!context) return;
+	const agentId = normalizeOptionalString(context.agentId);
+	const sessionId = normalizeOptionalString(context.sessionId);
+	const messageChannel = normalizeOptionalString(context.messageChannel);
+	const agentAccountId = normalizeOptionalString(context.agentAccountId);
 	const artifactContext = {
-		agentId: normalizeOptionalString(context.agentId),
-		sessionId: normalizeOptionalString(context.sessionId),
-		messageChannel: normalizeOptionalString(context.messageChannel),
-		agentAccountId: normalizeOptionalString(context.agentAccountId)
+		...agentId ? { agentId } : {},
+		...sessionId ? { sessionId } : {},
+		...messageChannel ? { messageChannel } : {},
+		...agentAccountId ? { agentAccountId } : {}
 	};
-	return Object.values(artifactContext).some((value) => value !== void 0) ? artifactContext : void 0;
+	return Object.keys(artifactContext).length > 0 ? artifactContext : void 0;
 }
 function normalizeDiffInput(params) {
 	const patch = params.patch?.trim();
@@ -2478,9 +2504,20 @@ var PluginToolInputError = class extends Error {
 //#endregion
 //#region extensions/diffs/src/plugin.ts
 const DIFFS_LANGUAGE_PACK_PLUGIN_ID = "diffs-language-pack";
+const DIFF_ARTIFACT_NAMESPACE = "diff-artifacts";
+const DIFF_ARTIFACT_MAX_ENTRIES = 2048;
+const DIFF_ARTIFACT_MAX_BYTES_PER_ENTRY = 32 * 1024 * 1024;
+const DIFF_ARTIFACT_MAX_BYTES_PER_NAMESPACE = 256 * 1024 * 1024;
 function registerDiffsPlugin(api) {
 	const store = new DiffArtifactStore({
 		rootDir: path.join(resolvePreferredOpenClawTmpDir(), "openclaw-diffs"),
+		blobStore: api.runtime.state.openBlobStore({
+			namespace: DIFF_ARTIFACT_NAMESPACE,
+			maxEntries: DIFF_ARTIFACT_MAX_ENTRIES,
+			maxBytesPerEntry: DIFF_ARTIFACT_MAX_BYTES_PER_ENTRY,
+			maxBytesPerNamespace: DIFF_ARTIFACT_MAX_BYTES_PER_NAMESPACE,
+			overflowPolicy: "reject-new"
+		}),
 		logger: api.logger
 	});
 	const resolveCurrentPluginConfig = () => resolveLivePluginConfigObject(api.runtime.config?.current ? () => api.runtime.config.current() : void 0, "diffs", api.pluginConfig) ?? {};

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@openclaw/diffs",
-  "version": "2026.7.2-beta.2",
+  "version": "2026.7.2-beta.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@openclaw/diffs",
-      "version": "2026.7.2-beta.2",
+      "version": "2026.7.2-beta.3",
       "dependencies": {
         "@pierre/diffs": "1.2.12",
         "@shikijs/langs": "4.3.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/diffs",
-  "version": "2026.7.2-beta.2",
+  "version": "2026.7.2-beta.3",
   "description": "OpenClaw read-only diff viewer plugin and file renderer for agents.",
   "repository": {
     "type": "git",
@@ -25,13 +25,13 @@
       "minHostVersion": ">=2026.4.30"
     },
     "compat": {
-      "pluginApi": ">=2026.7.2-beta.2"
+      "pluginApi": ">=2026.7.2-beta.3"
     },
     "assetScripts": {
       "build": "node ../../scripts/build-diffs-viewer-runtime.mjs curated"
     },
     "build": {
-      "openclawVersion": "2026.7.2-beta.2",
+      "openclawVersion": "2026.7.2-beta.3",
       "staticAssets": [
         {
           "source": "./assets/viewer-runtime.js",
@@ -55,7 +55,7 @@
     "skills/**"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.7.2-beta.2"
+    "openclaw": ">=2026.7.2-beta.3"
   },
   "peerDependenciesMeta": {
     "openclaw": {