@zackbart/connecta 0.31.0 → 0.32.0

package/dist/providers/gmail/index.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,14 @@ 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");
+}
+function bodyText(part, decoded) {
+    const body = mimeOf(part) === "text/html" ? htmlToText(decoded.text) : decoded.text;
+    return decoded.note ? `${body}\n[${decoded.note}]` : body;
+}
 /** Gmail stores a large body apart from the message, behind an attachment id. */
 const MAX_STORED_BODY_BYTES = 1024 * 1024;
 /**
@@ -190,11 +218,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 +243,9 @@ 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: bodyText(chosen, decoded), bodyFormat: format };
 }
 /**
  * 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
@@ -428,10 +624,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 +1066,7 @@ const ATTACHMENT_SCHEMA = {
         mimeType: { type: "string" },
         size: { type: "integer" },
         attachmentId: { type: "string" },
+        partId: { type: "string" },
         omittedIds: OMITTED_IDS_SCHEMA,
     },
 };
@@ -1018,7 +1215,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 +1276,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 +1305,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 +1520,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 +1633,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",
@@ -1430,7 +1679,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. 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- 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\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  include the same notice in their text.\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. 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- 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\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  include the same notice in their text.\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 {};

package/dist/providers/mixpanel/index.js

@@ -1,9 +1,11 @@
 import { skill } from "./skill.generated.js";
 import { remoteMcp, withCredentialDefaults } from "../../connectors/remote-mcp.js";
 import { reviewedCatalog } from "../../catalog-drift.js";
-import { keys, optionsOf } from "../../config-schema.js";
+import { keys, optionsOf, variants } from "../../config-schema.js";
 import { PROVIDER_COMMON, REMOTE_MCP_AUTH } from "../../connectors/option-shapes.js";
 import { defineProvider } from "../../provider.js";
+import { apiConnector } from "../../connectors/api-connector.js";
+import { mixpanelRest, MIXPANEL_API_ADMISSION } from "./rest.js";
 export const MIXPANEL_MCP_ENDPOINTS = {
     us: "https://mcp.mixpanel.com/mcp",
     eu: "https://mcp-eu.mixpanel.com/mcp",
@@ -358,18 +360,39 @@ ${regionNote}
 Account purpose: ${purpose}${skill.fragments.guide_1}${accountInstructions ? `\n## ${skill.instructionsHeading}\n\n${accountInstructions}\n` : ""}`;
 }
 /** The closed options mixpanel() accepts; see `assertKnownOptions`. */
-const MIXPANEL_OPTIONS = optionsOf()({ ...PROVIDER_COMMON, ...keys("region"), auth: REMOTE_MCP_AUTH });
-/** A maintained Mixpanel hosted-MCP connection. */
+const MIXPANEL_OPTIONS = variants("via", {
+    mcp: optionsOf()({
+        ...PROVIDER_COMMON,
+        ...keys("region", "via"),
+        auth: REMOTE_MCP_AUTH,
+    }).shape,
+    api: optionsOf()({
+        ...PROVIDER_COMMON,
+        ...keys("region", "via", "defaultProjectId"),
+        auth: variants("type", { credential: optionsOf()(keys("type")).shape }),
+    }).shape,
+}, "mcp");
+/** Mixpanel hosted MCP by default, or service-account REST with via: "api". */
 export const mixpanel = defineProvider({
     name: "mixpanel",
     title: "Mixpanel",
-    kind: "mcp",
+    kind: "dual",
     readme: "Mixpanel",
-    bundle: { "baselineGzip": 131378, "maxGzip": 191378 },
+    bundle: {
+        baselineGzip: 205500,
+        maxGzip: 265500,
+        note: "./providers/mixpanel (#823) adds the REST connector, guarded transport, shared operation index and value-safety engine alongside the unchanged hosted MCP client. The nine-operation reviewed subset was shrunk to depth 3 without descriptions before remeasuring: operations.ts is 1355 B gzip. The provider remeasures at about 205500 B gzip, compared with the 131378 B MCP-only baseline; the cap follows baseline + 60000 B. No new runtime dependencies.",
+    },
     skill,
     options: MIXPANEL_OPTIONS,
     classify: MIXPANEL_CLASSIFICATION,
-    create: mixpanelConnector,
+    create: (id, options, provider) => {
+        const region = options.region ?? "us";
+        if (!Object.hasOwn(MIXPANEL_MCP_ENDPOINTS, region)) {
+            throw new Error('region must be "us", "eu", or "in".');
+        }
+        return options.via === "api" ? mixpanelApi(id, options, provider) : mixpanelConnector(id, options, provider);
+    },
 });
 function mixpanelConnector(id, options, provider) {
     const purpose = options.purpose.trim();
@@ -412,5 +435,34 @@ function mixpanelConnector(id, options, provider) {
     });
     return connector;
 }
+function mixpanelApi(id, options, provider) {
+    if (options.auth?.type !== "credential")
+        throw new Error('via: "api" requires auth: { type: "credential" }.');
+    if (options.defaultProjectId !== undefined &&
+        (!Number.isSafeInteger(options.defaultProjectId) || options.defaultProjectId < 1)) {
+        throw new Error("defaultProjectId must be a positive safe integer.");
+    }
+    const region = options.region ?? "us";
+    const rest = mixpanelRest(region, options.defaultProjectId);
+    const instructions = options.instructions?.trim();
+    return apiConnector(id, {
+        ...provider.connectorOptions,
+        title: options.title ?? `Mixpanel API (${region})`,
+        description: `Mixpanel service-account REST APIs (${region} residency): ${options.purpose}`,
+        credential: {
+            label: "Mixpanel service account",
+            description: "username:secret from Mixpanel organization settings. Import requires Owner or Admin on the target project.",
+            placeholder: "username:secret",
+        },
+        testCredential: rest.testCredential,
+        callAdmission: options.callAdmission ?? MIXPANEL_API_ADMISSION,
+        usageGuide: {
+            content: `# Mixpanel API usage\n\nService-account REST, ${region} residency. Account purpose: ${options.purpose}\n\nDefault project: ${options.defaultProjectId ?? "none; supply project_id"}.${skill.fragments.api}${instructions ? `\n## ${skill.instructionsHeading}\n\n${instructions}\n` : ""}`,
+            summary: `${REGION_COPY[region]} residency, service-account REST. Raw export, user activity, profiles, reports and event import.`,
+            required: true,
+        },
+        tools: rest.tools,
+    });
+}
 /** @deprecated Read `mixpanel.definition.classify` instead. Kept for existing imports. */
 export const MIXPANEL_VETTED_CATALOG = reviewedCatalog(mixpanel.definition.classify, 'defineProvider("mixpanel")');