@openclaw/diffs 2026.5.7 → 2026.5.10-beta.1

package/README.md

@@ -106,6 +106,7 @@ Set plugin-wide defaults in `~/.openclaw/openclaw.json`:
             fileScale: 2,
             fileMaxWidth: 960,
             mode: "both",
+            ttlSeconds: 21600,
           },
         },
       },
@@ -120,6 +121,7 @@ Security options:
 
 - `security.allowRemoteViewer` (default `false`): allows non-loopback access to `/plugins/diffs/view/...` token URLs
 - `viewerBaseUrl` (optional): persistent viewer-link origin/path fallback for shareable URLs
+- `defaults.ttlSeconds` (default `1800`, max `21600`): default artifact lifetime for viewer and standalone file outputs
 
 Example:
 

package/dist/index.js

@@ -10,12 +10,15 @@ import { normalizeLowercaseStringOrEmpty, normalizeOptionalString } from "opencl
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { root, writeExternalFileWithinRoot } from "openclaw/plugin-sdk/security-runtime";
+import { stringEnum } from "openclaw/plugin-sdk/channel-actions";
 import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { Type } from "typebox";
 import { constants } from "node:fs";
 import { chromium } from "playwright-core";
 import { RegisteredCustomThemes, ResolvedThemes, ResolvingThemes, parsePatchFiles, resolveLanguage } from "@pierre/diffs";
 import { preloadFileDiff, preloadMultiFileDiff } from "@pierre/diffs/ssr";
+import { readJsonFileWithFallback } from "openclaw/plugin-sdk/json-store";
 //#region extensions/diffs/src/types.ts
 const DIFF_LAYOUTS = ["unified", "split"];
 const DIFF_MODES = [
@@ -104,7 +107,8 @@ const DEFAULT_DIFFS_TOOL_DEFAULTS = {
 	fileQuality: "standard",
 	fileScale: DEFAULT_IMAGE_QUALITY_PROFILES.standard.scale,
 	fileMaxWidth: DEFAULT_IMAGE_QUALITY_PROFILES.standard.maxWidth,
-	mode: "both"
+	mode: "both",
+	ttlSeconds: 1800
 };
 const DEFAULT_DIFFS_PLUGIN_SECURITY = { allowRemoteViewer: false };
 const VIEWER_BASE_URL_JSON_SCHEMA = {
@@ -143,7 +147,8 @@ const DiffsPluginJsonSchemaSource = z.strictObject({
 		imageQuality: z.enum(DIFF_IMAGE_QUALITY_PRESETS).optional().describe("Deprecated alias for fileQuality."),
 		imageScale: z.number().min(1).max(4).optional().describe("Deprecated alias for fileScale."),
 		imageMaxWidth: z.number().min(640).max(2400).optional().describe("Deprecated alias for fileMaxWidth."),
-		mode: z.enum(DIFF_MODES).default(DEFAULT_DIFFS_TOOL_DEFAULTS.mode).optional()
+		mode: z.enum(DIFF_MODES).default(DEFAULT_DIFFS_TOOL_DEFAULTS.mode).optional(),
+		ttlSeconds: z.number().min(1).max(21600).default(DEFAULT_DIFFS_TOOL_DEFAULTS.ttlSeconds).optional()
 	}).optional(),
 	security: z.strictObject({ allowRemoteViewer: z.boolean().default(DEFAULT_DIFFS_PLUGIN_SECURITY.allowRemoteViewer).optional() }).optional()
 });
@@ -222,7 +227,8 @@ function resolveDiffsPluginDefaults(config) {
 		fileQuality,
 		fileScale: normalizeFileScale(fileScale, profile.scale),
 		fileMaxWidth: normalizeFileMaxWidth(fileMaxWidth, profile.maxWidth),
-		mode: normalizeMode$1(defaults.mode)
+		mode: normalizeMode$1(defaults.mode),
+		ttlSeconds: normalizeTtlSeconds(defaults.ttlSeconds)
 	};
 }
 function resolveDiffsPluginSecurity(config) {
@@ -276,6 +282,10 @@ function normalizeFileMaxWidth(fileMaxWidth, fallback) {
 function normalizeMode$1(mode) {
 	return mode && DIFF_MODES.includes(mode) ? mode : DEFAULT_DIFFS_TOOL_DEFAULTS.mode;
 }
+function normalizeTtlSeconds(ttlSeconds) {
+	if (ttlSeconds === void 0 || !Number.isFinite(ttlSeconds)) return DEFAULT_DIFFS_TOOL_DEFAULTS.ttlSeconds;
+	return Math.min(Math.max(Math.floor(ttlSeconds), 1), 21600);
+}
 function resolveDiffImageRenderOptions(params) {
 	const format = normalizeFileFormat(params.fileFormat ?? params.imageFormat ?? params.format ?? params.defaults.fileFormat);
 	const qualityOverrideProvided = params.fileQuality !== void 0 || params.imageQuality !== void 0;
@@ -597,8 +607,9 @@ var DiffArtifactStore = class {
 			htmlPath,
 			...params.context ? { context: params.context } : {}
 		};
-		await fs.mkdir(artifactDir, { recursive: true });
-		await fs.writeFile(htmlPath, params.html, "utf8");
+		const root = await this.artifactRoot();
+		await root.mkdir(id);
+		await root.write(path.posix.join(id, "viewer.html"), params.html);
 		await this.writeMeta(meta);
 		this.scheduleCleanup();
 		return meta;
@@ -617,7 +628,7 @@ var DiffArtifactStore = class {
 		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 fs.readFile(htmlPath, "utf8");
+		return await (await this.artifactRoot()).readText(this.relativeStoredPath(htmlPath));
 	}
 	async updateFilePath(id, filePath) {
 		const meta = await this.readMeta(id);
@@ -654,7 +665,7 @@ var DiffArtifactStore = class {
 			filePath: this.normalizeStoredPath(filePath, "filePath"),
 			...params.context ? { context: params.context } : {}
 		};
-		await fs.mkdir(artifactDir, { recursive: true });
+		await (await this.artifactRoot()).mkdir(id);
 		await this.writeStandaloneMeta(meta);
 		this.scheduleCleanup();
 		return {
@@ -671,10 +682,9 @@ var DiffArtifactStore = class {
 		this.maybeCleanupExpired();
 	}
 	async cleanupExpired() {
-		await this.ensureRoot();
-		const entries = await fs.readdir(this.rootDir, { withFileTypes: true }).catch(() => []);
+		const entries = await (await this.artifactRoot()).list("", { withFileTypes: true }).catch(() => []);
 		const now = Date.now();
-		await Promise.all(entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+		await Promise.all(entries.filter((entry) => entry.isDirectory).map(async (entry) => {
 			const id = entry.name;
 			const meta = await this.readMeta(id);
 			if (meta) {
@@ -686,15 +696,16 @@ var DiffArtifactStore = class {
 				if (isExpired(standaloneMeta)) await this.deleteArtifact(id);
 				return;
 			}
-			const artifactPath = this.artifactDir(id);
-			const stat = await fs.stat(artifactPath).catch(() => null);
-			if (!stat) return;
-			if (now - stat.mtimeMs > SWEEP_FALLBACK_AGE_MS) await this.deleteArtifact(id);
+			if (now - entry.mtimeMs > SWEEP_FALLBACK_AGE_MS) await this.deleteArtifact(id);
 		}));
 	}
 	async ensureRoot() {
 		await fs.mkdir(this.rootDir, { recursive: true });
 	}
+	async artifactRoot() {
+		await this.ensureRoot();
+		return await root(this.rootDir);
+	}
 	maybeCleanupExpired() {
 		const now = Date.now();
 		if (this.cleanupInFlight || now < this.nextCleanupAt) return;
@@ -740,15 +751,12 @@ var DiffArtifactStore = class {
 			return null;
 		}
 	}
-	metaFilePath(id, fileName) {
-		return path.join(this.artifactDir(id), fileName);
-	}
 	async writeJsonMeta(id, fileName, data) {
-		await fs.writeFile(this.metaFilePath(id, fileName), JSON.stringify(data, null, 2), "utf8");
+		await (await this.artifactRoot()).writeJson(path.posix.join(id, fileName), data, { space: 2 });
 	}
 	async readJsonMeta(id, fileName, context) {
 		try {
-			const raw = await fs.readFile(this.metaFilePath(id, fileName), "utf8");
+			const raw = await (await this.artifactRoot()).readText(path.posix.join(id, fileName));
 			return JSON.parse(raw);
 		} catch (error) {
 			if (isFileNotFound(error)) return null;
@@ -772,6 +780,9 @@ var DiffArtifactStore = class {
 		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;
@@ -790,7 +801,8 @@ function isExpired(meta) {
 	return Date.now() >= expiresAt;
 }
 function isFileNotFound(error) {
-	return error instanceof Error && "code" in error && error.code === "ENOENT";
+	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;
@@ -819,7 +831,6 @@ var PlaywrightDiffScreenshotter = class {
 		this.browserIdleMs = params.browserIdleMs ?? DEFAULT_BROWSER_IDLE_MS;
 	}
 	async screenshotHtml(params) {
-		await fs.mkdir(path.dirname(params.outputPath), { recursive: true });
 		const lease = await acquireSharedBrowser({
 			config: this.config,
 			idleMs: this.browserIdleMs
@@ -918,16 +929,22 @@ var PlaywrightDiffScreenshotter = class {
 					const estimatedPixels = pdfWidth * pdfHeight;
 					const estimatedPages = Math.ceil(pdfHeight / PDF_REFERENCE_PAGE_HEIGHT_PX);
 					if (estimatedPixels > params.image.maxPixels || estimatedPages > MAX_PDF_PAGES) throw new Error(IMAGE_SIZE_LIMIT_ERROR);
-					await page.pdf({
-						path: params.outputPath,
-						width: `${pdfWidth}px`,
-						height: `${pdfHeight}px`,
-						printBackground: true,
-						margin: {
-							top: "0",
-							right: "0",
-							bottom: "0",
-							left: "0"
+					const pageForPdf = page;
+					await writeExternalArtifactFile({
+						outputPath: params.outputPath,
+						write: async (tempPath) => {
+							await pageForPdf.pdf({
+								path: tempPath,
+								width: `${pdfWidth}px`,
+								height: `${pdfHeight}px`,
+								printBackground: true,
+								margin: {
+									top: "0",
+									right: "0",
+									bottom: "0",
+									left: "0"
+								}
+							});
 						}
 					});
 					return params.outputPath;
@@ -956,15 +973,21 @@ var PlaywrightDiffScreenshotter = class {
 					}
 					throw new Error(IMAGE_SIZE_LIMIT_ERROR);
 				}
-				await page.screenshot({
-					path: params.outputPath,
-					type: "png",
-					scale: "device",
-					clip: {
-						x,
-						y,
-						width: cssWidth,
-						height: cssHeight
+				const pageForScreenshot = page;
+				await writeExternalArtifactFile({
+					outputPath: params.outputPath,
+					write: async (tempPath) => {
+						await pageForScreenshot.screenshot({
+							path: tempPath,
+							type: "png",
+							scale: "device",
+							clip: {
+								x,
+								y,
+								width: cssWidth,
+								height: cssHeight
+							}
+						});
 					}
 				});
 				return params.outputPath;
@@ -980,6 +1003,15 @@ var PlaywrightDiffScreenshotter = class {
 		}
 	}
 };
+async function writeExternalArtifactFile(params) {
+	const rootDir = path.dirname(params.outputPath);
+	await fs.mkdir(rootDir, { recursive: true });
+	await writeExternalFileWithinRoot({
+		rootDir,
+		path: path.basename(params.outputPath),
+		write: params.write
+	});
+}
 function injectBaseHref(html) {
 	if (html.includes("<base ")) return html;
 	return html.replace("<head>", `<head><base href="${LOCAL_VIEWER_BASE_HREF}" />`);
@@ -1169,13 +1201,8 @@ async function isExecutable(candidate) {
 //#endregion
 //#region extensions/diffs/src/language-hints.ts
 const PASSTHROUGH_LANGUAGE_HINTS = new Set(["ansi", "text"]);
-function normalizeOptionalString$1(value) {
-	if (typeof value !== "string") return;
-	const trimmed = value.trim();
-	return trimmed ? trimmed : void 0;
-}
 async function normalizeSupportedLanguageHint(value) {
-	const normalized = normalizeOptionalString$1(value);
+	const normalized = normalizeOptionalString(value);
 	if (!normalized) return;
 	if (PASSTHROUGH_LANGUAGE_HINTS.has(normalized)) return normalized;
 	try {
@@ -1246,9 +1273,9 @@ function createThemeLoader(themeName, themeSpecifier) {
 	let cachedTheme;
 	return async () => {
 		if (cachedTheme) return cachedTheme;
-		const themePath = themeRequire.resolve(themeSpecifier);
+		const { value: theme } = await readJsonFileWithFallback(themeRequire.resolve(themeSpecifier), {});
 		cachedTheme = {
-			...JSON.parse(await fs.readFile(themePath, "utf8")),
+			...theme,
 			name: themeName
 		};
 		return cachedTheme;
@@ -1677,14 +1704,6 @@ const MAX_PATCH_BYTES = 2 * 1024 * 1024;
 const MAX_TITLE_BYTES = 1024;
 const MAX_PATH_BYTES = 2048;
 const MAX_LANG_BYTES = 128;
-function stringEnum(values, description, options = {}) {
-	return Type.Unsafe({
-		type: "string",
-		enum: [...values],
-		description,
-		...options
-	});
-}
 const DiffsToolSchema = Type.Object({
 	before: Type.Optional(Type.String({ description: "Original text content." })),
 	after: Type.Optional(Type.String({ description: "Updated text content." })),
@@ -1704,11 +1723,11 @@ const DiffsToolSchema = Type.Object({
 		description: "Optional title for the rendered diff.",
 		maxLength: MAX_TITLE_BYTES
 	})),
-	mode: Type.Optional(stringEnum(DIFF_MODES, "Output mode: view, file, image (deprecated alias for file), or both. Default: both.")),
-	theme: Type.Optional(stringEnum(DIFF_THEMES, "Viewer theme. Default: dark.")),
-	layout: Type.Optional(stringEnum(DIFF_LAYOUTS, "Diff layout. Default: unified.")),
-	fileQuality: Type.Optional(stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "File quality preset: standard, hq, or print.")),
-	fileFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Rendered file format: png or pdf.")),
+	mode: Type.Optional(stringEnum(DIFF_MODES, { description: "Output mode: view, file, image (deprecated alias for file), or both. Default: both." })),
+	theme: Type.Optional(stringEnum(DIFF_THEMES, { description: "Viewer theme. Default: dark." })),
+	layout: Type.Optional(stringEnum(DIFF_LAYOUTS, { description: "Diff layout. Default: unified." })),
+	fileQuality: Type.Optional(stringEnum(DIFF_IMAGE_QUALITY_PRESETS, { description: "File quality preset: standard, hq, or print." })),
+	fileFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, { description: "Rendered file format: png or pdf." })),
 	fileScale: Type.Optional(Type.Number({
 		description: "Optional rendered-file device scale factor override (1-4).",
 		minimum: 1,
@@ -1720,9 +1739,15 @@ const DiffsToolSchema = Type.Object({
 		maximum: 2400
 	})),
 	/** @deprecated Use fileQuality. */
-	imageQuality: Type.Optional(stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "Deprecated alias for fileQuality.", { deprecated: true })),
+	imageQuality: Type.Optional(stringEnum(DIFF_IMAGE_QUALITY_PRESETS, {
+		description: "Deprecated alias for fileQuality.",
+		deprecated: true
+	})),
 	/** @deprecated Use fileFormat. */
-	imageFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.", { deprecated: true })),
+	imageFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, {
+		description: "Deprecated alias for fileFormat.",
+		deprecated: true
+	})),
 	/** @deprecated Use fileScale. */
 	imageScale: Type.Optional(Type.Number({
 		description: "Deprecated alias for fileScale.",
@@ -1759,7 +1784,7 @@ function createDiffsTool(params) {
 			const theme = normalizeTheme(toolParams.theme, params.defaults.theme);
 			const layout = normalizeLayout(toolParams.layout, params.defaults.layout);
 			const expandUnchanged = toolParams.expandUnchanged === true;
-			const ttlMs = normalizeTtlMs(toolParams.ttlSeconds);
+			const ttlMs = normalizeTtlMs(toolParams.ttlSeconds ?? params.defaults.ttlSeconds);
 			const image = resolveDiffImageRenderOptions({
 				defaults: params.defaults,
 				fileFormat: normalizeOutputFormat(toolParams.fileFormat ?? toolParams.imageFormat ?? toolParams.format),

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "diffs",
   "activation": {
-    "onStartup": false
+    "onStartup": true
   },
   "name": "Diffs",
   "description": "Read-only diff viewer and file renderer for agents.",
@@ -75,6 +75,10 @@
       "label": "Default Output Mode",
       "help": "Tool default when mode is omitted. Use view for canvas/gateway viewer, file for PNG/PDF, or both."
     },
+    "defaults.ttlSeconds": {
+      "label": "Default Artifact TTL",
+      "help": "Default lifetime in seconds for diff viewer and file artifacts. Maximum: 21600."
+    },
     "security.allowRemoteViewer": {
       "label": "Allow Remote Viewer",
       "help": "Allow non-loopback access to diff viewer URLs when the token path is known."
@@ -190,6 +194,12 @@
             "type": "string",
             "enum": ["view", "image", "file", "both"],
             "default": "both"
+          },
+          "ttlSeconds": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 21600,
+            "default": 1800
           }
         }
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/diffs",
-  "version": "2026.5.7",
+  "version": "2026.5.10-beta.1",
   "description": "OpenClaw diff viewer plugin",
   "repository": {
     "type": "git",
@@ -11,10 +11,10 @@
     "build:viewer": "bun build src/viewer-client.ts --target browser --format esm --minify --outfile assets/viewer-runtime.js"
   },
   "dependencies": {
-    "@pierre/diffs": "1.1.20",
+    "@pierre/diffs": "1.1.21",
     "@pierre/theme": "0.0.29",
     "playwright-core": "1.59.1",
-    "typebox": "1.1.37"
+    "typebox": "1.1.38"
   },
   "devDependencies": {
     "@openclaw/plugin-sdk": "workspace:*"
@@ -30,10 +30,10 @@
       "minHostVersion": ">=2026.4.30"
     },
     "compat": {
-      "pluginApi": ">=2026.5.7"
+      "pluginApi": ">=2026.5.10-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.5.7",
+      "openclawVersion": "2026.5.10-beta.1",
       "staticAssets": [
         {
           "source": "./assets/viewer-runtime.js",
@@ -56,7 +56,7 @@
     "skills/**"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.5.7"
+    "openclaw": ">=2026.5.10-beta.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {