@zackbart/connecta 0.31.0 → 0.33.0

package/dist/providers/gmail/index.js

@@ -26,7 +26,7 @@ import { skill } from "./skill.generated.js";
  */
 import { apiConnector as api, defined } from "../../connectors/api-connector.js";
 import { ConnectorCallError } from "../../errors.js";
-import { GOOGLE_WORKSPACE_OPTIONS, googleWorkspaceClient, workspaceConnection, } from "../_shared/google/workspace.js";
+import { GOOGLE_WORKSPACE_OPTIONS, googleWorkspaceClient, workspaceConnection, workspaceConnector, } from "../_shared/google/workspace.js";
 import { RESULT_BUDGET_BYTES, clampText, jsonBytes } from "../_shared/google/result-size.js";
 import { asProviderFactory } from "../../provider.js";
 /**
@@ -58,6 +58,11 @@ const SUMMARY_CONCURRENCY = 5;
 /** A full thread without attachment bodies; Gmail's message cap is 25 MB. */
 const GMAIL_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
 const MAX_RECIPIENTS = 100;
+/** Gmail cannot range-read attachment JSON, so text and binary downloads are bounded. */
+const MAX_ATTACHMENT_BYTES = 1024 * 1024;
+/** Same direct-call ceiling and minimum result budget as Drive content reads. */
+const MAX_ATTACHMENT_RESULT_BYTES = 4 * 1024 * 1024;
+const MIN_ATTACHMENT_RESULT_BYTES = 64 * 1024;
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -118,22 +123,37 @@ function base64UrlBytes(data) {
 }
 function charsetOf(part) {
     const type = header(part, "Content-Type") ?? "";
-    return /charset="?([^";\s]+)"?/i.exec(type)?.[1] ?? "utf-8";
+    // Consume complete parameters so a semicolon inside another quoted value
+    // cannot masquerade as a charset. MIME allows whitespace between tokens.
+    const parameters = /;\s*([^=;\s]+)\s*=\s*(?:"((?:\\.|[^"\\])*)"|([^;\s]*))/g;
+    for (const match of type.matchAll(parameters)) {
+        if (match[1].toLowerCase() === "charset") {
+            return (match[2]?.replace(/\\(.)/g, "$1") ?? match[3] ?? "").trim();
+        }
+    }
+    return "utf-8";
 }
-/** Bytes as text, in the part's declared charset where the runtime knows it. */
+/** Bytes as text, with an explicit notice when the declared charset is unsupported. */
 function decodeIn(part, data) {
     let bytes;
     try {
         bytes = base64UrlBytes(data);
     }
     catch {
-        return "";
+        return { text: "" };
     }
+    return decodeBytes(part, bytes);
+}
+function decodeBytes(part, bytes) {
+    const charset = charsetOf(part);
     try {
-        return new TextDecoder(charsetOf(part)).decode(bytes);
+        return { text: new TextDecoder(charset).decode(bytes) };
     }
     catch {
-        return new TextDecoder().decode(bytes);
+        return {
+            text: new TextDecoder().decode(bytes),
+            note: `Gmail declared unsupported charset "${clipped(charset, FIELD_BYTES)}"; decoded as UTF-8.`,
+        };
     }
 }
 function mimeOf(part) {
@@ -161,13 +181,13 @@ const BODY_TYPES = new Set(["text/plain", "text/html"]);
 const MAX_PART_DEPTH = 20;
 /**
  * Walk a payload keeping ancestry: the message's own parts, in order, and the
- * attachment roots, whose subtrees are never entered.
+ * attachment roots, whose subtrees are entered only for a resolved forwarded root.
  */
-function walk(root) {
+function walk(root, enterAttachmentRoot = false) {
     const own = [];
     const attachments = [];
     const visit = (part, depth) => {
-        if (isAttachment(part)) {
+        if (isAttachment(part) && !(enterAttachmentRoot && depth === 0)) {
             attachments.push(part);
             return;
         }
@@ -180,6 +200,10 @@ function walk(root) {
     visit(root, 0);
     return { own, attachments };
 }
+/** The same plain-first selection for messages and parsed forwarded attachments. */
+function ownBody(own) {
+    return own.find((part) => mimeOf(part) === "text/plain") ?? own.find((part) => mimeOf(part) === "text/html");
+}
 /** Gmail stores a large body apart from the message, behind an attachment id. */
 const MAX_STORED_BODY_BYTES = 1024 * 1024;
 /**
@@ -190,11 +214,10 @@ const MAX_STORED_BODY_BYTES = 1024 * 1024;
  */
 async function readBody(client, ctx, messageId, payload, max) {
     const own = walk(payload).own;
-    const plain = own.find((part) => mimeOf(part) === "text/plain");
-    const chosen = plain ?? own.find((part) => mimeOf(part) === "text/html");
+    const chosen = ownBody(own);
     if (!chosen)
         return { body: "", bodyTruncated: false, bodyFormat: "none" };
-    const format = plain ? "text" : "html";
+    const format = mimeOf(chosen) === "text/plain" ? "text" : "html";
     const stored = asRecord(chosen["body"]);
     let data = text(stored["data"]);
     const attachmentId = text(stored["attachmentId"]);
@@ -216,9 +239,13 @@ async function readBody(client, ctx, messageId, payload, max) {
         }, ctx));
         data = text(fetched["data"]);
     }
-    const decoded = data ? decodeIn(chosen, data) : "";
+    const decoded = data ? decodeIn(chosen, data) : { text: "" };
     // Uncut: the caller caps it, by characters and by the result's bytes.
-    return { text: format === "html" ? htmlToText(decoded) : decoded, bodyFormat: format };
+    return {
+        text: format === "html" ? htmlToText(decoded.text) : decoded.text,
+        bodyFormat: format,
+        ...(decoded.note ? { bodyNote: decoded.note } : {}),
+    };
 }
 /**
  * Gmail's ids are short opaque tokens — message and thread ids are sixteen
@@ -243,7 +270,7 @@ function ids(fields) {
     const kept = {};
     const omitted = [];
     for (const [name, [value, maxBytes]] of Object.entries(fields)) {
-        const id = idOf(value, maxBytes);
+        const id = name === "partId" ? partIdOf(value) : idOf(value, maxBytes);
         if (id !== undefined)
             kept[name] = id;
         else if (text(value) !== undefined)
@@ -269,11 +296,180 @@ function attachmentsOf(payload) {
             filename: clipped(text(part["filename"]) ?? "", FIELD_BYTES),
             mimeType: clipped(text(part["mimeType"]), FIELD_BYTES),
             size: typeof asRecord(part["body"])["size"] === "number" ? asRecord(part["body"])["size"] : undefined,
-            ...ids({ attachmentId: [asRecord(part["body"])["attachmentId"], ATTACHMENT_ID_BYTES] }),
+            ...ids({
+                attachmentId: [asRecord(part["body"])["attachmentId"], ATTACHMENT_ID_BYTES],
+                partId: [part["partId"]],
+            }),
         })),
         omitted: Math.max(0, all.length - MAX_LISTED_ATTACHMENTS),
     };
 }
+/** Unlike opaque ids, Gmail's root part id may be empty. */
+function partIdOf(value) {
+    return typeof value === "string" && jsonBytes(value) <= ID_BYTES ? value : undefined;
+}
+function declaredSize(body) {
+    const size = body["size"];
+    return typeof size === "number" && Number.isSafeInteger(size) && size >= 0 ? size : undefined;
+}
+/** Include every descendant, even carried files that body selection will skip. */
+function forwardedSize(part, depth = 0) {
+    if (depth > MAX_PART_DEPTH)
+        return undefined;
+    const body = asRecord(part["body"]);
+    const children = asArray(part["parts"]);
+    let total = declaredSize(body);
+    if (total === undefined) {
+        if (children.length === 0 || body["size"] !== undefined || body["attachmentId"] || body["data"])
+            return undefined;
+        total = 0;
+    }
+    for (const child of children) {
+        const size = forwardedSize(asRecord(child), depth + 1);
+        if (size === undefined)
+            return undefined;
+        total += size;
+        if (!Number.isSafeInteger(total))
+            return undefined;
+    }
+    return total;
+}
+/** Validate both Gmail byte counts before content can be returned as complete. */
+async function attachmentBytes(client, ctx, messageId, part) {
+    const stored = asRecord(part["body"]);
+    let source = stored;
+    const freshId = text(stored["attachmentId"]);
+    if (freshId) {
+        source = asRecord(await client.json({
+            method: "GET",
+            path: `/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(freshId)}`,
+        }, ctx));
+    }
+    const data = source["data"];
+    if (typeof data !== "string")
+        return undefined;
+    let bytes;
+    try {
+        bytes = base64UrlBytes(data);
+    }
+    catch {
+        throw new ConnectorCallError("connector_call_failed", "Gmail returned invalid base64url attachment data.", {
+            retryable: false,
+        });
+    }
+    if (bytes.length !== declaredSize(stored) ||
+        (source["size"] !== undefined && bytes.length !== declaredSize(source))) {
+        throw new ConnectorCallError("connector_call_failed", "Gmail attachment data does not match its declared byte size.", { retryable: false });
+    }
+    return bytes;
+}
+/** Read only a carried part of a fresh message, never an arbitrary download id. */
+async function readAttachment(client, ctx, args) {
+    const messageId = String(args["messageId"]);
+    const partId = args["partId"];
+    const attachmentId = text(args["attachmentId"]);
+    if (partId === undefined && attachmentId === undefined) {
+        throw new ConnectorCallError("invalid_args", "Supply partId from the attachment listing, or attachmentId.");
+    }
+    const message = asRecord(await client.json({ method: "GET", path: `/messages/${encodeURIComponent(messageId)}`, query: { format: "full" } }, ctx));
+    const attachments = walk(asRecord(message["payload"])).attachments;
+    // partId is immutable and authoritative when supplied. An attachmentId
+    // from the previous listing may have rotated since that messages.get.
+    const part = attachments.find((entry) => partId !== undefined ? entry["partId"] === partId : asRecord(entry["body"])["attachmentId"] === attachmentId);
+    if (!part) {
+        throw new ConnectorCallError("not_found", "This attachment is not among the message's carried parts. Read get_message again and use its immutable partId.");
+    }
+    const stored = asRecord(part["body"]);
+    const mime = mimeOf(part).split(";")[0].trim();
+    const parsedForward = mime === "message/rfc822" &&
+        !text(stored["attachmentId"]) &&
+        !text(stored["data"]) &&
+        asArray(part["parts"]).length > 0;
+    const size = parsedForward ? forwardedSize(part) : declaredSize(stored);
+    const maxBytes = typeof args["maxBytes"] === "number" ? args["maxBytes"] : RESULT_BUDGET_BYTES;
+    const maxChars = typeof args["maxChars"] === "number" ? args["maxChars"] : DEFAULT_MESSAGE_BODY_CHARS;
+    const base = compact({
+        messageId,
+        ...ids({ partId: [part["partId"]] }),
+        filename: clipped(text(part["filename"]) ?? "", FIELD_BYTES),
+        mimeType: clipped(text(part["mimeType"]) ?? "application/octet-stream", FIELD_BYTES),
+        size,
+    });
+    const unavailable = (note) => ({ ...base, format: "unavailable", contentTruncated: false, note });
+    const isText = mime.startsWith("text/") ||
+        ["application/json", "application/xml", "message/rfc822"].includes(mime) ||
+        mime.endsWith("+json") ||
+        mime.endsWith("+xml");
+    let envelope = { ...base, format: isText ? "text" : "base64", content: "", contentTruncated: false };
+    const fitting = Math.floor(Math.max(0, maxBytes - jsonBytes(envelope)) / 4) * 3;
+    const limit = isText ? MAX_ATTACHMENT_BYTES : Math.min(MAX_ATTACHMENT_BYTES, fitting);
+    const tooLarge = () => unavailable(limit < MAX_ATTACHMENT_BYTES
+        ? `This binary attachment does not fit maxBytes (${maxBytes}), which holds ${limit} attachment bytes. Raise maxBytes, up to ${MAX_ATTACHMENT_RESULT_BYTES} for a direct call_tool only, to read up to ${MAX_ATTACHMENT_BYTES} bytes. No content is returned.`
+        : `This attachment exceeds the ${MAX_ATTACHMENT_BYTES}-byte download and inline cap. No content is returned; open it in Gmail.`);
+    // Declared size is checked before downloading, but actual bytes are checked
+    // too: inconsistent metadata must never bypass the cap or whole-result budget.
+    if (size === undefined)
+        return unavailable("Gmail did not declare a valid attachment size; no content is downloaded. Open it in Gmail.");
+    if (size > limit)
+        return tooLarge();
+    let decoded;
+    if (parsedForward) {
+        const own = walk(part, true).own;
+        const chosen = ownBody(own);
+        if (!chosen)
+            return unavailable("This forwarded message has no readable text body; open it in Gmail.");
+        const bytes = await attachmentBytes(client, ctx, messageId, chosen);
+        if (!bytes)
+            return unavailable("Gmail returned no readable forwarded message body data; open it in Gmail.");
+        const rendered = decodeBytes(chosen, bytes);
+        if (!rendered.text.trim())
+            return unavailable("This forwarded message has no readable text body; open it in Gmail.");
+        const headers = ["From", "To", "Date", "Subject"].flatMap((name) => {
+            const value = own.map((entry) => header(entry, name)).find((entry) => entry !== undefined);
+            return value === undefined ? [] : [`${name}: ${value}`];
+        });
+        const body = mimeOf(chosen) === "text/html" ? htmlToText(rendered.text) : rendered.text;
+        if (!body.trim())
+            return unavailable("This forwarded message has no readable text body; open it in Gmail.");
+        decoded = headers.length > 0 ? `${headers.join("\n")}\n\n${body}` : body;
+        envelope = { ...envelope, ...compact({ note: rendered.note }) };
+    }
+    else {
+        const bytes = await attachmentBytes(client, ctx, messageId, part);
+        if (!bytes)
+            return unavailable("Gmail returned no attachment data; open it in Gmail.");
+        if (bytes.length > limit)
+            return tooLarge();
+        if (!isText) {
+            let binary = "";
+            for (let index = 0; index < bytes.length; index += 0x8000) {
+                binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+            }
+            return { ...envelope, content: btoa(binary) };
+        }
+        const rendered = decodeBytes(part, bytes);
+        decoded = rendered.text;
+        if (mime === "message/rfc822" && !decoded.trim()) {
+            return unavailable("This forwarded message has no readable text body; open it in Gmail.");
+        }
+        envelope = { ...envelope, ...compact({ note: rendered.note }) };
+    }
+    const characters = Array.from(decoded);
+    const marker = (dropped) => `\n[… ${dropped} more characters truncated; raise maxChars or maxBytes for a direct call_tool, or open it in Gmail]`;
+    const byChars = characters.length > maxChars
+        ? characters.slice(0, maxChars).join("") + marker(characters.length - maxChars)
+        : decoded;
+    if (jsonBytes({ ...envelope, content: byChars }) <= maxBytes) {
+        return { ...envelope, content: byChars, contentTruncated: characters.length > maxChars };
+    }
+    // Reserve the longest marker, then clamp only the original prefix. A text
+    // cut by both limits still has one marker, counted in the result's budget.
+    const prefix = characters.slice(0, maxChars).join("");
+    const contentBudget = maxBytes - jsonBytes(envelope) + jsonBytes("");
+    const kept = clampText(prefix, contentBudget - jsonBytes(marker(characters.length)) + 2, () => "");
+    const content = kept + marker(characters.length - Array.from(kept).length);
+    return { ...envelope, content, contentTruncated: true };
+}
 /**
  * Per-field byte bounds, so every result is bounded by construction: a page
  * of 25 summaries, or one message beside its body, stays under
@@ -334,6 +530,7 @@ async function projectMessage(client, ctx, value, maxBodyChars, budget = RESULT_
         body: "",
         bodyTruncated: false,
         bodyFormat: read.bodyFormat,
+        bodyNote: read.bodyNote,
         attachments: attachments.listed.length > 0 ? attachments.listed : undefined,
         attachmentsOmitted: attachments.omitted > 0 ? attachments.omitted : undefined,
         omittedIds,
@@ -428,10 +625,10 @@ function resultLimitMarker(dropped) {
  * all, against the budget. The bounds above make a refusal here a
  * should-not-happen; it exists so nothing oversized is ever handed on.
  */
-function deliverable(tool, result) {
+function deliverable(tool, result, budget = RESULT_BUDGET_BYTES) {
     const size = jsonBytes(result);
-    if (size > RESULT_BUDGET_BYTES) {
-        throw new ConnectorCallError("connector_call_failed", `Gmail's answer to ${tool} is ${size} bytes even after cutting, past connecta's ${RESULT_BUDGET_BYTES / 1024} KiB result limit. Open it in Gmail.`, { retryable: false });
+    if (size > budget) {
+        throw new ConnectorCallError("connector_call_failed", `Gmail's answer to ${tool} is ${size} bytes even after cutting, past connecta's ${budget / 1024} KiB result limit. Open it in Gmail.`, { retryable: false });
     }
     return result;
 }
@@ -870,6 +1067,7 @@ const ATTACHMENT_SCHEMA = {
         mimeType: { type: "string" },
         size: { type: "integer" },
         attachmentId: { type: "string" },
+        partId: { type: "string" },
         omittedIds: OMITTED_IDS_SCHEMA,
     },
 };
@@ -892,6 +1090,7 @@ const MESSAGE_PROPERTIES = {
     body: { type: "string" },
     bodyTruncated: { type: "boolean" },
     bodyFormat: { type: "string", enum: ["text", "html", "none", "unavailable"] },
+    bodyNote: { type: "string", description: "Decoding notice, preserved when the body is truncated." },
     attachments: { type: "array", items: ATTACHMENT_SCHEMA },
     attachmentsOmitted: { type: "integer" },
 };
@@ -1018,7 +1217,7 @@ function tools(client) {
         },
         {
             name: "get_thread",
-            description: "Get a Gmail thread's messages, oldest first, with headers, plain-text bodies capped by maxBodyChars, and attachment names. A long thread pages by cursor.",
+            description: "Get a Gmail thread's messages, oldest first, with headers, plain-text bodies capped by maxBodyChars, and attachment metadata. Read attachments with get_attachment using partId. A long thread pages by cursor.",
             annotations: readOnly,
             inputSchema: input({
                 threadId: idProperty("Thread id from search_threads or a message's threadId."),
@@ -1079,7 +1278,7 @@ function tools(client) {
         },
         {
             name: "get_message",
-            description: "Get one Gmail message with headers, its plain-text body (HTML converted only when no text part exists), and attachment metadata. Never downloads attachments.",
+            description: "Get one Gmail message with headers, its plain-text body (HTML converted only when no text part exists), and attachment metadata. Read attachments with get_attachment using partId.",
             annotations: readOnly,
             inputSchema: input({
                 messageId: idProperty("Message id from get_thread, or a draft's messageId."),
@@ -1108,6 +1307,58 @@ function tools(client) {
                 return message;
             },
         },
+        {
+            name: "get_attachment",
+            description: "Read a Gmail attachment by immutable partId: text with its charset, or small binaries as standard base64 for Drive create_file. Refuses oversized downloads; text is capped by maxChars and the whole result by maxBytes.",
+            annotations: readOnly,
+            inputSchema: {
+                ...input({
+                    messageId: idProperty("Message id from get_message, get_thread, or get_draft."),
+                    partId: {
+                        type: "string",
+                        maxLength: ID_BYTES,
+                        description: "Immutable partId from the attachment listing, including an empty root id. Preferred; authoritative when attachmentId is also supplied.",
+                    },
+                    attachmentId: {
+                        type: "string",
+                        minLength: 1,
+                        maxLength: ATTACHMENT_ID_BYTES,
+                        pattern: ID_PATTERN,
+                        description: "Alternative attachmentId from the listing. Gmail can rotate it between reads; prefer partId.",
+                    },
+                    maxChars: {
+                        type: "integer",
+                        minimum: 1,
+                        maximum: MAX_BODY_CHARS,
+                        description: `Text code points kept; defaults to ${DEFAULT_MESSAGE_BODY_CHARS}. Longer text ends with a truncation marker. Ignored for binaries.`,
+                    },
+                    maxBytes: {
+                        type: "integer",
+                        minimum: MIN_ATTACHMENT_RESULT_BYTES,
+                        maximum: MAX_ATTACHMENT_RESULT_BYTES,
+                        description: `Whole-result UTF-8 JSON byte budget; defaults to ${RESULT_BUDGET_BYTES}. Raise it only for a direct call_tool; execute_code cannot receive large results.`,
+                    },
+                }, ["messageId"]),
+                anyOf: [{ required: ["partId"] }, { required: ["attachmentId"] }],
+            },
+            outputSchema: {
+                type: "object",
+                properties: {
+                    messageId: { type: "string" },
+                    partId: { type: "string" },
+                    omittedIds: OMITTED_IDS_SCHEMA,
+                    filename: { type: "string" },
+                    mimeType: { type: "string" },
+                    size: { type: "integer" },
+                    format: { type: "string", enum: ["text", "base64", "unavailable"] },
+                    content: { type: "string" },
+                    contentTruncated: { type: "boolean" },
+                    note: { type: "string" },
+                },
+                required: ["messageId", "filename", "mimeType", "format", "contentTruncated"],
+            },
+            handler: async (args, ctx) => await readAttachment(client, ctx, args),
+        },
         {
             name: "list_labels",
             description: "List the user's Gmail labels, system and user-created, with the ids messages carry; no message counts. Search by name with label: in search_threads.",
@@ -1271,7 +1522,7 @@ function tools(client) {
             name: "create_draft",
             description: "Create a Gmail draft, optionally as a reply in an existing thread. It is saved, never sent: the user reviews and sends it in Gmail.",
             // Additive: a new draft changes nothing that existed. Not read-only, so
-            // program calls require a trusted pool; other writes use
+            // program calls require a writable endpoint; other writes use
             // call_destructive_tool. The host controls approval.
             annotations: { readOnlyHint: false, destructiveHint: false },
             inputSchema: input({
@@ -1384,7 +1635,7 @@ function usageGuide(purpose, instructions) {
  *
  * `gmail.compose` technically allows sending; this connection never does,
  * because no tool reaches a send method. Drafts are additive writes the host
- * approves through call_destructive_tool or a trusted program.
+ * approves through call_destructive_tool or a program on a writable endpoint.
  */
 export const gmail = asProviderFactory({
     name: "gmail",
@@ -1413,7 +1664,7 @@ function gmailConnector(id, options) {
         notFound: "absent",
         connection,
     });
-    return api(id, {
+    return workspaceConnector(connection, api(id, {
         ...defined({
             callAdmission: options.callAdmission,
             maxResultBytes: options.maxResultBytes,
@@ -1430,7 +1681,9 @@ function gmailConnector(id, options) {
         // Every tool's result passes the whole-size postcondition on its way out.
         tools: tools(client).map((tool) => ({
             ...tool,
-            handler: async (args, ctx) => deliverable(tool.name, await tool.handler(args, ctx)),
+            handler: async (args, ctx) => deliverable(tool.name, await tool.handler(args, ctx), tool.name === "get_attachment" && typeof args["maxBytes"] === "number"
+                ? args["maxBytes"]
+                : RESULT_BUDGET_BYTES),
         })),
-    });
+    }));
 }

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

@@ -1,9 +1,9 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "# Gmail usage (draft-only)\n\nActs as the signed-in person's own Gmail through Workspace delegation: read mail and write drafts, never send.\n\nConnection purpose: \n\n## Whose mailbox\n\nEvery call reads and writes the mailbox deployment config maps the caller\nto. No argument names a mailbox. A call with none mapped fails\n`auth_required`; only an operator can change the mapping.\n\n## Reading\n\n- `search_threads` takes Gmail search syntax; reuse the person's own\n  phrasing (`from:`, `subject:`, `newer_than:7d`, `is:unread`,\n  `label:`). Page with `page.nextCursor` and the same query.\n- `get_thread` returns messages oldest first with bodies capped by\n  `maxBodyChars`; a cut body ends with a truncation marker. A long thread\n  pages: follow `page.nextCursor` until `hasMore` is false, with the same\n  arguments. `conflict` means the thread changed under the cursor; read it\n  again from the start. Reduce inside\n  `execute_code` before returning a long thread.\n- Every result stays under 192 KiB; `list_labels` pages the same way.\n- Attachments are listed by name, type, and size only; none is downloaded.\n  An attached or forwarded email is an attachment, not the body.\n- `bodyFormat: \"unavailable\"` means Gmail stored the body apart from the\n  message and it is too large to read here; say so rather than summarizing.\n\n## Drafting\n\n- `create_draft` saves a draft and never sends it; tell the person it is\n  waiting in Drafts. There is no send, delete, or label tool.\n- To reply, pass `replyToMessageId`: the draft joins that thread with\n  In-Reply-To and References set, and subject (Re: …) and `to` default\n  from that message's Reply-To, else its From. Keep the Re: subject or Gmail\n  may start a new thread.\n- `update_draft` replaces the body entirely; send the full new text.\n  From, To, Cc, Bcc, Reply-To, Subject, the thread, and reply headers are\n  kept unless restated; no other header is. A draft with attachments or\n  inline images is refused, unchanged — Gmail's update would delete them.\n- Gmail sets From to the mailbox itself; there is no From argument.\n",
+    "content": "# Gmail usage (draft-only)\n\nActs as the signed-in person's own Gmail through Workspace delegation: read mail and write drafts, never send.\n\nConnection purpose: \n\n## Whose mailbox\n\nEvery call reads and writes the mailbox deployment config maps the caller\nto; an agent acts as the owner of the pool it came through, unless the deployment fixes one shared mailbox that every caller, agent or person, acts as. No argument\nnames a mailbox. A call with none mapped, or from an agent whose pool has no\nowner, fails `auth_required`; only an operator can change either.\n\n## Reading\n\n- `search_threads` takes Gmail search syntax; reuse the person's own\n  phrasing (`from:`, `subject:`, `newer_than:7d`, `is:unread`,\n  `label:`). Page with `page.nextCursor` and the same query.\n- `get_thread` returns messages oldest first with bodies capped by\n  `maxBodyChars`; a cut body ends with a truncation marker. A long thread\n  pages: follow `page.nextCursor` until `hasMore` is false, with the same\n  arguments. `conflict` means the thread changed under the cursor; read it\n  again from the start. Reduce inside\n  `execute_code` before returning a long thread.\n- Results default to at most 192 KiB; `list_labels` pages the same way.\n- `get_message` and `get_thread` list attachment metadata. An attached or\n  forwarded email is an attachment, not the body.\n- `bodyFormat: \"unavailable\"` means Gmail stored the body apart from the\n  message and it is too large to read here; say so rather than summarizing.\n- `get_message`, each `get_thread` message, and `get_draft` return `bodyNote`\n  when decoding falls back to UTF-8 for an unsupported charset. The note\n  survives character and result-byte truncation, including `maxBodyChars: 0`\n  when inline body data is decoded. It counts toward the result's byte limit.\n\n## Attachments\n\n- `get_attachment` takes `messageId` and the listing's immutable `partId`.\n  Prefer `partId`, which stays stable across message reads, including an\n  empty id for a root attachment. `attachmentId` is an alternative that\n  Gmail can rotate between reads. When both are supplied, `partId` wins and\n  the fresh message's download id is used. Read the listing again after\n  an unknown-id refusal; never store an attachmentId for later use.\n- Small attachments can have inline data and no attachmentId. Use their\n  partId too. Only carried attachment parts can be read, never arbitrary\n  message body parts or blind download ids.\n- Text, JSON, XML, calendar invites, CSV, and `message/rfc822` return\n  `format: \"text\"` and `content` decoded in the declared charset. An unsupported\n  charset produces an explicit `note` that decoding used UTF-8. Message bodies\n  return the notice separately as `bodyNote`.\n  Parsed forwarded emails render From, To, Date, Subject, and their own\n  plain body, else HTML converted to text. Raw forwarded data is preferred\n  when present. A forwarded email without readable text returns an\n  `unavailable` note.\n  `maxChars` defaults to 12,000 code points, at most 100,000. A character\n  or byte cut ends with a truncation marker and `contentTruncated: true`.\n  Reduce attachment text inside `execute_code` before returning it.\n- Binary attachments return `format: \"base64\"` and standard base64 in\n  `content`. Pass it unchanged to Drive `create_file` as `contentBase64`,\n  with `name: filename` and `mimeType`. File creation is a write: use\n  `call_destructive_tool` or a program on a writable endpoint for that step.\n- Downloads, text and binary, are limited to 1 MiB. Declared size is\n  checked before a separate download. Parsed forwarded emails check the sum\n  of descendant sizes before downloading any stored body, and return that\n  sum as `size`. Attachment data must match both the message part's declared\n  size and the download response's size when supplied; inconsistent payloads\n  fail rather than return incomplete files. Binary content must also fit the\n  whole-result `maxBytes`, which defaults to 192 KiB. `format: \"unavailable\"`\n  returns a note and no content when it cannot fit. Raising `maxChars`\n  or `maxBytes` cannot bypass the download cap.\n- Raise `maxBytes` only for a direct `call_tool` read, from 64 KiB up to\n  4 MiB, as with Drive `get_file_content`. `execute_code` cannot receive\n  large results; keep the default there. Direct-call results may be paged.\n\n## Drafting\n\n- `create_draft` saves a draft and never sends it; tell the person it is\n  waiting in Drafts. There is no send, delete, or label tool.\n- To reply, pass `replyToMessageId`: the draft joins that thread with\n  In-Reply-To and References set, and subject (Re: …) and `to` default\n  from that message's Reply-To, else its From. Keep the Re: subject or Gmail\n  may start a new thread.\n- `update_draft` replaces the body entirely; send the full new text.\n  From, To, Cc, Bcc, Reply-To, Subject, the thread, and reply headers are\n  kept unless restated; no other header is. A draft with attachments or\n  inline images is refused, unchanged — Gmail's update would delete them.\n- Gmail sets From to the mailbox itself; there is no From argument.\n",
     "instructionsHeading": "Connection instructions",
     "fragments": {
         "guide_0": "# Gmail usage (draft-only)\n\nActs as the signed-in person's own Gmail through Workspace delegation: read mail and write drafts, never send.\n\nConnection purpose: ",
-        "guide_1": "\n\n## Whose mailbox\n\nEvery call reads and writes the mailbox deployment config maps the caller\nto. No argument names a mailbox. A call with none mapped fails\n`auth_required`; only an operator can change the mapping.\n\n## Reading\n\n- `search_threads` takes Gmail search syntax; reuse the person's own\n  phrasing (`from:`, `subject:`, `newer_than:7d`, `is:unread`,\n  `label:`). Page with `page.nextCursor` and the same query.\n- `get_thread` returns messages oldest first with bodies capped by\n  `maxBodyChars`; a cut body ends with a truncation marker. A long thread\n  pages: follow `page.nextCursor` until `hasMore` is false, with the same\n  arguments. `conflict` means the thread changed under the cursor; read it\n  again from the start. Reduce inside\n  `execute_code` before returning a long thread.\n- Every result stays under 192 KiB; `list_labels` pages the same way.\n- Attachments are listed by name, type, and size only; none is downloaded.\n  An attached or forwarded email is an attachment, not the body.\n- `bodyFormat: \"unavailable\"` means Gmail stored the body apart from the\n  message and it is too large to read here; say so rather than summarizing.\n\n## Drafting\n\n- `create_draft` saves a draft and never sends it; tell the person it is\n  waiting in Drafts. There is no send, delete, or label tool.\n- To reply, pass `replyToMessageId`: the draft joins that thread with\n  In-Reply-To and References set, and subject (Re: …) and `to` default\n  from that message's Reply-To, else its From. Keep the Re: subject or Gmail\n  may start a new thread.\n- `update_draft` replaces the body entirely; send the full new text.\n  From, To, Cc, Bcc, Reply-To, Subject, the thread, and reply headers are\n  kept unless restated; no other header is. A draft with attachments or\n  inline images is refused, unchanged — Gmail's update would delete them.\n- Gmail sets From to the mailbox itself; there is no From argument.\n"
+        "guide_1": "\n\n## Whose mailbox\n\nEvery call reads and writes the mailbox deployment config maps the caller\nto; an agent acts as the owner of the pool it came through, unless the deployment fixes one shared mailbox that every caller, agent or person, acts as. No argument\nnames a mailbox. A call with none mapped, or from an agent whose pool has no\nowner, fails `auth_required`; only an operator can change either.\n\n## Reading\n\n- `search_threads` takes Gmail search syntax; reuse the person's own\n  phrasing (`from:`, `subject:`, `newer_than:7d`, `is:unread`,\n  `label:`). Page with `page.nextCursor` and the same query.\n- `get_thread` returns messages oldest first with bodies capped by\n  `maxBodyChars`; a cut body ends with a truncation marker. A long thread\n  pages: follow `page.nextCursor` until `hasMore` is false, with the same\n  arguments. `conflict` means the thread changed under the cursor; read it\n  again from the start. Reduce inside\n  `execute_code` before returning a long thread.\n- Results default to at most 192 KiB; `list_labels` pages the same way.\n- `get_message` and `get_thread` list attachment metadata. An attached or\n  forwarded email is an attachment, not the body.\n- `bodyFormat: \"unavailable\"` means Gmail stored the body apart from the\n  message and it is too large to read here; say so rather than summarizing.\n- `get_message`, each `get_thread` message, and `get_draft` return `bodyNote`\n  when decoding falls back to UTF-8 for an unsupported charset. The note\n  survives character and result-byte truncation, including `maxBodyChars: 0`\n  when inline body data is decoded. It counts toward the result's byte limit.\n\n## Attachments\n\n- `get_attachment` takes `messageId` and the listing's immutable `partId`.\n  Prefer `partId`, which stays stable across message reads, including an\n  empty id for a root attachment. `attachmentId` is an alternative that\n  Gmail can rotate between reads. When both are supplied, `partId` wins and\n  the fresh message's download id is used. Read the listing again after\n  an unknown-id refusal; never store an attachmentId for later use.\n- Small attachments can have inline data and no attachmentId. Use their\n  partId too. Only carried attachment parts can be read, never arbitrary\n  message body parts or blind download ids.\n- Text, JSON, XML, calendar invites, CSV, and `message/rfc822` return\n  `format: \"text\"` and `content` decoded in the declared charset. An unsupported\n  charset produces an explicit `note` that decoding used UTF-8. Message bodies\n  return the notice separately as `bodyNote`.\n  Parsed forwarded emails render From, To, Date, Subject, and their own\n  plain body, else HTML converted to text. Raw forwarded data is preferred\n  when present. A forwarded email without readable text returns an\n  `unavailable` note.\n  `maxChars` defaults to 12,000 code points, at most 100,000. A character\n  or byte cut ends with a truncation marker and `contentTruncated: true`.\n  Reduce attachment text inside `execute_code` before returning it.\n- Binary attachments return `format: \"base64\"` and standard base64 in\n  `content`. Pass it unchanged to Drive `create_file` as `contentBase64`,\n  with `name: filename` and `mimeType`. File creation is a write: use\n  `call_destructive_tool` or a program on a writable endpoint for that step.\n- Downloads, text and binary, are limited to 1 MiB. Declared size is\n  checked before a separate download. Parsed forwarded emails check the sum\n  of descendant sizes before downloading any stored body, and return that\n  sum as `size`. Attachment data must match both the message part's declared\n  size and the download response's size when supplied; inconsistent payloads\n  fail rather than return incomplete files. Binary content must also fit the\n  whole-result `maxBytes`, which defaults to 192 KiB. `format: \"unavailable\"`\n  returns a note and no content when it cannot fit. Raising `maxChars`\n  or `maxBytes` cannot bypass the download cap.\n- Raise `maxBytes` only for a direct `call_tool` read, from 64 KiB up to\n  4 MiB, as with Drive `get_file_content`. `execute_code` cannot receive\n  large results; keep the default there. Direct-call results may be paged.\n\n## Drafting\n\n- `create_draft` saves a draft and never sends it; tell the person it is\n  waiting in Drafts. There is no send, delete, or label tool.\n- To reply, pass `replyToMessageId`: the draft joins that thread with\n  In-Reply-To and References set, and subject (Re: …) and `to` default\n  from that message's Reply-To, else its From. Keep the Re: subject or Gmail\n  may start a new thread.\n- `update_draft` replaces the body entirely; send the full new text.\n  From, To, Cc, Bcc, Reply-To, Subject, the thread, and reply headers are\n  kept unless restated; no other header is. A draft with attachments or\n  inline images is refused, unchanged — Gmail's update would delete them.\n- Gmail sets From to the mailbox itself; there is no From argument.\n"
     }
 };

package/dist/providers/linear/index.js

@@ -302,7 +302,7 @@ export const linear = defineProvider({
         // the summary without the description.
         const accessNote = access === "read-only"
             ? "Read-only connection: bound to Linear's read-only endpoint, whose token is scope-limited downstream, so every write fails at Linear regardless of arguments. Route writes to a connector configured for read-write access."
-            : "Read-write connection: treat every `save_`, `create_`, `delete_`, `resolve_`, `submit_`, and `merge_` operation as a write. Connecta classifies the maintained writes explicitly and enforces the configured pool trust policy. Unknown tools without an explicit, uncontradicted read annotation fail closed.";
+            : "Read-write connection: treat every `save_`, `create_`, `delete_`, `resolve_`, `submit_`, and `merge_` operation as a write. Connecta classifies the maintained writes explicitly, and a read-only endpoint refuses them. Unknown tools without an explicit, uncontradicted read annotation fail closed.";
         return remoteMcp(id, {
             url: LINEAR_MCP_ENDPOINTS[access],
             ...provider.connectorOptions,

package/dist/providers/mixpanel/index.d.ts

@@ -2,7 +2,7 @@ import { type RemoteMcpAuth } from "../../connectors/remote-mcp.js";
 import type { ConnectorCallAdmissionPolicy } from "../../types.js";
 export type MixpanelRegion = "us" | "eu" | "in";
 export declare const MIXPANEL_MCP_ENDPOINTS: Readonly<Record<MixpanelRegion, string>>;
-export interface MixpanelOptions {
+interface MixpanelCommonOptions {
     /**
      * Human-readable display name; defaults to "Mixpanel (<region>)". The region
      * rides the title because a project lives in exactly one residency and
@@ -18,25 +18,40 @@ export interface MixpanelOptions {
      * region answers empty rather than wrong, which reads as an empty project.
      */
     region?: MixpanelRegion;
-    /**
-     * OAuth by default; static headers support Mixpanel service accounts, and
-     * `{ type: "credential" }` takes the same service account as an
-     * operator-managed `username:secret` that Connecta frames for the endpoint.
-     */
-    auth?: RemoteMcpAuth;
     /** Account-specific conventions appended to the maintained provider guide. */
     instructions?: string;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
     /**
-     * Optional per-runtime policy. There is no default: Mixpanel meters its MCP
-     * server per user per hour, and a per-runtime counter over-counts one runtime
-     * serving many users and under-counts many runtimes sharing one credential.
-     * Only an operator who knows the account can pick a number worth enforcing.
+     * Optional per-runtime policy. API mode defaults to 60 calls/hour and five
+     * concurrent calls across all tools and projects. MCP mode has no default:
+     * its per-user hourly quota cannot be modeled by one per-runtime counter.
      */
     callAdmission?: ConnectorCallAdmissionPolicy;
 }
-/** A maintained Mixpanel hosted-MCP connection. */
+/** The default hosted MCP connection. Existing auth configurations still work. */
+export interface MixpanelMcpOptions extends MixpanelCommonOptions {
+    via?: "mcp";
+    /**
+     * OAuth by default; static headers support Mixpanel service accounts, and
+     * `{ type: "credential" }` takes the same service account as an
+     * operator-managed `username:secret` that Connecta frames for the endpoint.
+     */
+    auth?: RemoteMcpAuth;
+    defaultProjectId?: never;
+}
+/** REST APIs using an operator-managed username:secret service account. */
+export interface MixpanelApiOptions extends MixpanelCommonOptions {
+    via: "api";
+    auth: {
+        type: "credential";
+    };
+    /** Fills an omitted project_id. Explicit ids still reach other granted projects. */
+    defaultProjectId?: number;
+}
+export type MixpanelOptions = MixpanelMcpOptions | MixpanelApiOptions;
+/** Mixpanel hosted MCP by default, or service-account REST with via: "api". */
 export declare const mixpanel: import("../../provider.js").ProviderFactory<MixpanelOptions>;
 /** @deprecated Read `mixpanel.definition.classify` instead. Kept for existing imports. */
 export declare const MIXPANEL_VETTED_CATALOG: import("../../catalog-drift.js").VettedCatalog;
+export {};