@zackbart/connecta 0.34.1 → 0.36.0

package/dist/providers/drive/safety.js

@@ -0,0 +1,90 @@
+// Reviewed against Drive Discovery revision 20261020. Resource keys, decryption JWTs,
+// and vendor-generated private download destinations are permanently withheld.
+import { safe, refuse, vendorErrors } from "../_shared/rest/value-safety.js";
+export const DRIVE_VALUE_SAFETY = {
+    title: "Google Drive",
+    embeddedUrls: {},
+    operations: {
+        "GET /changes": refuse("This operation has not been admitted to the narrow Drive execution allowlist; use the named file and permission workflows."),
+        "GET /changes/startPageToken": refuse("This operation has not been admitted to the narrow Drive execution allowlist; use the named file and permission workflows."),
+        "POST /changes/watch": refuse("Persistent watch delivery and channel administration are outside this connection."),
+        "GET /drives": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "nextPageToken",
+        ])),
+        "GET /files": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "files[].appProperties",
+            "nextPageToken",
+        ])),
+        "POST /files": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "appProperties",
+        ])),
+        "GET /files/generateCseToken": refuse("Credential minting is outside this connection; no CSE access token is returned."),
+        "GET /files/{fileId}": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "appProperties",
+        ])),
+        "PATCH /files/{fileId}": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "appProperties",
+        ])),
+        "GET /files/{fileId}/accessproposals": refuse("Approval and access-proposal workflows require separate review and are outside this connection."),
+        "GET /files/{fileId}/approvals": refuse("Approval and access-proposal workflows require separate review and are outside this connection."),
+        "POST /files/{fileId}/approvals/{approvalId}:reassign": refuse("Approval and access-proposal workflows require separate review and are outside this connection."),
+        "GET /files/{fileId}/comments": refuse("This operation has not been admitted to the narrow Drive execution allowlist; use the named file and permission workflows."),
+        "GET /files/{fileId}/comments/{commentId}/replies": refuse("This operation has not been admitted to the narrow Drive execution allowlist; use the named file and permission workflows."),
+        "POST /files/{fileId}/copy": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "appProperties",
+        ])),
+        "GET /files/{fileId}/listLabels": refuse("This operation has not been admitted to the narrow Drive execution allowlist; use the named file and permission workflows."),
+        "GET /files/{fileId}/permissions": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "nextPageToken",
+        ])),
+        "PATCH /files/{fileId}/permissions/{permissionId}": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [])),
+        "GET /files/{fileId}/revisions": vendorErrors(safe("File metadata and continuation tokens are requested data; private capabilities are withheld globally.", [
+            "nextPageToken",
+        ])),
+        "POST /files/{fileId}/watch": refuse("Persistent watch delivery and channel administration are outside this connection."),
+        "GET /teamdrives": refuse("Shared-drive administration and ownership changes are outside this connection; list_shared_drives reads membership."),
+    },
+    fields: {
+        nextPageToken: {
+            verdict: "keep",
+            reason: "Opaque continuation bound to the delegated grant, not an access credential.",
+        },
+        appProperties: {
+            verdict: "keep",
+            reason: "Private application-authored metadata, not a Google credential; nested values still cross safety.",
+        },
+        jwt: { verdict: "redact", reason: "Client encryption decryption credentials are never returnable." },
+        resourceKey: { verdict: "redact", reason: "Link-sharing access keys convey private file access." },
+        targetResourceKey: { verdict: "redact", reason: "Shortcut target access keys convey private file access." },
+        webContentLink: {
+            verdict: "redact",
+            reason: "Use the bounded named content tool instead of a download destination.",
+        },
+        exportLinks: { verdict: "redact", reason: "Use the bounded named export instead of download destinations." },
+        thumbnailLink: { verdict: "redact", reason: "Short-lived thumbnail URLs convey private content." },
+        backgroundImageLink: {
+            verdict: "redact",
+            reason: "Short-lived shared-drive background image URLs convey private content.",
+        },
+        downloadUrl: { verdict: "redact", reason: "Revision download destinations are private media capabilities." },
+    },
+};
+/** Resource-key URLs are private even when embedded in ordinary metadata text. */
+export function withholdDriveLinks(value) {
+    if (typeof value === "string")
+        return value.replace(/https?:\/\/[^\s<>"\x60]+/gi, (text) => {
+            try {
+                const url = new URL(text.replaceAll("&amp;", "&"));
+                const names = [...url.searchParams.keys(), ...new URLSearchParams(url.hash.slice(1)).keys()];
+                return names.some((key) => /^(?:target)?resourcekey$/i.test(key)) ? "[redacted]" : text;
+            }
+            catch {
+                return text;
+            }
+        });
+    if (Array.isArray(value))
+        return value.map(withholdDriveLinks);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, withholdDriveLinks(item)]));
+    return value;
+}

package/dist/providers/drive/skill.generated.js

@@ -1,9 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "# Google Drive usage\n\nActs as the signed-in person's own Google Drive through Workspace delegation: what they can open, and nothing they cannot.\n\nConnection purpose: \n\n## Whose Drive\n\nEvery call acts as the Workspace address deployment config maps the caller\nto, and reaches exactly the files that person can open, shared drives\nincluded; an agent acts as the owner of the pool it came through, unless the deployment fixes one shared account that every caller, agent or person, acts as. No\nargument names an account. A call with none mapped fails `auth_required`; only an operator can change\nthat. A missing file\nand one this person cannot see fail alike — Google does not distinguish them.\n\n## Finding files\n\n- `search_files` takes Drive query syntax: `name contains 'x'`,\n  `fullText contains 'x'`, `mimeType = '…'`, `'<folderId>' in parents`,\n  `modifiedTime > '2026-01-01T00:00:00'`. Quote values with single quotes.\n  Trashed files are left out unless `includeTrashed`. `incompleteSearch:\n  true` means Drive gave up before searching everything; narrow the query or\n  the corpus. Shared drives: `list_shared_drives`, then `corpora: \"drive\"`\n  with its `driveId`.\n- Page with `page.nextCursor` and the same arguments; a cursor from another\n  tool or other arguments is refused. A page can stop short of `limit` to\n  stay under `maxBytes`; the cursor resumes at the first row left out, and\n  fails `conflict` if that page changed meanwhile — start over then.\n- Ids come from these reads or a Drive URL (`/d/<id>/`, `/folders/<id>`);\n  never guess one.\n\n## Reading content\n\n- `get_file_content` exports Docs as Markdown, Sheets as CSV of the\n  **first sheet only**, and Slides as plain text; reads text files as text;\n  and returns other files as base64 when the encoded file fits the result. Anything else — a\n  larger binary, a drawing, a form, a folder, a shortcut — comes back as\n  `format: \"unavailable\"` with a `note`, never as an empty success.\n- Text is capped by `maxChars`; a cut ends with a truncation marker and\n  `contentTruncated: true`. Drive exports at most 10 MB.\n- Every read stays under `maxBytes` of JSON. The default is what one result\n  can carry into `execute_code`, so a program always receives it. A larger\n  `maxBytes` (up to 4 MiB — a binary of up to 1 MiB) reaches only a direct\n  `call_tool`, which pages it with `connecta.result`.\n\n## Writing\n\n- `create_folder` and `restore_file` add without losing or exposing\n  anything.\n- A new file takes its folder's sharing, not its source's: `create_file`\n  and `copy_file` into a shared folder disclose that content to everyone\n  the folder is shared with, so both are approved like any destructive write.\n  Check the destination with `list_permissions` first. `convertTo`\n  imports content as a Google Doc, Sheet, or Slides file.\n- `update_file_content` replaces the whole content; send all of it.\n  `update_file` renames; `move_file` changes the folder and with it who\n  inherits access.\n- `trash_file` is recoverable for 30 days with `restore_file`. There is no\n  permanent delete and no ownership transfer.\n- `share_file` emails no one unless `sendNotificationEmail: true`. Check\n  `list_permissions` before and after changing access, and confirm with the\n  person before sharing with `anyone` or a whole domain.\n",
-    "instructionsHeading": "Connection instructions",
-    "fragments": {
-        "guide_0": "# Google Drive usage\n\nActs as the signed-in person's own Google Drive through Workspace delegation: what they can open, and nothing they cannot.\n\nConnection purpose: ",
-        "guide_1": "\n\n## Whose Drive\n\nEvery call acts as the Workspace address deployment config maps the caller\nto, and reaches exactly the files that person can open, shared drives\nincluded; an agent acts as the owner of the pool it came through, unless the deployment fixes one shared account that every caller, agent or person, acts as. No\nargument names an account. A call with none mapped fails `auth_required`; only an operator can change\nthat. A missing file\nand one this person cannot see fail alike — Google does not distinguish them.\n\n## Finding files\n\n- `search_files` takes Drive query syntax: `name contains 'x'`,\n  `fullText contains 'x'`, `mimeType = '…'`, `'<folderId>' in parents`,\n  `modifiedTime > '2026-01-01T00:00:00'`. Quote values with single quotes.\n  Trashed files are left out unless `includeTrashed`. `incompleteSearch:\n  true` means Drive gave up before searching everything; narrow the query or\n  the corpus. Shared drives: `list_shared_drives`, then `corpora: \"drive\"`\n  with its `driveId`.\n- Page with `page.nextCursor` and the same arguments; a cursor from another\n  tool or other arguments is refused. A page can stop short of `limit` to\n  stay under `maxBytes`; the cursor resumes at the first row left out, and\n  fails `conflict` if that page changed meanwhile — start over then.\n- Ids come from these reads or a Drive URL (`/d/<id>/`, `/folders/<id>`);\n  never guess one.\n\n## Reading content\n\n- `get_file_content` exports Docs as Markdown, Sheets as CSV of the\n  **first sheet only**, and Slides as plain text; reads text files as text;\n  and returns other files as base64 when the encoded file fits the result. Anything else — a\n  larger binary, a drawing, a form, a folder, a shortcut — comes back as\n  `format: \"unavailable\"` with a `note`, never as an empty success.\n- Text is capped by `maxChars`; a cut ends with a truncation marker and\n  `contentTruncated: true`. Drive exports at most 10 MB.\n- Every read stays under `maxBytes` of JSON. The default is what one result\n  can carry into `execute_code`, so a program always receives it. A larger\n  `maxBytes` (up to 4 MiB — a binary of up to 1 MiB) reaches only a direct\n  `call_tool`, which pages it with `connecta.result`.\n\n## Writing\n\n- `create_folder` and `restore_file` add without losing or exposing\n  anything.\n- A new file takes its folder's sharing, not its source's: `create_file`\n  and `copy_file` into a shared folder disclose that content to everyone\n  the folder is shared with, so both are approved like any destructive write.\n  Check the destination with `list_permissions` first. `convertTo`\n  imports content as a Google Doc, Sheet, or Slides file.\n- `update_file_content` replaces the whole content; send all of it.\n  `update_file` renames; `move_file` changes the folder and with it who\n  inherits access.\n- `trash_file` is recoverable for 30 days with `restore_file`. There is no\n  permanent delete and no ownership transfer.\n- `share_file` emails no one unless `sendNotificationEmail: true`. Check\n  `list_permissions` before and after changing access, and confirm with the\n  person before sharing with `anyone` or a whole domain.\n"
-    }
+    "content": "## Finding files and joining Workspace products\n\nDrive searches file data; operation discovery searches API capabilities.\nUse file ids from reads, Drive URLs or the person: an id they give, such as\n`pdf1`, works as is. The same id identifies a Google Doc,\nSheet, Slides deck or Form in its product connector. Shared-drive ids identify\nmembership and the root folder; folder parents determine inherited access.\nA missing file and a file the delegated user cannot see fail alike.\n\nDrive query values use single quotes: `name contains 'budget'`,\n`mimeType = 'application/pdf'`, `'folder_123' in parents`, or\n`modifiedTime > '2026-01-01T00:00:00'`. Trashed files are excluded by default.\n`incompleteSearch: true` means Google did not search every corpus; narrow the\nquery or choose a single shared drive. It is never an exact count.\n\n`maxBytes` is the byte budget and `limit` is rows per page; keep a high limit\nfor large folders and continue with the same listing arguments. Named `fields`\nmay narrow and `maxBytes` may change between pages. Hatch paths omit `/drive/v3`.\n\n## Content and file decisions\n\nThe content workflow exports Docs as Markdown, Sheets as CSV of the first\nsheet only, and Slides as text. Other text files retain their declared charset.\nSmall binary files can be returned as base64. A drawing, unsupported native\nfile, folder, shortcut or oversized binary returns an unavailable explanation.\nFor a shortcut, read its target id instead. Drive exports at most 10 MB.\n\nContent containing sent credentials is withheld as a whole binary value; there\nis no partial-content recovery around that boundary. Withheld MIME, shortcut,\nfolder or parent metadata cannot decide a subsequent read or move. Re-read\nthrough a safe source before trying the workflow again.\n\n## Access and recovery\n\nA file or copy inherits its destination folder's access. Read permission holders\nbefore moving, copying or creating in a shared folder, and read them again after\nchanging access. Inherited permissions name the parent folder or shared drive\nthat must be changed instead. An owner cannot be removed or replaced here.\n\nAll new grants use `share_file`, which sends no notification email by default.\nConfirm intent before granting `anyone` or domain access. Permission creation\nthrough the hatch is refused, including public-link grants; the named workflow\nowns grantee validation and notification behavior.\n\nContent updates replace the complete content. A create with an uncertain outcome\nneeds a search for the intended file before another create. Recoverable trash\ncan be restored for 30 days. Permanent deletion, ownership transfer, watch\nregistration, credential minting and generic media transport are outside the\nhatch. Use the named content and upload workflows for bounded bytes.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `drive_api_details`, `drive_api_read`, `drive_api_search`, `list_folder_items`, `list_permissions`, `list_shared_drives`, `search_files`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `drive_api_search` finds this API's operations and reads no account data, `drive_api_details` shows one operation's contract, and `drive_api_read` calls a reviewed read. `drive_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 51 operations are refused by design; use `drive_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A Drive source page changed before its local cursor resumed.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "instructionsHeading": "Connection instructions"
 };