runline 0.7.5 → 0.7.7

package/dist/plugins/googleDrive/src/index.js

@@ -18,6 +18,24 @@
  *   drive.create / drive.get / drive.list / drive.update / drive.delete
  *     (Shared Drives / Team Drives)
  *
+ *   comment.list / comment.get / comment.create / comment.update /
+ *   comment.delete / comment.resolve / comment.reopen
+ *   reply.list / reply.create / reply.update / reply.delete
+ *
+ *   revision.list / revision.get / revision.download /
+ *   revision.update / revision.delete / revision.restore
+ *     (Office-file comments live inside the bytes; revision.* is the
+ *      recovery path when file.update overwrites a working draft.)
+ *
+ *   changes.getStartPageToken / changes.list / changes.watch / changes.stop
+ *     (Drive change feed.)
+ *
+ *   permission.update — patch an existing share role / expiration.
+ *   accessProposal.list / accessProposal.resolve — Drive's "Request access" flow.
+ *   about.get — current user, quota, export formats.
+ *   file.export — native-doc export wrapper.
+ *   file.list — raw files.list (the wrapper is fileFolder.search).
+ *
  * Binary content conventions — every upload/download surface
  * speaks base64 or filesystem paths:
  *
@@ -1146,4 +1164,655 @@ export default function googleDrive(rl) {
             return { success: true };
         },
     });
+    // ─── Comments ────────────────────────────────────────────────────
+    //
+    // Drive's `comments` and `replies` resources. The comments live on
+    // the Drive side for both Google-native docs and Office files, and
+    // are distinct from in-document comments stored inside .docx /
+    // .xlsx / .pptx bytes (those round-trip through `revisions`).
+    const COMMENT_FIELDS = "kind,id,createdTime,modifiedTime,resolved,deleted," +
+        "author(displayName,emailAddress)," +
+        "quotedFileContent(value,mimeType)," +
+        "anchor,content,htmlContent," +
+        "replies(kind,id,createdTime,modifiedTime,deleted,author(displayName,emailAddress),action,content,htmlContent)";
+    const COMMENT_LIST_FIELDS = `kind,nextPageToken,comments(${COMMENT_FIELDS})`;
+    const REPLY_FIELDS = "kind,id,createdTime,modifiedTime,deleted," +
+        "author(displayName,emailAddress),action,content,htmlContent";
+    const REPLY_LIST_FIELDS = `kind,nextPageToken,replies(${REPLY_FIELDS})`;
+    rl.registerAction("comment.list", {
+        description: "List all comments on a Drive file, including each comment's replies. Returns an array sorted by Drive's default (most recent first).",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            includeDeleted: {
+                type: "boolean",
+                required: false,
+                description: "Include deleted comments. Default false.",
+            },
+            pageSize: {
+                type: "number",
+                required: false,
+                description: "Max comments per page (Drive caps at 100).",
+            },
+            startModifiedTime: {
+                type: "string",
+                required: false,
+                description: "RFC 3339 timestamp; only return comments modified at or after this time.",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const fileId = p.fileId;
+            const out = [];
+            const query = {
+                fields: COMMENT_LIST_FIELDS,
+                includeDeleted: p.includeDeleted ?? false,
+                pageSize: p.pageSize ?? 100,
+                startModifiedTime: p.startModifiedTime,
+            };
+            let pageToken;
+            do {
+                if (pageToken)
+                    query.pageToken = pageToken;
+                const page = (await driveRequest(ctx, "GET", `/drive/v3/files/${fileId}/comments`, undefined, query));
+                if (Array.isArray(page.comments))
+                    out.push(...page.comments);
+                pageToken = page.nextPageToken;
+            } while (pageToken);
+            return { fileId, count: out.length, comments: out };
+        },
+    });
+    rl.registerAction("comment.get", {
+        description: "Fetch a single comment (with its replies) by ID.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            includeDeleted: { type: "boolean", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "GET", `/drive/v3/files/${p.fileId}/comments/${p.commentId}`, undefined, { fields: COMMENT_FIELDS, includeDeleted: p.includeDeleted ?? false });
+        },
+    });
+    rl.registerAction("comment.create", {
+        description: "Create a new top-level comment on a file. Pass quotedFileContent.value (and optionally mimeType) to anchor the comment to a specific snippet.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            content: { type: "string", required: true, description: "Comment body (plain text)." },
+            quotedFileContent: {
+                type: "object",
+                required: false,
+                description: "{ value: string, mimeType?: string }",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = { content: p.content };
+            if (p.quotedFileContent)
+                body.quotedFileContent = p.quotedFileContent;
+            return driveRequest(ctx, "POST", `/drive/v3/files/${p.fileId}/comments`, body, { fields: COMMENT_FIELDS });
+        },
+    });
+    rl.registerAction("comment.update", {
+        description: "Edit the content of an existing comment. Caller must be the author or have edit rights.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            content: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "PATCH", `/drive/v3/files/${p.fileId}/comments/${p.commentId}`, { content: p.content }, { fields: COMMENT_FIELDS });
+        },
+    });
+    rl.registerAction("comment.delete", {
+        description: "Soft-delete a comment.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            await driveRequest(ctx, "DELETE", `/drive/v3/files/${p.fileId}/comments/${p.commentId}`);
+            return { success: true };
+        },
+    });
+    rl.registerAction("comment.resolve", {
+        description: "Resolve a comment thread by posting a resolution reply. `resolved` on a Comment is computed from replies; this is the canonical way to mark a thread done.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            content: {
+                type: "string",
+                required: false,
+                description: "Optional reply body. Defaults to 'Resolved.'",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "POST", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies`, { action: "resolve", content: p.content ?? "Resolved." }, { fields: REPLY_FIELDS });
+        },
+    });
+    rl.registerAction("comment.reopen", {
+        description: "Re-open a previously resolved comment by posting a reopen reply.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            content: { type: "string", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "POST", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies`, { action: "reopen", content: p.content ?? "Reopened." }, { fields: REPLY_FIELDS });
+        },
+    });
+    rl.registerAction("reply.list", {
+        description: "List replies on a specific comment.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            includeDeleted: { type: "boolean", required: false },
+            pageSize: { type: "number", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const out = [];
+            const query = {
+                fields: REPLY_LIST_FIELDS,
+                includeDeleted: p.includeDeleted ?? false,
+                pageSize: p.pageSize ?? 100,
+            };
+            let pageToken;
+            do {
+                if (pageToken)
+                    query.pageToken = pageToken;
+                const page = (await driveRequest(ctx, "GET", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies`, undefined, query));
+                if (Array.isArray(page.replies))
+                    out.push(...page.replies);
+                pageToken = page.nextPageToken;
+            } while (pageToken);
+            return { fileId: p.fileId, commentId: p.commentId, count: out.length, replies: out };
+        },
+    });
+    rl.registerAction("reply.create", {
+        description: "Post a reply to a comment. Pass action: 'resolve' | 'reopen' to also flip the comment state.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            content: { type: "string", required: true },
+            action: {
+                type: "string",
+                required: false,
+                description: "'resolve' | 'reopen'. Omit for a plain reply.",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = { content: p.content };
+            if (p.action === "resolve" || p.action === "reopen")
+                body.action = p.action;
+            return driveRequest(ctx, "POST", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies`, body, { fields: REPLY_FIELDS });
+        },
+    });
+    rl.registerAction("reply.update", {
+        description: "Edit the content of a reply.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            replyId: { type: "string", required: true },
+            content: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "PATCH", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies/${p.replyId}`, { content: p.content }, { fields: REPLY_FIELDS });
+        },
+    });
+    rl.registerAction("reply.delete", {
+        description: "Soft-delete a reply.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            commentId: { type: "string", required: true },
+            replyId: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            await driveRequest(ctx, "DELETE", `/drive/v3/files/${p.fileId}/comments/${p.commentId}/replies/${p.replyId}`);
+            return { success: true };
+        },
+    });
+    // ─── Revisions ──────────────────────────────────────────────────
+    //
+    // Drive retains prior bytes of every file. For Google-native docs
+    // that means snapshots of the doc state; for Office files (.docx,
+    // .xlsx, .pptx) it means the actual byte history. Exposing this
+    // matters because in-document review comments on Office files live
+    // *inside* the file bytes (`word/comments.xml`), not in Drive's
+    // `comments` resource. A call to `file.update({ contentPath })`
+    // silently destroys those comments; the only programmatic recovery
+    // path is reading prior revision bytes through these actions.
+    //
+    // Default retention is ~30 days / 100 revisions for Office files;
+    // set `keepForever: true` via `revision.update` on a known-good
+    // revision before any risky in-place update.
+    const REVISION_FIELDS = "id,mimeType,modifiedTime,keepForever,originalFilename,size,md5Checksum," +
+        "lastModifyingUser(displayName,emailAddress)," +
+        "published,publishAuto,publishedOutsideDomain,publishedLink";
+    const REVISION_LIST_FIELDS = `kind,nextPageToken,revisions(${REVISION_FIELDS})`;
+    rl.registerAction("revision.list", {
+        description: "List every revision Drive retains for a file, oldest first. For Office files the per-revision bytes are what `revision.download` returns.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            pageSize: { type: "number", required: false, description: "Default 200; Drive caps at 1000." },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const fileId = p.fileId;
+            const out = [];
+            const query = {
+                fields: REVISION_LIST_FIELDS,
+                pageSize: p.pageSize ?? 200,
+            };
+            let pageToken;
+            do {
+                if (pageToken)
+                    query.pageToken = pageToken;
+                const page = (await driveRequest(ctx, "GET", `/drive/v3/files/${fileId}/revisions`, undefined, query));
+                if (Array.isArray(page.revisions))
+                    out.push(...page.revisions);
+                pageToken = page.nextPageToken;
+            } while (pageToken);
+            return { fileId, count: out.length, revisions: out };
+        },
+    });
+    rl.registerAction("revision.get", {
+        description: "Fetch metadata for a single revision.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            revisionId: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "GET", `/drive/v3/files/${p.fileId}/revisions/${p.revisionId}`, undefined, { fields: REVISION_FIELDS });
+        },
+    });
+    rl.registerAction("revision.download", {
+        description: "Download the bytes of a specific revision. Pass savePath to write to disk and get back the path; otherwise returns { contentBase64, mimeType, size }. This is the recovery path when an in-place file.update has overwritten in-document comments on an Office file.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            revisionId: { type: "string", required: true },
+            savePath: {
+                type: "string",
+                required: false,
+                description: "Filesystem path to write the bytes to. If omitted, returns base64.",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const fileId = p.fileId;
+            const revisionId = p.revisionId;
+            const token = await accessToken(ctx);
+            const url = new URL(`${API_BASE}/drive/v3/files/${fileId}/revisions/${revisionId}`);
+            url.searchParams.set("alt", "media");
+            const res = await fetch(url.toString(), {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) {
+                throw new Error(`googleDrive: revision download failed (${res.status}): ${await res.text()}`);
+            }
+            const bytes = Buffer.from(await res.arrayBuffer());
+            const mimeType = res.headers.get("content-type") ?? "application/octet-stream";
+            if (typeof p.savePath === "string") {
+                writeFileSync(p.savePath, bytes);
+                return { fileId, revisionId, mimeType, size: bytes.byteLength, savedTo: p.savePath };
+            }
+            return {
+                fileId,
+                revisionId,
+                mimeType,
+                size: bytes.byteLength,
+                contentBase64: bytes.toString("base64"),
+            };
+        },
+    });
+    rl.registerAction("revision.update", {
+        description: "Patch revision metadata. The most useful flag is keepForever — without it Drive can garbage-collect revisions after 30 days / 100 versions on Office files. Set keepForever=true on the head revision before any risky file.update so prior bytes are guaranteed recoverable.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            revisionId: { type: "string", required: true },
+            keepForever: { type: "boolean", required: false },
+            published: { type: "boolean", required: false },
+            publishAuto: { type: "boolean", required: false },
+            publishedOutsideDomain: { type: "boolean", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = {};
+            for (const k of [
+                "keepForever",
+                "published",
+                "publishAuto",
+                "publishedOutsideDomain",
+            ]) {
+                if (p[k] !== undefined)
+                    body[k] = p[k];
+            }
+            if (Object.keys(body).length === 0) {
+                throw new Error("googleDrive.revision.update: pass at least one of keepForever / published / publishAuto / publishedOutsideDomain.");
+            }
+            return driveRequest(ctx, "PATCH", `/drive/v3/files/${p.fileId}/revisions/${p.revisionId}`, body, { fields: REVISION_FIELDS });
+        },
+    });
+    rl.registerAction("revision.delete", {
+        description: "Permanently delete a revision (head revision cannot be deleted).",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            revisionId: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            await driveRequest(ctx, "DELETE", `/drive/v3/files/${p.fileId}/revisions/${p.revisionId}`);
+            return { success: true };
+        },
+    });
+    rl.registerAction("revision.restore", {
+        description: "Restore an older revision as the head of the file. Downloads the revision bytes and re-uploads them via multipart so the head moves to that content. Drive's REST API has no native restore endpoint for binary files; this performs the equivalent in two calls. Returns the new head file resource.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            revisionId: { type: "string", required: true, description: "Revision to restore as head." },
+            mimeType: {
+                type: "string",
+                required: false,
+                description: "Override mime type for the re-upload. Defaults to the revision's mime type.",
+            },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const fileId = p.fileId;
+            const revisionId = p.revisionId;
+            const token = await accessToken(ctx);
+            // 1. Pull the chosen revision's bytes.
+            const dl = await fetch(`${API_BASE}/drive/v3/files/${fileId}/revisions/${revisionId}?alt=media`, { headers: { Authorization: `Bearer ${token}` } });
+            if (!dl.ok) {
+                throw new Error(`googleDrive: revision restore download failed (${dl.status}): ${await dl.text()}`);
+            }
+            const bytes = Buffer.from(await dl.arrayBuffer());
+            const mime = p.mimeType ??
+                dl.headers.get("content-type") ??
+                "application/octet-stream";
+            // 2. Multipart-PATCH them as the new head of the same file.
+            const url = new URL(`${API_BASE}/upload/drive/v3/files/${fileId}`);
+            url.searchParams.set("uploadType", "multipart");
+            url.searchParams.set("supportsAllDrives", "true");
+            url.searchParams.set("fields", "id,name,mimeType,modifiedTime,size,headRevisionId,webViewLink");
+            const body = buildMultipart({ mimeType: mime }, bytes, mime);
+            const res = await fetch(url.toString(), {
+                method: "PATCH",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": `multipart/related; boundary=${MULTIPART_BOUNDARY}`,
+                    "Content-Length": String(body.byteLength),
+                },
+                body: new Uint8Array(body),
+            });
+            if (!res.ok) {
+                throw new Error(`googleDrive: revision restore upload failed (${res.status}): ${await res.text()}`);
+            }
+            const head = (await res.json());
+            return { fileId, restoredFromRevisionId: revisionId, head };
+        },
+    });
+    // ─── Changes feed ───────────────────────────────────────────────
+    //
+    // Drive's change feed. Without these the agent has to poll comment.list
+    // per file. With them, a sensor can wake on any file change in the user's
+    // corpus or in a specific shared drive.
+    rl.registerAction("changes.getStartPageToken", {
+        description: "Get the current Drive change-feed start page token. Use as the seed `pageToken` for the first `changes.list` call.",
+        inputSchema: {
+            driveId: { type: "string", required: false, description: "Shared-drive id; omit for the user's My Drive corpus." },
+            supportsAllDrives: { type: "boolean", required: false, default: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "GET", `/drive/v3/changes/startPageToken`, undefined, {
+                driveId: p.driveId,
+                supportsAllDrives: p.supportsAllDrives ?? true,
+            });
+        },
+    });
+    rl.registerAction("changes.list", {
+        description: "List changes to files and Shared Drives since the given `pageToken`. Returns `{ changes, newStartPageToken, nextPageToken? }`. Drive does not surface comment-level changes here — use this for file metadata/content changes; pair with comments.list for review activity.",
+        inputSchema: {
+            pageToken: { type: "string", required: true, description: "Token from `changes.getStartPageToken` or a prior `nextPageToken`." },
+            driveId: { type: "string", required: false },
+            spaces: { type: "string", required: false, description: "drive | photos | appDataFolder. Default drive." },
+            includeRemoved: { type: "boolean", required: false },
+            includeItemsFromAllDrives: { type: "boolean", required: false, default: true },
+            supportsAllDrives: { type: "boolean", required: false, default: true },
+            restrictToMyDrive: { type: "boolean", required: false },
+            pageSize: { type: "number", required: false },
+            fields: { type: "string", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "GET", `/drive/v3/changes`, undefined, {
+                pageToken: p.pageToken,
+                driveId: p.driveId,
+                spaces: p.spaces,
+                includeRemoved: p.includeRemoved,
+                includeItemsFromAllDrives: p.includeItemsFromAllDrives ?? true,
+                supportsAllDrives: p.supportsAllDrives ?? true,
+                restrictToMyDrive: p.restrictToMyDrive,
+                pageSize: p.pageSize ?? 100,
+                fields: p.fields ??
+                    "kind,nextPageToken,newStartPageToken,changes(kind,removed,fileId,driveId,changeType,time,file(id,name,mimeType,modifiedTime,trashed,parents))",
+            });
+        },
+    });
+    rl.registerAction("changes.watch", {
+        description: "Subscribe to push notifications on the change feed. Drive will POST to `address` whenever a change in this corpus is recorded. Returns a channel resource; pair with `channels.stop` (`changes.stop`) when done.",
+        inputSchema: {
+            pageToken: { type: "string", required: true },
+            address: { type: "string", required: true, description: "HTTPS URL Drive will POST notifications to." },
+            channelId: { type: "string", required: false, description: "Caller-chosen UUID. Auto-generated when omitted." },
+            token: { type: "string", required: false, description: "Optional opaque token Drive echoes on each delivery." },
+            expiration: { type: "number", required: false, description: "Unix ms at which Drive should expire the channel. Defaults ~1 hour." },
+            driveId: { type: "string", required: false },
+            supportsAllDrives: { type: "boolean", required: false, default: true },
+            includeItemsFromAllDrives: { type: "boolean", required: false, default: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = {
+                id: p.channelId ?? uuid(),
+                type: "web_hook",
+                address: p.address,
+            };
+            if (p.token)
+                body.token = p.token;
+            if (p.expiration)
+                body.expiration = String(p.expiration);
+            return driveRequest(ctx, "POST", `/drive/v3/changes/watch`, body, {
+                pageToken: p.pageToken,
+                driveId: p.driveId,
+                supportsAllDrives: p.supportsAllDrives ?? true,
+                includeItemsFromAllDrives: p.includeItemsFromAllDrives ?? true,
+            });
+        },
+    });
+    rl.registerAction("changes.stop", {
+        description: "Stop a previously-subscribed change channel. Pass the same `channelId` and `resourceId` returned by `changes.watch`.",
+        inputSchema: {
+            channelId: { type: "string", required: true },
+            resourceId: { type: "string", required: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            await driveRequest(ctx, "POST", `/drive/v3/channels/stop`, { id: p.channelId, resourceId: p.resourceId });
+            return { success: true };
+        },
+    });
+    // ─── Permission update ──────────────────────────────────────────
+    //
+    // Patch an existing permission. The bundled `file.share` creates a new
+    // permission, and `file.deletePermission` removes one — but to promote a
+    // commenter to writer (or expire a permission) without re-sharing, you
+    // need the PATCH endpoint.
+    rl.registerAction("permission.update", {
+        description: "Patch an existing file/folder permission. Use to change the role on an existing share, set an expiration time, or transfer ownership.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            permissionId: { type: "string", required: true },
+            role: { type: "string", required: false, description: "owner | organizer | fileOrganizer | writer | commenter | reader" },
+            expirationTime: { type: "string", required: false, description: "RFC 3339; only valid for writer/commenter/reader on My Drive files." },
+            transferOwnership: { type: "boolean", required: false },
+            removeExpiration: { type: "boolean", required: false },
+            useDomainAdminAccess: { type: "boolean", required: false },
+            supportsAllDrives: { type: "boolean", required: false, default: true },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = {};
+            if (p.role)
+                body.role = p.role;
+            if (p.expirationTime)
+                body.expirationTime = p.expirationTime;
+            const qs = { supportsAllDrives: p.supportsAllDrives ?? true };
+            if (p.transferOwnership)
+                qs.transferOwnership = true;
+            if (p.removeExpiration)
+                qs.removeExpiration = true;
+            if (p.useDomainAdminAccess)
+                qs.useDomainAdminAccess = true;
+            if (Object.keys(body).length === 0 && !qs.removeExpiration) {
+                throw new Error("googleDrive.permission.update: pass at least one of role / expirationTime / removeExpiration.");
+            }
+            return driveRequest(ctx, "PATCH", `/drive/v3/files/${p.fileId}/permissions/${p.permissionId}`, body, qs);
+        },
+    });
+    // ─── Access proposals ───────────────────────────────────────────
+    //
+    // Drive's "Request access" flow. When a user clicks "Request access" on a
+    // file they can't open, Drive records an access proposal which the file's
+    // owner can resolve (accept and grant, or deny). These actions let the
+    // agent triage and resolve those requests programmatically.
+    rl.registerAction("accessProposal.list", {
+        description: "List access proposals (Request-access entries) on a file.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            pageSize: { type: "number", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const out = [];
+            let pageToken;
+            do {
+                const page = (await driveRequest(ctx, "GET", `/drive/v3/files/${p.fileId}/accessproposals`, undefined, { pageSize: p.pageSize ?? 100, pageToken }));
+                if (Array.isArray(page.accessProposals))
+                    out.push(...page.accessProposals);
+                pageToken = page.nextPageToken;
+            } while (pageToken);
+            return { fileId: p.fileId, count: out.length, accessProposals: out };
+        },
+    });
+    rl.registerAction("accessProposal.resolve", {
+        description: "Resolve an access proposal. `action` is one of 'ACCEPT' or 'DENY'. When accepting, pass `role` (default 'reader') to grant.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            proposalId: { type: "string", required: true },
+            action: { type: "string", required: true, description: "'ACCEPT' | 'DENY'" },
+            role: { type: "string", required: false, description: "Role to grant on ACCEPT. Default 'reader'." },
+            view: { type: "string", required: false, description: "Optional Drive scope view (e.g. 'published')." },
+            sendNotification: { type: "boolean", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const body = { action: p.action };
+            if (p.action === "ACCEPT") {
+                body.role = [p.role ?? "reader"];
+                if (p.view)
+                    body.view = p.view;
+            }
+            if (p.sendNotification !== undefined)
+                body.sendNotification = p.sendNotification;
+            return driveRequest(ctx, "POST", `/drive/v3/files/${p.fileId}/accessproposals/${p.proposalId}:resolve`, body);
+        },
+    });
+    // ─── About ───────────────────────────────────────────────────────
+    rl.registerAction("about.get", {
+        description: "Current user info: storage quota, export formats, max upload size, importable mime types. Useful for healthchecks and conversion planning.",
+        inputSchema: {
+            fields: { type: "string", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            return driveRequest(ctx, "GET", `/drive/v3/about`, undefined, {
+                fields: p.fields ??
+                    "user(displayName,emailAddress,permissionId,photoLink),storageQuota,maxUploadSize,canCreateDrives,exportFormats,importFormats",
+            });
+        },
+    });
+    // ─── File export (ergonomic wrapper) ────────────────────────────
+    rl.registerAction("file.export", {
+        description: "Export a Google-native file (Doc/Sheet/Slide/Drawing/Form) to a non-native mimeType. Wrapper around the export endpoint; pass `savePath` to write to disk and get the path back, otherwise returns base64.",
+        inputSchema: {
+            fileId: { type: "string", required: true },
+            mimeType: {
+                type: "string",
+                required: true,
+                description: "Target export mime, e.g. application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, text/plain, text/csv.",
+            },
+            savePath: { type: "string", required: false },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const token = await accessToken(ctx);
+            const u = new URL(`${API_BASE}/drive/v3/files/${p.fileId}/export`);
+            u.searchParams.set("mimeType", p.mimeType);
+            const res = await fetch(u.toString(), { headers: { Authorization: `Bearer ${token}` } });
+            if (!res.ok) {
+                throw new Error(`googleDrive: export failed (${res.status}): ${await res.text()}`);
+            }
+            const bytes = Buffer.from(await res.arrayBuffer());
+            const contentType = res.headers.get("content-type") ?? p.mimeType;
+            if (typeof p.savePath === "string") {
+                writeFileSync(p.savePath, bytes);
+                return { path: p.savePath, mimeType: contentType, size: bytes.byteLength };
+            }
+            return { mimeType: contentType, size: bytes.byteLength, contentBase64: bytes.toString("base64") };
+        },
+    });
+    // ─── Raw file.list ──────────────────────────────────────────────
+    rl.registerAction("file.list", {
+        description: "Raw Drive `files.list`. Pass Drive search-syntax `q` and any combination of corpora / driveId / spaces / orderBy. `fileFolder.search` is the friendlier wrapper; reach for `file.list` only when you need the unwrapped surface.",
+        inputSchema: {
+            q: { type: "string", required: false },
+            corpora: { type: "string", required: false, description: "user | drive | allDrives" },
+            driveId: { type: "string", required: false },
+            spaces: { type: "string", required: false },
+            orderBy: { type: "string", required: false },
+            pageSize: { type: "number", required: false },
+            pageToken: { type: "string", required: false },
+            includeItemsFromAllDrives: { type: "boolean", required: false, default: true },
+            supportsAllDrives: { type: "boolean", required: false, default: true },
+            fields: { type: "string", required: false },
+            returnAll: { type: "boolean", required: false, description: "If true, follows pageToken until exhausted and returns the concatenated file list." },
+        },
+        async execute(input, ctx) {
+            const p = (input ?? {});
+            const baseQs = {
+                q: p.q,
+                corpora: p.corpora,
+                driveId: p.driveId,
+                spaces: p.spaces,
+                orderBy: p.orderBy,
+                pageSize: p.pageSize ?? 100,
+                includeItemsFromAllDrives: p.includeItemsFromAllDrives ?? true,
+                supportsAllDrives: p.supportsAllDrives ?? true,
+                fields: p.fields ?? "kind,nextPageToken,files(id,name,mimeType,parents,modifiedTime,size,owners(emailAddress),driveId,webViewLink)",
+            };
+            if (p.returnAll) {
+                return paginateAll(ctx, "/drive/v3/files", "files", baseQs);
+            }
+            return driveRequest(ctx, "GET", `/drive/v3/files`, undefined, { ...baseQs, pageToken: p.pageToken });
+        },
+    });
 }