Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { accessFor } from "../src/plugins/access";
import { catalogueEntry } from "../src/plugins/catalogue";
import { callTool, listTools } from "../src/plugins/google-drive-rest";
import {
MAX_RESULT_CHARS,
type McpTool,
callTool as mcpCallTool,
} from "../src/plugins/mcp";
import { transportFor } from "../src/plugins/transport";
/**
* The Drive REST adapter, asserted without Google.
*
* `fetch` is replaced rather than a server started, because what is under test is the translation:
* which URL a tool becomes, what a refusal reads as, and that an empty listing says so in words.
* None of that needs a network, and all of it is what breaks when Drive's shapes are misremembered.
*/
const connection = {
url: "https://www.googleapis.com/drive/v3",
token: "test-token",
};
const realFetch = globalThis.fetch;
/**
* Anything this file did not stub is an escape, and an escape fails the test that let it out.
*
* Ordering used to matter here: a test awaited `listTools` before installing its stub, and got away
* with it only because this adapter's list happens to be a local constant. Reordering that one call
* fixes it once; a call made before its stub would go out to Google again the moment any of these
* functions grows a request. So `fetch` is armed to refuse instead, before every test.
*
* Refusing is not enough on its own — the adapter catches its own transport errors and reports them
* as a sentence, which would turn an escape into a plausible-looking failure message. The escapes
* are therefore recorded and the ledger asserted empty afterwards, so one is named as what it is
* rather than read as Drive being unreachable.
*/
let escapedToNetwork: string[] = [];
beforeEach(() => {
escapedToNetwork = [];
// Annotated as answering, though it never does: a function that only throws infers as returning
// `never`, which does not overlap `fetch` enough for the cast the stub below makes freely.
globalThis.fetch = (async (input: string | URL): Promise<Response> => {
escapedToNetwork.push(String(input));
throw new Error(`unstubbed fetch escaped to the network: ${String(input)}`);
}) as typeof fetch;
});
afterEach(() => {
globalThis.fetch = realFetch;
expect(escapedToNetwork).toEqual([]);
});
/** Records what was requested and answers with a fixed body. */
function stubFetch(
body: unknown,
init: { status?: number; text?: string } = {},
) {
const calls: { url: string; authorization: string | null }[] = [];
globalThis.fetch = (async (input: string | URL, options?: RequestInit) => {
calls.push({
url: String(input),
authorization: new Headers(options?.headers).get("authorization") ?? null,
});
const payload = init.text ?? JSON.stringify(body);
return new Response(payload, {
status: init.status ?? 200,
headers: { "content-type": "application/json" },
});
}) as typeof fetch;
return calls;
}
/**
* Arguments a tool will accept, read off the tool's own schema rather than written out here.
*
* A tool added to the adapter with a required argument this file has never heard of still gets
* called with one, so the coverage below cannot quietly stop covering it.
*/
function argsFor(tool: McpTool): Record<string, unknown> {
const required: unknown[] = Array.isArray(tool.inputSchema.required)
? tool.inputSchema.required
: [];
return Object.fromEntries(required.map((name) => [String(name), "given"]));
}
/**
* A body that answers every advertised tool: a listing for the searches, a text file for the reads.
*/
const anyToolsBody = {
files: [],
id: "given",
name: "notes.txt",
mimeType: "text/plain",
};
describe("the adapter is the transport the catalogue asks for", () => {
test("the Drive entry resolves to this adapter, not to MCP", () => {
const entry = catalogueEntry("google-drive");
expect(entry?.transport).toBe("google-drive-rest");
// Identity, not shape: proves the registry wired this module rather than something MCP-shaped.
expect(
transportFor(
accessFor(
{ provenance: "first-party", url: "https://www.googleapis.com" },
entry,
).transport,
).callTool,
).toBe(callTool);
});
test("a server with no catalogue entry falls back to MCP", () => {
// A custom server an administrator added by URL is somebody else's MCP endpoint by definition.
// Composed through `accessFor`, which is where the absent-entry fallback now lives — and asserted
// as MCP rather than as "not Drive", which any wrongly resolved kind would also satisfy.
expect(
transportFor(
accessFor(
{ provenance: "custom", url: "https://mcp.example.com/mcp" },
null,
).transport,
).callTool,
).toBe(mcpCallTool);
});
test("every advertised tool is one the dispatcher handles", async () => {
// Stubbed before the first call of any kind, so nothing here depends on `listTools` staying
// local; the guard above turns a reintroduction of that order into a named failure.
stubFetch(anyToolsBody);
const tools = await listTools(connection);
expect(tools.length).toBeGreaterThan(0);
for (const tool of tools) {
/*
* Called with what the tool asks for, and asserted on what a handled tool DOES: it reaches
* Drive and answers. The dispatcher's fallthrough is the failure being excluded, and it is
* excluded by never making a request — which stays true however that refusal is worded, and
* which a reworded, mistyped or entirely different error cannot satisfy.
*/
const calls = stubFetch(anyToolsBody);
const result = await callTool(connection, tool.name, argsFor(tool));
expect(calls.length).toBeGreaterThan(0);
expect(result.isError).toBe(false);
}
});
test("a tool the dispatcher does not implement is refused without a request", async () => {
// The other half of the pair: the fallthrough exists, and is what a tool NOT in the list gets.
const calls = stubFetch(anyToolsBody);
const result = await callTool(connection, "delete_everything", {});
expect(result.isError).toBe(true);
expect(calls).toHaveLength(0);
});
});
/*
* Drive is `user-oauth`, so the store refuses a call with nobody's credential long before this
* module is reached and the adapter's own check is the second lock. It is asserted anyway: it is
* the difference between a sentence saying so and a request to Google carrying `Bearer undefined`,
* which Drive answers with a 401 whose meaning is a great deal less obvious.
*/
describe("a call with no credential never leaves the process", () => {
const withoutToken = { url: connection.url };
test("every advertised tool refuses, and none of them requests anything", async () => {
stubFetch(anyToolsBody);
const tools = await listTools(withoutToken);
expect(tools.length).toBeGreaterThan(0);
for (const tool of tools) {
const calls = stubFetch(anyToolsBody);
const result = await callTool(withoutToken, tool.name, argsFor(tool));
// Silence first, and asserted as silence rather than as wording: nothing was requested, so
// no `Bearer undefined` went to Google to come back as a 401 about the wrong thing.
expect(calls).toHaveLength(0);
expect(result.isError).toBe(true);
}
});
test("listing what the adapter offers asks nobody, so it needs nothing", async () => {
/*
* Two properties in one call, and the second is why this test is left unstubbed. The gate that
* once stood here made connecting Drive a four-stop journey, so a tokenless listing has to
* answer in full — and the reason it can is that it asks nobody, which the armed `fetch` above
* is what proves. A `listTools` that grew a request would fail here by name.
*/
expect(await listTools(withoutToken)).toEqual(await listTools(connection));
expect(escapedToNetwork).toEqual([]);
});
});
describe("a search becomes the right Drive request", () => {
test("the query is sent as a Drive q clause, with the caller's token", async () => {
const calls = stubFetch({ files: [] });
await callTool(connection, "search_files", { query: "roadmap" });
expect(calls).toHaveLength(1);
const url = new URL(calls[0].url);
expect(url.origin + url.pathname).toBe(
"https://www.googleapis.com/drive/v3/files",
);
expect(url.searchParams.get("q")).toBe(
"(name contains 'roadmap' or fullText contains 'roadmap') and trashed = false",
);
expect(calls[0].authorization).toBe("Bearer test-token");
});
/*
* THE INJECTION CASE. Drive's `q` syntax delimits with single quotes, so an apostrophe in a search
* term would close the clause early — turning a search for somebody's file into a different query
* than the one asked for, or a syntax error. Escaped, a term is only ever a term.
*/
test("an apostrophe in the query cannot break out of the clause", async () => {
const calls = stubFetch({ files: [] });
await callTool(connection, "search_files", { query: "don't ship" });
const q = new URL(calls[0].url).searchParams.get("q");
expect(q).toBe(
"(name contains 'don\\'t ship' or fullText contains 'don\\'t ship') and trashed = false",
);
});
/*
* `files.list` returns trashed files unless the query excludes them, so a document somebody had
* thrown away came back as a recent file, or as a match above, with nothing in its line to say it
* was in the trash. Both listings ask Drive to leave the trash out.
*/
test("recent files are ordered by Drive, and filtered only by the trash", async () => {
const calls = stubFetch({ files: [] });
await callTool(connection, "list_recent_files", {});
const url = new URL(calls[0].url);
expect(url.searchParams.get("orderBy")).toBe("modifiedTime desc");
expect(url.searchParams.get("q")).toBe("trashed = false");
});
test("a search with nothing to search for is refused before the network", async () => {
const calls = stubFetch({ files: [] });
const result = await callTool(connection, "search_files", {});
expect(result.isError).toBe(true);
expect(calls).toHaveLength(0);
});
});
describe("what a model is told", () => {
test("a match is named, with the id it needs to read it", async () => {
stubFetch({
files: [
{
id: "abc123",
name: "Roadmap",
mimeType: "application/vnd.google-apps.document",
modifiedTime: "2026-08-21T10:00:00Z",
webViewLink: "https://docs.google.com/document/d/abc123",
},
],
});
const result = await callTool(connection, "search_files", {
query: "roadmap",
});
expect(result.isError).toBe(false);
expect(result.text).toContain("Roadmap");
// Every other tool here takes an id, so a result without one is a dead end.
expect(result.text).toContain("abc123");
expect(result.text).toContain("https://docs.google.com/document/d/abc123");
});
/*
* The empty case, stated in words rather than returned as an empty string. An empty result reads to
* a model as "the tool had nothing to say" and gets filled in from memory, which for a knowledge
* connector is the exact failure the whole lane exists to prevent.
*/
test("nothing found says so, and is not an error", async () => {
stubFetch({ files: [] });
const result = await callTool(connection, "search_files", {
query: "nothing matches this",
});
expect(result.isError).toBe(false);
expect(result.text).toContain("Nothing was found");
});
test("Google's own refusal is passed through, not replaced", async () => {
stubFetch(
{},
{
status: 403,
text: JSON.stringify({
error: { message: "Google Drive API has not been used in project 1" },
}),
},
);
const result = await callTool(connection, "search_files", { query: "x" });
expect(result.isError).toBe(true);
// The sentence naming what to fix, which is the whole reason the body is kept.
expect(result.text).toContain("has not been used in project 1");
expect(result.text).toContain("403");
});
});
describe("reading a file asks Drive what it is first", () => {
test("a Google Doc is exported as text, never downloaded", async () => {
const calls = stubFetch({
id: "doc1",
name: "Notes",
mimeType: "application/vnd.google-apps.document",
});
await callTool(connection, "read_file_content", { fileId: "doc1" });
expect(calls).toHaveLength(2);
// `alt=media` refuses an editor file outright, so the export path is not an optimisation.
expect(calls[1].url).toContain("/files/doc1/export");
expect(new URL(calls[1].url).searchParams.get("mimeType")).toBe(
"text/plain",
);
});
test("an ordinary text file is downloaded", async () => {
const calls = stubFetch({
id: "txt1",
name: "notes.txt",
mimeType: "text/plain",
});
await callTool(connection, "read_file_content", { fileId: "txt1" });
expect(new URL(calls[1].url).searchParams.get("alt")).toBe("media");
expect(calls[1].url).not.toContain("/export");
});
/*
* A PDF is declined by name rather than decoded and hoped for.
*
* `response.text()` on binary produces thousands of replacement characters, and that goes straight
* into a model's context: it costs the tokens of the real document, says nothing, and looks enough
* like content that the model will try to summarise it. The assertion that matters is the second
* one — the download is never even attempted, so the bytes never exist to be mangled.
*/
test("a binary file is declined instead of being read as text", async () => {
const calls = stubFetch({
id: "pdf1",
name: "Contract.pdf",
mimeType: "application/pdf",
});
const result = await callTool(connection, "read_file_content", {
fileId: "pdf1",
});
expect(result.isError).toBe(true);
expect(result.text).toContain("application/pdf");
// One call: the metadata lookup. No download followed it.
expect(calls).toHaveLength(1);
});
/*
* A type Google never defined is declined like any other unreadable one.
*
* Whoever uploaded the file chose the type string, so the export table is asked a question by
* somebody outside this deployment. Looked up in a plain object, `toString` is answered with
* `Object.prototype.toString` — truthy, so the file is treated as an exportable editor format:
* the refusal above is skipped and `?mimeType=function toString() { [native code] }` is sent to
* Google in its place.
*/
test("a made-up type borrowed from Object.prototype is not an exportable format", async () => {
for (const mimeType of ["toString", "constructor", "valueOf"]) {
const calls = stubFetch({ id: "odd1", name: "Odd", mimeType });
const result = await callTool(connection, "read_file_content", {
fileId: "odd1",
});
expect(result.isError).toBe(true);
expect(result.text).toContain(mimeType);
// One call: the metadata lookup. No export followed it.
expect(calls).toHaveLength(1);
}
});
});
/*
* Drive's search and recent lists return shortcuts as ordinary hits. Reading one by that id used
* to be refused as a binary `application/vnd.google-apps.shortcut`, so a document the person could
* open — and that search had just named — could not be read.
*/
describe("a shortcut is read as the file it points at", () => {
test("a shortcut to a Google Doc is exported from the target", async () => {
const calls: string[] = [];
let served = 0;
globalThis.fetch = (async (input: string | URL) => {
const url = String(input);
calls.push(url);
served += 1;
if (served === 1) {
return new Response(
JSON.stringify({
id: "shortcut1",
name: "Notes",
mimeType: "application/vnd.google-apps.shortcut",
shortcutDetails: {
targetId: "doc1",
targetMimeType: "application/vnd.google-apps.document",
},
}),
{ headers: { "content-type": "application/json" } },
);
}
if (served === 2) {
return new Response(
JSON.stringify({
id: "doc1",
name: "Notes",
mimeType: "application/vnd.google-apps.document",
}),
{ headers: { "content-type": "application/json" } },
);
}
return new Response("the document body", {
headers: { "content-type": "text/plain" },
});
}) as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "shortcut1",
});
expect(result.isError).toBe(false);
expect(result.text).toContain("the document body");
expect(calls).toHaveLength(3);
expect(calls[1]).toContain("/files/doc1?");
expect(calls[2]).toContain("/files/doc1/export");
expect(calls[2]).not.toContain("/files/shortcut1/");
});
test("a shortcut to a text file is downloaded from the target", async () => {
const calls: string[] = [];
let served = 0;
globalThis.fetch = (async (input: string | URL) => {
const url = String(input);
calls.push(url);
served += 1;
if (served === 1) {
return new Response(
JSON.stringify({
id: "shortcut2",
name: "notes.txt",
mimeType: "application/vnd.google-apps.shortcut",
shortcutDetails: {
targetId: "txt1",
targetMimeType: "text/plain",
},
}),
{ headers: { "content-type": "application/json" } },
);
}
if (served === 2) {
return new Response(
JSON.stringify({
id: "txt1",
name: "notes.txt",
mimeType: "text/plain",
}),
{ headers: { "content-type": "application/json" } },
);
}
return new Response("plain notes", {
headers: { "content-type": "text/plain" },
});
}) as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "shortcut2",
});
expect(result.isError).toBe(false);
expect(result.text).toContain("plain notes");
expect(new URL(calls[2]).searchParams.get("alt")).toBe("media");
expect(calls[2]).toContain("/files/txt1?");
expect(calls[2]).not.toContain("/export");
});
test("a shortcut that names no file is refused without a second request", async () => {
const calls = stubFetch({
id: "shortcut3",
name: "Broken",
mimeType: "application/vnd.google-apps.shortcut",
shortcutDetails: {},
});
const result = await callTool(connection, "read_file_content", {
fileId: "shortcut3",
});
expect(result.isError).toBe(true);
expect(result.text.toLowerCase()).toContain("shortcut");
expect(calls).toHaveLength(1);
});
test("a shortcut to a PDF is declined as a PDF, and the PDF is not downloaded", async () => {
const calls: string[] = [];
let served = 0;
globalThis.fetch = (async (input: string | URL) => {
calls.push(String(input));
served += 1;
return new Response(
JSON.stringify(
served === 1
? {
id: "shortcut4",
name: "Contract",
mimeType: "application/vnd.google-apps.shortcut",
shortcutDetails: {
targetId: "pdf1",
targetMimeType: "application/pdf",
},
}
: {
id: "pdf1",
name: "Contract.pdf",
mimeType: "application/pdf",
},
),
{ headers: { "content-type": "application/json" } },
);
}) as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "shortcut4",
});
expect(result.isError).toBe(true);
expect(result.text).toContain("application/pdf");
expect(calls).toHaveLength(2);
});
});
describe("reading a file asks Drive what it is first", () => {
test("a file id is required, and no request is made without one", async () => {
const calls = stubFetch({});
const result = await callTool(connection, "read_file_content", {});
expect(result.isError).toBe(true);
expect(calls).toHaveLength(0);
});
test("a file too long for one result is cut between characters, never through one", async () => {
// The name and a blank line lead the result, so the filler is sized to put an emoji's high half
// on the last code unit the limit keeps.
const heading = "notes.txt\n\n";
const filler = "a".repeat(MAX_RESULT_CHARS - 1 - heading.length);
let served = 0;
globalThis.fetch = (async () => {
served += 1;
return served === 1
? new Response(
JSON.stringify({
id: "txt1",
name: "notes.txt",
mimeType: "text/plain",
}),
{ headers: { "content-type": "application/json" } },
)
: new Response(`${filler}😀tail`, {
headers: { "content-type": "text/plain" },
});
}) as unknown as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "txt1",
});
expect(result.truncated).toBe(true);
expect(result.text.split("\n\n[truncated")[0]).toBe(`${heading}${filler}`);
});
/*
* Only the opening of a long file is shown, so only the opening is read.
*
* The whole download used to be held as one string before all but the first MAX_RESULT_CHARS
* characters were dropped: a 200 MB log took the process up by more than 600 MB to return 20,000
* characters. The body here counts what is pulled from it, so reading it to the end fails.
*/
test("a file far longer than one result is not downloaded whole", async () => {
const line = new TextEncoder().encode(`${"x".repeat(1023)}\n`);
const size = 16 * 1024 * 1024;
let pulled = 0;
let served = 0;
globalThis.fetch = (async () => {
served += 1;
if (served === 1) {
return new Response(
JSON.stringify({
id: "log1",
name: "big.log",
mimeType: "text/plain",
}),
{ headers: { "content-type": "application/json" } },
);
}
const body = new ReadableStream<Uint8Array>({
pull(controller) {
if (pulled >= size) {
controller.close();
return;
}
pulled += line.length;
controller.enqueue(line);
},
});
return new Response(body, { headers: { "content-type": "text/plain" } });
}) as unknown as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "log1",
});
expect(pulled).toBeLessThan(size / 16);
expect(result.isError).toBe(false);
expect(result.truncated).toBe(true);
expect(result.text.startsWith(`big.log\n\n${"x".repeat(1023)}\n`)).toBe(
true,
);
// The file's length is not known, so none is claimed.
expect(
result.text.endsWith("\n\n[truncated: the file is longer than this]"),
).toBe(true);
});
test("a download with no body at all reads as an empty file", async () => {
let served = 0;
globalThis.fetch = (async () => {
served += 1;
return served === 1
? new Response(
JSON.stringify({
id: "empty1",
name: "empty.txt",
mimeType: "text/plain",
}),
{ headers: { "content-type": "application/json" } },
)
: new Response(null);
}) as unknown as typeof fetch;
const result = await callTool(connection, "read_file_content", {
fileId: "empty1",
});
expect(result).toEqual({
text: "empty.txt",
isError: false,
truncated: false,
});
});
});
/*
* Drive leaves shared drive items out of any `files.get` or `files.list` that does not say it supports
* them. Without these parameters a document the person could open in a shared drive was a 404 by id
* and missing from every search, and shared drives are where many companies keep their documents.
*/
describe("a file in a shared drive is reached like one in My Drive", () => {
test("both listings ask Drive for shared drive items", async () => {
const calls = stubFetch({ files: [] });
await callTool(connection, "search_files", { query: "roadmap" });
await callTool(connection, "list_recent_files", {});
expect(calls).toHaveLength(2);
for (const call of calls) {
const params = new URL(call.url).searchParams;
expect(params.get("supportsAllDrives")).toBe("true");
expect(params.get("includeItemsFromAllDrives")).toBe("true");
}
});
test("looking a file up says the caller supports shared drives", async () => {
const calls = stubFetch({ id: "shared1", name: "Plan" });
await callTool(connection, "get_file_metadata", { fileId: "shared1" });
expect(calls).toHaveLength(1);
expect(new URL(calls[0].url).searchParams.get("supportsAllDrives")).toBe(
"true",
);
});
test("reading a file says so on the lookup and on the download", async () => {
const calls = stubFetch({
id: "shared2",
name: "notes.txt",
mimeType: "text/plain",
});
await callTool(connection, "read_file_content", { fileId: "shared2" });
expect(calls).toHaveLength(2);
for (const call of calls) {
expect(new URL(call.url).searchParams.get("supportsAllDrives")).toBe(
"true",
);
}
});
});