mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents read Gmail, Calendar, Drive, Docs, Sheets and Slides through the built-in Google Workspace connection > - Paperclip now has its own REST-backed Google tools in `server/src/google-workspace-rest-tools/`. No service uses them yet > - That folder guessed a result size limit of 250,000 bytes. It applied the limit only to Drive, Docs, Sheets and Slides. Gmail and Calendar had no limit > - The guess was wrong in both directions. It refused documents that Paperclip can deliver, and the folder should not know Paperclip's limits > - This pull request makes the limit a number that the gateway gives. The folder applies it to every tool in all six services through one check. It also brings three Google planning docs up to date > - The benefit is that a REST result is refused only when the gateway would also refuse the same result from Google's own MCP server ## Linked Issues or Issue Description Refs #22027, #22028, #22029, #22026 **Is your feature request related to a problem?** The REST tools refused results over a size the folder chose itself (250,000 bytes). Paperclip can deliver larger results: the runner saves a large result as an artifact and gives the agent a pointer. Gmail and Calendar results had no limit at all. **Describe the solution you'd like** The gateway gives the limit. The folder applies the given number to the final serialized result of every tool, with one helper. A result over the limit is an error that says how to ask for less. It is never cut short. **Describe alternatives you've considered** A larger number chosen from the runner's 1 GiB capture limit. Google's own transfer limit (20 MB per response) and memory use make that a poor choice. Also, results would then differ between the REST path and Google's MCP path. ### Limits a tool result passes on the way to an agent | Point | Limit | What happens over it | | --- | --- | --- | | Google response read by `google-http.ts` | 20 MB (`MAX_RESPONSE_BYTES`) | Tool error. Nothing returned | | REST folder result (new) | the number the gateway passes: 999,885 bytes | Tool error with "read less" advice. The gateway returns `tool_error` (502) | | Gateway read of a remote MCP response (`MAX_REMOTE_MCP_RESPONSE_BYTES` in `tool-gateway.ts`) | 1,000,000 bytes per JSON body or event-stream message | `mcp_remote_response_too_large` (502). This is the "1,000,000 bytes are rejected" statement in `doc/prompt-injection-prevention.md`. It applies to the Google MCP path only; the REST path has no HTTP read | | Injection screening model check | 256 KiB model request | Not a delivery limit. A larger result is checked by the built-in patterns only | | Gateway HTTP route (`POST /tool-gateway/.../tools/call`) | none in Paperclip | `res.json(result)` | | Runner (`captureRunnerToolResult`) | 500,000 bytes (`RUNNER_TOOL_RESULT_MAX_BYTES`) | Saved as an artifact. The agent gets a pointer and reads it with `read_tool_result` | | Runner capture | 1 GiB (`RUNNER_API_RESPONSE_MAX_BYTES`) | `SemanticToolOutcomeUnknownError` | The gateway wraps the result as `{ content, data: { content, structuredContent, ... } }`, so the payload occurs again. Measured: a Gmail result of 676,459 bytes from the folder became 1,017,386 bytes delivered (ratio 1.50). The ratio cannot be more than 2. ### The budget `GOOGLE_WORKSPACE_REST_MAX_RESULT_BYTES` in `tool-gateway.ts` = `MAX_REMOTE_MCP_RESPONSE_BYTES` less the JSON-RPC envelope and event-stream framing (`event: message\ndata: {"jsonrpc":"2.0","id":"paperclip-tool-<uuid>-version","result":...}`) = **999,885 bytes**. A result that Google's MCP server could deliver through the gateway is also delivered over REST, and the reverse. With the wrapper, the largest delivered result is less than 2 MB. The runner saves it as an artifact (far below 1 GiB). So the folder never refuses a result that the runner can give as a pointer. Practical limits at that budget (plain ASCII; escaped and non-ASCII characters count more): | Tool | Largest content | | --- | --- | | Gmail `get_message` | about 500 KB plain body, or about 250 KB each for plain plus HTML | | Calendar `get_event` | about 500 KB description | | Drive `read_file_content` | about 500 KB text | | Drive `download_file_content` | about 375 KB file bytes | | Docs `read_doc` | about 240 KB document text | | Slides `read_presentation` | about 250 KB text | | Sheets `get_values` | about 500 KB cell text, at most 50,000 cells | ## What Changed - `tool.ts`: `defineTool` takes `whenTooLarge` advice per read tool (required for reads, refused for writes) and a `ToolLimits` argument. It measures the final `CallToolResult` once (`withinResultBudget`) and replaces an oversized result with a `too_large` tool error. `FALLBACK_MAX_RESULT_BYTES` (250,000) applies only when a direct caller gives no limit. - `callGoogleWorkspaceRestTool` and `createGoogleWorkspaceRestServer` take `maxResultBytes`. A value that is not a positive integer is refused before any request. - All 23 read tools state their advice: a smaller `pageSize` for list tools, `messageFormat` or `view` for Gmail, a narrower range for Sheets, `fields` for Slides. Write tools are not checked: a completed write is never reported as an error, so an agent is not led to repeat it. - Drive, Docs, Slides and Sheets no longer have their own byte checks (`boundedStructuredResult`, `boundedResult`, `sizedResult`, `MAX_CONTENT_BYTES` removed). Drive downloads stop reading at the given limit. The Sheets 50,000-cell limit stays. - Two Drive tool descriptions no longer state a fixed number. - Adapter `google-workspace-rest-dispatch.ts`: `maxResultBytes` is a required input and is passed through. - `tool-gateway.ts`: new `GOOGLE_WORKSPACE_REST_MAX_RESULT_BYTES`, passed on the REST branch. - Folder README: new "Result size" section with the limits and costs; old 250,000-byte text replaced. - Docs: `doc/memory/google-connector-memory.md`, the production checklist and the code-fix plan now list #22026 to #22029, the REST status (36 of 36, none switched on), the November 17 decisions, the known differences from Google's tools, open risks and next steps. ## Verification - `cd server && npx vitest run src/google-workspace-rest-tools` passes (53 files, 1,361 tests with the adapter test). - New `result-budget.test.ts`: for Gmail (read, list), Calendar (list, read), Drive, Docs, Slides and Sheets, a result just under a given budget is returned and one just over is refused with the tool's advice. Without a budget, the fallback applies; with a larger budget, the same result is returned. Drive downloads use the given cap. A Gmail list tells the caller to lower `pageSize`. A Gmail draft result over the budget is still returned, not an error. `defineTool` refuses a read tool without advice and a write tool with it. - `npx vitest run src/services/google-workspace-rest-dispatch.test.ts`: the adapter passes the gateway's number, and the folder applies exactly that number. - `npx vitest run src/__tests__/google-workspace-rest-transport.test.ts` (24 tests): with Gmail on REST, a 330 KB email passes the gateway with screening, is more than 500,000 bytes delivered, and `captureRunnerToolResult` turns it into a `read_tool_result` pointer. A 520 KB email is refused with `tool_error` and the advice, after one Google request. - `npx tsc --noEmit -p server/tsconfig.json`: no errors. - `pnpm verify --explain`: broader verification required (a doc under `doc/` is a global CI input). CI supplies that coverage. - Time per call: the check is one `JSON.stringify` of the result. About 5 µs for a 4 KB result, 18 µs for 42 KB, 0.24 ms for 700 KB. Drive, Docs, Sheets and Slides had the same pass before, so they add nothing. Gmail and Calendar add this one pass. ## Risks - Gmail and Calendar results now have a limit. Direct callers that pass no limit get the 250,000-byte fallback. The gateway always passes its number. - Drive, Docs, Slides and Sheets accept results up to about 4 times larger than before through the gateway. Large results reach agents as artifact pointers. - Error text for oversized results changed to one shared form. - No service is switched to REST, so users see no change today. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code with tool use (shell, file edits, GitHub CLI) and extended reasoning. ## 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>
86 lines
5.5 KiB
TypeScript
86 lines
5.5 KiB
TypeScript
import { GOOGLE_WORKSPACE_TOOL_TRANSPORT, googleWorkspaceServiceToolNames } from "@paperclipai/shared";
|
|
import { describe, expect, it, vi } from "vitest";
|
|
import {
|
|
callGoogleWorkspaceRest,
|
|
googleWorkspaceRestTransportGaps,
|
|
probeGoogleWorkspaceRest,
|
|
} from "./google-workspace-rest-dispatch.js";
|
|
|
|
describe("Google Workspace REST transport eligibility", () => {
|
|
it("switches no service to paperclip_rest unless the REST tools cover its whole allowlist", () => {
|
|
expect(googleWorkspaceRestTransportGaps()).toEqual([]);
|
|
});
|
|
|
|
it("finds Gmail and Calendar fully implemented and Chat not", () => {
|
|
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, gmail: "paperclip_rest", calendar: "paperclip_rest" })).toEqual([]);
|
|
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, chat: "paperclip_rest" }).map((gap) => gap.service)).toEqual(["chat"]);
|
|
});
|
|
|
|
it("names every missing tool of a service with no REST tools", () => {
|
|
expect(googleWorkspaceRestTransportGaps({ ...GOOGLE_WORKSPACE_TOOL_TRANSPORT, chat: "paperclip_rest" }))
|
|
.toEqual([{ service: "chat", missing: googleWorkspaceServiceToolNames("chat") }]);
|
|
});
|
|
});
|
|
|
|
describe("callGoogleWorkspaceRest", () => {
|
|
it("sends only the bearer token to Google and passes the gateway's fetch and signal", async () => {
|
|
const controller = new AbortController();
|
|
const fetch = vi.fn(async (_url: string, _init: RequestInit) => Response.json({ id: "draft1", message: { id: "m", threadId: "t" } }));
|
|
const outcome = await callGoogleWorkspaceRest({
|
|
service: "gmail", toolName: "create_draft", arguments: { subject: "Hi", body: "Hello" }, maxResultBytes: 1_000_000,
|
|
credentialHeaders: { authorization: "Bearer token-1", "x-paperclip-run": "run-1" }, fetch, signal: controller.signal,
|
|
});
|
|
expect(outcome).toMatchObject({ ok: true, result: { structuredContent: { id: "draft1", subject: "Hi" } } });
|
|
const init = fetch.mock.calls[0]![1];
|
|
expect(Object.fromEntries(new Headers(init.headers))).toMatchObject({ authorization: "Bearer token-1" });
|
|
expect(new Headers(init.headers).has("x-paperclip-run")).toBe(false);
|
|
controller.abort();
|
|
expect(init.signal?.aborted).toBe(true);
|
|
});
|
|
|
|
it("returns token problems as outcomes and leaves other failures as tool errors", async () => {
|
|
const answer = (status: number, body: unknown) => vi.fn(async () => Response.json(body, { status }));
|
|
const call = (fetch: ReturnType<typeof answer>, credentialHeaders: Record<string, string> = { Authorization: "Bearer t" }) =>
|
|
callGoogleWorkspaceRest({ service: "gmail", toolName: "get_message", arguments: { messageId: "m1" }, maxResultBytes: 1_000_000, credentialHeaders, fetch });
|
|
await expect(call(answer(401, {}))).resolves.toEqual({ ok: false, authFailure: "unauthenticated" });
|
|
await expect(call(answer(200, {}), {})).resolves.toEqual({ ok: false, authFailure: "unauthenticated" });
|
|
await expect(call(answer(403, { error: { errors: [{ reason: "insufficientPermissions" }] } })))
|
|
.resolves.toEqual({ ok: false, authFailure: "insufficient_scope" });
|
|
await expect(call(answer(404, { error: { code: 404 } }))).resolves.toMatchObject({ ok: true, result: { isError: true } });
|
|
});
|
|
|
|
it("passes the gateway's result budget to the REST tools, which enforce exactly that number", async () => {
|
|
const body = "a".repeat(30_000);
|
|
const message = { id: "m1", threadId: "t1", internalDate: "1763337600000",
|
|
payload: { mimeType: "text/plain", headers: [], body: { size: body.length, data: Buffer.from(body).toString("base64url") } } };
|
|
const call = (maxResultBytes: number) => callGoogleWorkspaceRest({
|
|
service: "gmail", toolName: "get_message", arguments: { messageId: "m1" }, maxResultBytes,
|
|
credentialHeaders: { Authorization: "Bearer t" }, fetch: vi.fn(async () => Response.json(message)),
|
|
});
|
|
const fits = await call(1_000_000);
|
|
expect(fits).toMatchObject({ ok: true, result: { structuredContent: { plaintextBody: body } } });
|
|
const bytes = Buffer.byteLength(JSON.stringify(fits.ok && fits.result), "utf8");
|
|
await expect(call(bytes)).resolves.toMatchObject({ ok: true, result: { structuredContent: { plaintextBody: body } } });
|
|
const over = await call(bytes - 1);
|
|
expect(over).toMatchObject({ ok: true, result: { isError: true } });
|
|
expect(JSON.stringify(over)).toContain(`more than the ${(bytes - 1).toLocaleString("en-US")} bytes this tool can return`);
|
|
});
|
|
|
|
it("refuses a service the REST tools do not implement", async () => {
|
|
await expect(callGoogleWorkspaceRest({ service: "chat", toolName: "send_message", arguments: {}, maxResultBytes: 1_000_000, credentialHeaders: {}, fetch: vi.fn() }))
|
|
.rejects.toThrow("no Paperclip REST tools");
|
|
});
|
|
});
|
|
|
|
describe("probeGoogleWorkspaceRest", () => {
|
|
it("reports a token problem separately from an unavailable service", async () => {
|
|
const probe = (status: number, body: unknown) => probeGoogleWorkspaceRest({
|
|
service: "gmail", credentialHeaders: { Authorization: "Bearer t" }, grantedScopes: ["https://www.googleapis.com/auth/gmail.readonly"],
|
|
fetch: vi.fn(async () => Response.json(body, { status })),
|
|
});
|
|
await expect(probe(200, { emailAddress: "a@example.test" })).resolves.toEqual({ ok: true });
|
|
await expect(probe(401, {})).resolves.toMatchObject({ ok: false, authFailure: "unauthenticated" });
|
|
await expect(probe(403, { error: { errors: [{ reason: "accessNotConfigured" }] } })).resolves.toMatchObject({ ok: false, authFailure: null });
|
|
});
|
|
});
|