mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 03:29:18 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Google Workspace connector gives agents Google tools through the tool gateway > - Google's hosted Workspace MCP servers are a Developer Preview, so Paperclip launches on its own tools over Google's REST APIs, in `server/src/google-workspace-rest-tools/` > - Gmail and Calendar are done there; Docs and Slides have no tools yet > - This pull request adds `read_doc`, `update_doc`, `read_presentation` and `update_presentation` with the same names and inputs as Google's MCP tools > - The benefit is that the Docs and Slides services can switch to `paperclip_rest` once their API is enabled, and reviewers see a full document in Paperclip ## Linked Issues or Issue Description **Subsystem affected** Google Workspace REST tool set (`server/src/google-workspace-rest-tools/`), Docs and Slides services. **Problem or motivation** The REST tool set has no Docs or Slides tools. The allowlist (`toolScopes.docs`, `toolScopes.slides`) names two tools for each service. A service cannot switch to `paperclip_rest` until all of its allowlisted tools exist. **Proposed solution** Add the four tools in new `docs/` and `slides/` folders. Each tool makes exactly one REST call. The read tools return the whole file as Markdown-style text plus an index structure for edits. The update tools post `batchUpdate` requests in order and require the revision ID that the caller read. **Alternatives considered** Return the raw `documents.get` JSON. It is 10 to 20 times larger than the text, so ordinary documents go over the result size limit, and it is hard to compare with Google Docs. Reorder edit requests by index. That changes what dependent requests do, and Google's tool does not do it. Refs #22000, #22014, #22017 ## What Changed - `docs/`: `read_doc` (`documents.get` with `includeTabsContent=true`) and `update_doc` (`documents.batchUpdate`), a renderer for every tab, child tab, heading, list (real numbering), table, link, header, footer, footnote, chip, suggestion and comment, and an index structure where each paragraph's `text.length` equals `endIndex - startIndex`. - `slides/`: `read_presentation` (`presentations.get`; with `fields` it returns Google's resource as is) and `update_presentation` (`presentations.batchUpdate`), a renderer for every slide's text, tables, groups, media and speaker notes. - `documents-shared.ts`: the 250,000-byte limit on the final serialized result (an error, never a cut-short result), the revision-conflict error, comment rendering, and argument checks. - Update tools require `writeControl.requiredRevisionId` and refuse `targetRevisionId`. A revision conflict returns "nothing was changed; read it again". Writes are never retried. - `google-http.ts`: allows `docs.googleapis.com` only under `/v1/documents/` and `slides.googleapis.com` only under `/v1/presentations/`. - `tools.ts`, `probe.ts`: register the services. Docs and Slides have no network probe, because every read needs a file ID. - Update tools accept only a closed list of batch request kinds (`docs/request-kinds.ts`, `slides/request-kinds.ts`). Kinds and forms that read another file are refused by name: `insertRichLink`, the Sheets chart kinds, `importSlides`, `createAudio`, Drive videos, and images from Drive or Docs links. Unknown kinds are refused too. - `read_doc` always requests `SUGGESTIONS_INLINE` and falls back to an explicit `PREVIEW_WITHOUT_SUGGESTIONS` read for view-only users; the result says which view it used. - Tables with merged cells are placed on the full grid; covered cells read `(merged left)` or `(merged up)`. - Revision conflicts are recognized from Google's `error.status` and `error.details` first, with the message as a fallback. - Annotations: `update_doc` and `update_presentation` are destructive and not idempotent. **Calendar `update_event` is now also marked destructive** (it overwrites fields, removes attendees and replaces reminders). Google's references mark both non-destructive; the README records this. - `README.md`: endpoint and scope table with Google's documentation links, the result format, what cannot be shown, update order and revision rules, and every difference from Google's tools. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools`: 33 files, 573 tests pass (169 new in `docs/` and `slides/`, plus host, probe and allowlist tests). - `cd server && pnpm typecheck`: passes. - `pnpm verify`: exit 2 (README is a broad input), so required CI supplies broad coverage. - `src/services/google-workspace-rest-dispatch.test.ts` fails the same way on `master` (it still expects Gmail to be incomplete after #22014). This PR does not touch it. ## Risks - Low risk. Nothing calls these tools until the Docs or Slides transport is set to `paperclip_rest`; both stay `google_mcp`. - The inner format of `content` differs from Google's tool, which Google does not publish. The README lists this. - Revision-conflict detection matches Google's 400 message on "revision". Any 400 rejects the whole batch, so nothing changes in either case. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
153 lines
10 KiB
TypeScript
153 lines
10 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import { fakeGoogle, json } from "../fixtures/fake-google.js";
|
|
import { createGoogleHttp } from "../google-http.js";
|
|
import { updateDoc, updateDocRequest } from "./update-doc.js";
|
|
|
|
const REVISION = { requiredRevisionId: "rev-7" };
|
|
|
|
type Edit = { insertText?: { text: string; location: { index: number } }; deleteContentRange?: { range: { startIndex: number; endIndex: number } } };
|
|
|
|
function applyInOrder(body: string, requests: Edit[]): string {
|
|
let current = body;
|
|
for (const request of requests) {
|
|
if (request.insertText) {
|
|
const at = request.insertText.location.index - 1;
|
|
current = current.slice(0, at) + request.insertText.text + current.slice(at);
|
|
} else if (request.deleteContentRange) {
|
|
const { startIndex, endIndex } = request.deleteContentRange.range;
|
|
current = current.slice(0, startIndex - 1) + current.slice(endIndex - 1);
|
|
}
|
|
}
|
|
return current;
|
|
}
|
|
|
|
function body(call: { body: unknown }): { requests: Edit[]; writeControl: Record<string, unknown> } {
|
|
return call.body as { requests: Edit[]; writeControl: Record<string, unknown> };
|
|
}
|
|
|
|
describe("update_doc request", () => {
|
|
it("posts the requests unchanged and in order, with the revision the caller read", () => {
|
|
const requests = [
|
|
{ insertText: { text: "!", location: { index: 12 } } },
|
|
{ updateTextStyle: { range: { startIndex: 1, endIndex: 6 }, textStyle: { bold: true }, fields: "bold" } },
|
|
{ replaceAllText: { containsText: { text: "draft", matchCase: true }, replaceText: "final" } },
|
|
];
|
|
expect(updateDocRequest({ documentId: "doc-1", requests, writeControl: REVISION })).toEqual({
|
|
method: "POST",
|
|
host: "docs.googleapis.com",
|
|
path: "/v1/documents/doc-1:batchUpdate",
|
|
body: { requests, writeControl: { requiredRevisionId: "rev-7" } },
|
|
});
|
|
});
|
|
|
|
it.each(["EDIT", "SUGGEST", "WRITE_MODE_UNSPECIFIED"] as const)("passes writeMode %s through", (writeMode) => {
|
|
const request = updateDocRequest({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 1 } } }], writeControl: { ...REVISION, writeMode } });
|
|
expect((request.body as { writeControl: unknown }).writeControl).toEqual({ requiredRevisionId: "rev-7", writeMode });
|
|
});
|
|
|
|
it.each([
|
|
["no writeControl", undefined, /writeControl\.requiredRevisionId is required/],
|
|
["an empty writeControl", {}, /writeControl\.requiredRevisionId is required/],
|
|
["only a write mode", { writeMode: "EDIT" as const }, /writeControl\.requiredRevisionId is required/],
|
|
["targetRevisionId", { targetRevisionId: "rev-7" }, /targetRevisionId is not supported/],
|
|
["both revision fields", { requiredRevisionId: "rev-7", targetRevisionId: "rev-7" }, /targetRevisionId is not supported/],
|
|
])("refuses %s", (_name, writeControl, message) => {
|
|
expect(() => updateDocRequest({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 1 } } }], writeControl })).toThrow(message);
|
|
});
|
|
});
|
|
|
|
describe("update_doc edit order", () => {
|
|
const read = "Hello world.";
|
|
const fromOneRead: Edit[] = [
|
|
{ insertText: { text: " and goodbye", location: { index: 12 } } },
|
|
{ deleteContentRange: { range: { startIndex: 7, endIndex: 8 } } },
|
|
{ insertText: { text: "Well, ", location: { index: 1 } } },
|
|
];
|
|
|
|
it("applies edits made from one read correctly when they go from the highest index to the lowest, as the description says", () => {
|
|
expect(applyInOrder(read, fromOneRead)).toBe("Well, Hello orld and goodbye.");
|
|
expect(applyInOrder(read, [...fromOneRead].reverse())).not.toBe("Well, Hello orld and goodbye.");
|
|
});
|
|
|
|
it("sends several edits in one call, exactly in the caller's order, in a single request", async () => {
|
|
const { fetch, calls } = fakeGoogle(() => json({ documentId: "d", replies: [{}, {}, {}], writeControl: { requiredRevisionId: "rev-8" } }));
|
|
const result = await updateDoc.call({ documentId: "d", requests: fromOneRead, writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect(calls).toHaveLength(1);
|
|
expect(body(calls[0]!).requests).toEqual(fromOneRead);
|
|
expect(applyInOrder(read, body(calls[0]!).requests)).toBe("Well, Hello orld and goodbye.");
|
|
expect(result.structuredContent).toEqual({ replies: [{}, {}, {}], writeControl: { requiredRevisionId: "rev-8" } });
|
|
});
|
|
|
|
it("keeps dependent edits in order: an insertion and then styling of the inserted text", async () => {
|
|
const requests = [
|
|
{ insertText: { text: "Title\n", location: { index: 1 } } },
|
|
{ updateParagraphStyle: { range: { startIndex: 1, endIndex: 7 }, paragraphStyle: { namedStyleType: "HEADING_1" }, fields: "namedStyleType" } },
|
|
];
|
|
const { fetch, calls } = fakeGoogle(() => json({ replies: [{}, {}], writeControl: { requiredRevisionId: "rev-8" } }));
|
|
await updateDoc.call({ documentId: "d", requests, writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect(body(calls[0]!).requests.map((request) => Object.keys(request)[0])).toEqual(["insertText", "updateParagraphStyle"]);
|
|
});
|
|
});
|
|
|
|
describe("update_doc tool", () => {
|
|
it("returns a clear error and changes nothing when the document changed since it was read", async () => {
|
|
const { fetch, calls } = fakeGoogle(() => json({ error: { code: 400, status: "INVALID_ARGUMENT", message: "The required revision ID 'rev-7' does not match the latest revision." } }, 400));
|
|
const result = await updateDoc.call({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 1 } } }], writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect(calls).toHaveLength(1);
|
|
expect(result).toEqual({
|
|
isError: true,
|
|
content: [{ type: "text", text: "The document is no longer at the revision you read (or that revision ID is not valid), so nothing was changed. Read it again with read_doc and retry with its new revisionId." }],
|
|
});
|
|
});
|
|
|
|
it.each([
|
|
["FAILED_PRECONDITION", { code: 400, status: "FAILED_PRECONDITION", message: "Precondition check failed." }, 400],
|
|
["a revision reason in the details", { code: 400, status: "INVALID_ARGUMENT", message: "Request failed.", details: [{ "@type": "type.googleapis.com/google.rpc.ErrorInfo", reason: "REVISION_MISMATCH" }] }, 400],
|
|
["ABORTED on 409", { code: 409, status: "ABORTED", message: "Aborted." }, 409],
|
|
])("recognizes a conflict from Google's structured %s", async (_name, error, status) => {
|
|
const { fetch } = fakeGoogle(() => json({ error }, status));
|
|
const result = await updateDoc.call({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 1 } } }], writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect((result.content[0] as { text: string }).text).toMatch(/^The document is no longer at the revision you read/);
|
|
});
|
|
|
|
it("does not call a 400 that only mentions revisions a conflict", async () => {
|
|
const { fetch } = fakeGoogle(() => json({ error: { code: 400, status: "INVALID_ARGUMENT", message: "Invalid requests[0].updateDocumentStyle: revisions of the page size are not allowed." } }, 400));
|
|
const result = await updateDoc.call({ documentId: "d", requests: [{ updateDocumentStyle: {} }], writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect((result.content[0] as { text: string }).text).toBe("Invalid requests[0].updateDocumentStyle: revisions of the page size are not allowed.");
|
|
});
|
|
|
|
it("passes other rejections through with Google's message", async () => {
|
|
const { fetch } = fakeGoogle(() => json({ error: { code: 400, message: "Invalid requests[0].insertText: Index 99 must be less than the end index of the referenced segment, 12." } }, 400));
|
|
const result = await updateDoc.call({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 99 } } }], writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch }));
|
|
expect((result.content[0] as { text: string }).text).toBe("Invalid requests[0].insertText: Index 99 must be less than the end index of the referenced segment, 12.");
|
|
});
|
|
|
|
it.each([
|
|
["a server error", () => json({ error: { code: 503 } }, 503)],
|
|
["a dropped connection", () => { throw new TypeError("fetch failed"); }],
|
|
])("never retries the write after %s and warns that it may have happened", async (_name, answer) => {
|
|
const { fetch, calls } = fakeGoogle(answer);
|
|
const result = await updateDoc.call({ documentId: "d", requests: [{ insertText: { text: "a", location: { index: 1 } } }], writeControl: REVISION }, createGoogleHttp({ accessToken: "t", fetch, retryDelayMs: 0 }));
|
|
expect(calls).toHaveLength(1);
|
|
expect(result.isError).toBe(true);
|
|
expect((result.content[0] as { text: string }).text).toMatch(/may or may not have been made/);
|
|
});
|
|
|
|
it.each([
|
|
["no requests", { documentId: "d", writeControl: REVISION }],
|
|
["an empty request list", { documentId: "d", requests: [], writeControl: REVISION }],
|
|
["a request with two kinds", { documentId: "d", requests: [{ insertText: {}, deleteContentRange: {} }], writeControl: REVISION }],
|
|
["a request with no kind", { documentId: "d", requests: [{}], writeControl: REVISION }],
|
|
["a request that is not an object", { documentId: "d", requests: ["insertText"], writeControl: REVISION }],
|
|
["a bad document ID", { documentId: "../d", requests: [{ insertText: {} }], writeControl: REVISION }],
|
|
["no revision", { documentId: "d", requests: [{ insertText: {} }] }],
|
|
["a target revision", { documentId: "d", requests: [{ insertText: {} }], writeControl: { targetRevisionId: "r" } }],
|
|
["an unknown write mode", { documentId: "d", requests: [{ insertText: {} }], writeControl: { ...REVISION, writeMode: "FORCE" } }],
|
|
["too many requests", { documentId: "d", requests: Array.from({ length: 501 }, () => ({ insertText: {} })), writeControl: REVISION }],
|
|
])("sends nothing for %s", async (_name, input) => {
|
|
const { fetch, calls } = fakeGoogle(() => json({}));
|
|
expect((await updateDoc.call(input, createGoogleHttp({ accessToken: "t", fetch }))).isError).toBe(true);
|
|
expect(calls).toHaveLength(0);
|
|
});
|
|
});
|