pdf-server: add save_as interact action

Adds a model-callable save_as action to the interact tool that writes the
viewer's current annotated state (annotations + form values) to a new file.

Reuses the get_pages request/reply pattern: model's interact call blocks
while the viewer builds bytes via getAnnotatedPdfBytes() and posts them
back through a new submit_save_data app-only tool.

Validation runs synchronously before bothering the viewer:
- path must be absolute or file://
- isWritablePath gate (same as save_pdf)
- existence check; fails with a descriptive error unless overwrite: true

The viewer can report build errors back via submit_save_data({error}),
so the model gets a real message instead of the 45s timeout.

Author: ochafik

examples/pdf-server/README.md

@@ -188,13 +188,13 @@ When roots are ignored the server logs:
 
 ## Tools
 
-| Tool             | Visibility | Purpose                                               |
-| ---------------- | ---------- | ----------------------------------------------------- |
-| `list_pdfs`      | Model      | List available local files and origins                |
-| `display_pdf`    | Model + UI | Display interactive viewer                            |
-| `interact`¹      | Model      | Navigate, annotate, search, extract pages, fill forms |
-| `read_pdf_bytes` | App only   | Stream PDF data in chunks                             |
-| `save_pdf`       | App only   | Save annotated PDF back to local file                 |
+| Tool             | Visibility | Purpose                                                             |
+| ---------------- | ---------- | ------------------------------------------------------------------- |
+| `list_pdfs`      | Model      | List available local files and origins                              |
+| `display_pdf`    | Model + UI | Display interactive viewer                                          |
+| `interact`¹      | Model      | Navigate, annotate, search, extract pages, fill forms, save to file |
+| `read_pdf_bytes` | App only   | Stream PDF data in chunks                                           |
+| `save_pdf`       | App only   | Save annotated PDF back to local file                               |
 
 ¹ stdio only by default; in HTTP mode requires `--enable-interact` — see [Deployment](#deployment).
 
@@ -250,6 +250,12 @@ After the model calls `display_pdf`, it receives the `viewUUID` and a descriptio
 >
 > _Model calls `interact` with action `fill_form`, fields `[{name:"Name", value:"Alice"}, {name:"Date", value:"2026-02-26"}]`_
 
+### Saving
+
+> **User:** Save the annotated version as `/docs/contract-signed.pdf`.
+>
+> _Model calls `interact` with action `save_as`, path `/docs/contract-signed.pdf`. Fails if the file exists; pass `overwrite: true` to replace. The target path must be under a mounted directory root (same write rules as the in-viewer save button)._
+
 ## Testing
 
 ### E2E Tests (Playwright)

examples/pdf-server/server.test.ts

@@ -1054,4 +1054,210 @@ describe("interact tool", () => {
       await server.close();
     });
   });
+
+  describe("save_as", () => {
+    // save_as is the FIRST interact action with a full request/reply unit
+    // test (get_text/get_screenshot use the same plumbing but are e2e-only).
+    // The roundtrip tests need: writable scope, kick off interact WITHOUT
+    // awaiting (it blocks until the view replies), poll → submit → await.
+
+    let tmpDir: string;
+    let savedDirs: Set<string>;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdf-saveas-"));
+      savedDirs = new Set(allowedLocalDirs);
+      allowedLocalDirs.add(tmpDir); // make tmpDir a directory root → writable
+    });
+
+    afterEach(() => {
+      allowedLocalDirs.clear();
+      for (const x of savedDirs) allowedLocalDirs.add(x);
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("rejects without `path`", async () => {
+      const { server, client } = await connect();
+      const r = await client.callTool({
+        name: "interact",
+        arguments: { viewUUID: "saveas-nopath", action: "save_as" },
+      });
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("save_as");
+      expect(firstText(r)).toContain("path");
+      await client.close();
+      await server.close();
+    });
+
+    it("rejects non-absolute path", async () => {
+      const { server, client } = await connect();
+      const r = await client.callTool({
+        name: "interact",
+        arguments: {
+          viewUUID: "saveas-rel",
+          action: "save_as",
+          path: "relative.pdf",
+        },
+      });
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("absolute");
+      await client.close();
+      await server.close();
+    });
+
+    it("rejects non-writable path", async () => {
+      const { server, client } = await connect();
+      // Path outside any directory root → not writable. Validation is sync,
+      // so nothing is enqueued and the queue stays empty.
+      const r = await client.callTool({
+        name: "interact",
+        arguments: {
+          viewUUID: "saveas-nowrite",
+          action: "save_as",
+          path: "/somewhere/else/out.pdf",
+        },
+      });
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("not under a mounted directory root");
+      await client.close();
+      await server.close();
+    });
+
+    it("rejects existing file when overwrite is false (default)", async () => {
+      const { server, client } = await connect();
+      const target = path.join(tmpDir, "exists.pdf");
+      fs.writeFileSync(target, "old contents");
+
+      const r = await client.callTool({
+        name: "interact",
+        arguments: {
+          viewUUID: "saveas-exists",
+          action: "save_as",
+          path: target,
+        },
+      });
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("already exists");
+      expect(firstText(r)).toContain("overwrite: true");
+      // Existence check is sync — nothing enqueued, file untouched.
+      expect(fs.readFileSync(target, "utf8")).toBe("old contents");
+      await client.close();
+      await server.close();
+    });
+
+    it("full roundtrip: enqueue → poll → submit → file written", async () => {
+      const { server, client } = await connect();
+      const uuid = "saveas-roundtrip";
+      const target = path.join(tmpDir, "out.pdf");
+      const pdfBytes = "%PDF-1.4\nfake-annotated-contents\n%%EOF";
+
+      // interact blocks in waitForSaveData until submit_save_data resolves it
+      const interactPromise = client.callTool({
+        name: "interact",
+        arguments: { viewUUID: uuid, action: "save_as", path: target },
+      });
+
+      // Viewer polls → receives the save_as command with a requestId
+      const cmds = await poll(client, uuid);
+      expect(cmds).toHaveLength(1);
+      expect(cmds[0].type).toBe("save_as");
+      const requestId = cmds[0].requestId as string;
+      expect(typeof requestId).toBe("string");
+
+      // Viewer submits bytes
+      const submit = await client.callTool({
+        name: "submit_save_data",
+        arguments: {
+          requestId,
+          data: Buffer.from(pdfBytes).toString("base64"),
+        },
+      });
+      expect(submit.isError).toBeFalsy();
+
+      // interact now unblocks with success
+      const r = await interactPromise;
+      expect(r.isError).toBeFalsy();
+      expect(firstText(r)).toContain("Saved");
+      expect(firstText(r)).toContain(target);
+      expect(fs.readFileSync(target, "utf8")).toBe(pdfBytes);
+
+      await client.close();
+      await server.close();
+    });
+
+    it("overwrite: true replaces an existing file", async () => {
+      const { server, client } = await connect();
+      const uuid = "saveas-overwrite";
+      const target = path.join(tmpDir, "replace.pdf");
+      fs.writeFileSync(target, "old contents");
+
+      const interactPromise = client.callTool({
+        name: "interact",
+        arguments: {
+          viewUUID: uuid,
+          action: "save_as",
+          path: target,
+          overwrite: true,
+        },
+      });
+
+      const cmds = await poll(client, uuid);
+      const requestId = cmds[0].requestId as string;
+      await client.callTool({
+        name: "submit_save_data",
+        arguments: {
+          requestId,
+          data: Buffer.from("%PDF-1.4\nnew").toString("base64"),
+        },
+      });
+
+      const r = await interactPromise;
+      expect(r.isError).toBeFalsy();
+      expect(fs.readFileSync(target, "utf8")).toBe("%PDF-1.4\nnew");
+
+      await client.close();
+      await server.close();
+    });
+
+    it("propagates viewer-reported errors to the model", async () => {
+      const { server, client } = await connect();
+      const uuid = "saveas-viewerr";
+      const target = path.join(tmpDir, "wontwrite.pdf");
+
+      const interactPromise = client.callTool({
+        name: "interact",
+        arguments: { viewUUID: uuid, action: "save_as", path: target },
+      });
+
+      const cmds = await poll(client, uuid);
+      // Viewer hit an error building bytes → reports it instead of timing out
+      await client.callTool({
+        name: "submit_save_data",
+        arguments: {
+          requestId: cmds[0].requestId as string,
+          error: "pdf-lib choked on a comb field",
+        },
+      });
+
+      const r = await interactPromise;
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("pdf-lib choked on a comb field");
+      expect(fs.existsSync(target)).toBe(false);
+
+      await client.close();
+      await server.close();
+    });
+
+    it("submit_save_data with unknown requestId returns isError", async () => {
+      const { server, client } = await connect();
+      const r = await client.callTool({
+        name: "submit_save_data",
+        arguments: { requestId: "never-created", data: "AAAA" },
+      });
+      expect(r.isError).toBe(true);
+      expect(firstText(r)).toContain("No pending request");
+      await client.close();
+      await server.close();
+    });
+  });
 });