From 44bc5964a4524c2bcf5682f1af78e50c41a22480 Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@gmail.com>
Date: Mon, 2 Mar 2026 01:52:34 -0500
Subject: [PATCH] diffs: harden PDF rendering and remove reserved format schema
 key

---
 extensions/diffs/src/browser.test.ts |  3 +++
 extensions/diffs/src/browser.ts      |  1 -
 extensions/diffs/src/tool.test.ts    | 12 ++++++++++++
 extensions/diffs/src/tool.ts         |  7 +++++--
 4 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/extensions/diffs/src/browser.test.ts b/extensions/diffs/src/browser.test.ts
index d6e23aaaf6f..537859bd928 100644
--- a/extensions/diffs/src/browser.test.ts
+++ b/extensions/diffs/src/browser.test.ts
@@ -137,6 +137,9 @@ describe("PlaywrightDiffScreenshotter", () => {
     expect(launchMock).toHaveBeenCalledTimes(1);
     expect(pages).toHaveLength(1);
     expect(pages[0]?.pdf).toHaveBeenCalledTimes(1);
+    const pdfCall = pages[0]?.pdf.mock.calls[0]?.[0] as Record<string, unknown> | undefined;
+    expect(pdfCall).toBeDefined();
+    expect(pdfCall).not.toHaveProperty("pageRanges");
     expect(pages[0]?.screenshot).toHaveBeenCalledTimes(0);
     await expect(fs.readFile(pdfPath, "utf8")).resolves.toContain("%PDF-1.7");
   });
diff --git a/extensions/diffs/src/browser.ts b/extensions/diffs/src/browser.ts
index a4956de99fe..53eb62c0109 100644
--- a/extensions/diffs/src/browser.ts
+++ b/extensions/diffs/src/browser.ts
@@ -189,7 +189,6 @@ export class PlaywrightDiffScreenshotter implements DiffScreenshotter {
               bottom: "0",
               left: "0",
             },
-            pageRanges: "1",
           });
           return params.outputPath;
         }
diff --git a/extensions/diffs/src/tool.test.ts b/extensions/diffs/src/tool.test.ts
index 7e0de7d5318..8e2e5b70a68 100644
--- a/extensions/diffs/src/tool.test.ts
+++ b/extensions/diffs/src/tool.test.ts
@@ -39,6 +39,18 @@ describe("diffs tool", () => {
     expect((result?.details as Record<string, unknown>).viewerUrl).toBeDefined();
   });
 
+  it("does not expose reserved format in the tool schema", async () => {
+    const tool = createDiffsTool({
+      api: createApi(),
+      store,
+      defaults: DEFAULT_DIFFS_TOOL_DEFAULTS,
+    });
+
+    const parameters = tool.parameters as { properties?: Record<string, unknown> };
+    expect(parameters.properties).toBeDefined();
+    expect(parameters.properties).not.toHaveProperty("format");
+  });
+
   it("returns an image artifact in image mode", async () => {
     const cleanupSpy = vi.spyOn(store, "scheduleCleanup");
     const screenshotter = {
diff --git a/extensions/diffs/src/tool.ts b/extensions/diffs/src/tool.ts
index 697b2d7c0f0..a76efb3e4f1 100644
--- a/extensions/diffs/src/tool.ts
+++ b/extensions/diffs/src/tool.ts
@@ -89,7 +89,6 @@ const DiffsToolSchema = Type.Object(
     imageQuality: Type.Optional(
       stringEnum(DIFF_IMAGE_QUALITY_PRESETS, "Deprecated alias for fileQuality."),
     ),
-    format: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.")),
     imageFormat: Type.Optional(stringEnum(DIFF_OUTPUT_FORMATS, "Deprecated alias for fileFormat.")),
     imageScale: Type.Optional(
       Type.Number({
@@ -126,6 +125,10 @@ const DiffsToolSchema = Type.Object(
 );
 
 type DiffsToolParams = Static<typeof DiffsToolSchema>;
+type DiffsToolRawParams = DiffsToolParams & {
+  // Keep backward compatibility for direct calls that still pass `format`.
+  format?: DiffOutputFormat;
+};
 
 export function createDiffsTool(params: {
   api: OpenClawPluginApi;
@@ -140,7 +143,7 @@ export function createDiffsTool(params: {
       "Create a read-only diff viewer from before/after text or a unified patch. Returns a gateway viewer URL for canvas use and can also render the same diff to a PNG or PDF.",
     parameters: DiffsToolSchema,
     execute: async (_toolCallId, rawParams) => {
-      const toolParams = rawParams as DiffsToolParams;
+      const toolParams = rawParams as DiffsToolRawParams;
       const input = normalizeDiffInput(toolParams);
       const mode = normalizeMode(toolParams.mode, params.defaults.mode);
       const theme = normalizeTheme(toolParams.theme, params.defaults.theme);