@zackbart/connecta 0.34.0 → 0.35.0

package/dist/providers/gmail/tools.js

@@ -0,0 +1,1435 @@
+// Curated Gmail workflows over real Effect declarations and the standard kit boundary.
+import { Effect, Option } from "effect";
+import { defined } from "../../connectors/api-connector.js";
+import { ConnectorCallError } from "../../errors.js";
+import { Refusal, toConnectorCallError } from "../../http/errors.js";
+import { googleClient } from "../_shared/google/kit.js";
+import { RESULT_BUDGET_BYTES, clampText, jsonBytes } from "../_shared/google/result-size.js";
+import { encodeForAgent, redactBeforeCut, redactSentSecrets } from "../../sent-secrets.js";
+import { errors, GMAIL, gmailBodyProvenance } from "./api.js";
+import { read, write } from "../../http/tools.js";
+import { boundCursor } from "../../http/paging.js";
+import { fieldsProblem, selectFields } from "../../http/fields.js";
+import { Operation } from "../../runtime/call.js";
+import { index } from "./lib/index.js";
+import { inputs, outputs, rows } from "./lib/schemas.js";
+import { threadingIds } from "./lib/threading.js";
+/**
+ * Each summary row costs one metadata read, so a page stays small. Gmail's
+ * own list maximum is 500.
+ */
+const MAX_PAGE_SIZE = 25;
+const DEFAULT_PAGE_SIZE = 10;
+/** Bodies are capped per message; a thread multiplies this. */
+const DEFAULT_THREAD_BODY_CHARS = 3000;
+const DEFAULT_MESSAGE_BODY_CHARS = 12000;
+/** Summary reads in flight at once for one page. */
+const SUMMARY_CONCURRENCY = 5;
+/** A full thread without attachment bodies; Gmail's message cap is 25 MB. */
+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;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function text(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function header(payload, name) {
+    const wanted = name.toLowerCase();
+    for (const entry of asArray(payload["headers"])) {
+        if (entry?.name?.toLowerCase() === wanted)
+            return text(entry.value);
+    }
+    return undefined;
+}
+const ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+};
+function decodeEntities(ctx, value) {
+    const safe = redactBeforeCut(ctx, value);
+    const decoded = safe.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, name) => {
+        if (name[0] === "#") {
+            const code = name[1] === "x" || name[1] === "X" ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+        }
+        return ENTITIES[name.toLowerCase()] ?? entity;
+    });
+    return redactBeforeCut(ctx, decoded);
+}
+/** Readable text from an HTML part that has no plain-text sibling. */
+function htmlToText(ctx, html) {
+    html = redactBeforeCut(ctx, html);
+    return decodeEntities(ctx, html
+        .replace(/<(script|style|head)\b[\s\S]*?<\/\1\s*>/gi, "")
+        .replace(/<br\s*\/?>/gi, "\n")
+        .replace(/<li\b[^>]*>/gi, "\n- ")
+        .replace(/<\/(p|div|tr|li|h[1-6]|blockquote|table)\s*>/gi, "\n")
+        .replace(/<[^>]*>/g, ""))
+        .replace(/[ \t\u00a0]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function base64UrlBytes(data) {
+    const base64 = data.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4));
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function charsetOf(ctx, part) {
+    const type = header(part, "Content-Type") ?? "";
+    if (redactBeforeCut(ctx, type) !== type)
+        return "[redacted]";
+    // 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") {
+            const source = match[2] ?? match[3] ?? "";
+            if (redactBeforeCut(ctx, source) !== source)
+                return "[redacted]";
+            return redactBeforeCut(ctx, source.replace(/\\(.)/g, "$1")).trim();
+        }
+    }
+    return "utf-8";
+}
+/** Bytes as text, with an explicit notice when the declared charset is unsupported. */
+function decodeIn(ctx, part, data) {
+    let bytes;
+    try {
+        bytes = base64UrlBytes(data);
+    }
+    catch {
+        return { text: "" };
+    }
+    return decodeBytes(ctx, part, bytes);
+}
+function decodeBytes(ctx, part, bytes) {
+    const charset = charsetOf(ctx, part);
+    try {
+        return { text: new TextDecoder(charset).decode(bytes) };
+    }
+    catch {
+        return {
+            text: new TextDecoder().decode(bytes),
+            note: `Gmail declared unsupported charset "${clipped(ctx, charset, FIELD_BYTES)}"; decoded as UTF-8.`,
+        };
+    }
+}
+function mimeOf(part) {
+    return String(part["mimeType"] ?? "").toLowerCase();
+}
+/**
+ * Where the message's own content ends and something it carries begins: a
+ * named file, a part disposed as an attachment, or a whole forwarded message.
+ * Everything beneath such a part belongs to it — an attached email's text is
+ * not the message's body.
+ */
+function isAttachment(part) {
+    const mime = mimeOf(part);
+    return (Boolean(text(part["filename"])) ||
+        /^\s*attachment\b/i.test(header(part, "Content-Disposition") ?? "") ||
+        mime === "message/rfc822" ||
+        // Any leaf that is not body text — an unnamed inline image, a calendar
+        // invitation — is carried content, listed rather than dropped. A text
+        // body Gmail stored apart (an attachmentId, no filename) stays a body.
+        (mime !== "" && !mime.startsWith("multipart/") && !BODY_TYPES.has(mime)));
+}
+/** The only parts that can be a message's own body. */
+const BODY_TYPES = new Set(["text/plain", "text/html"]);
+/** How deep a payload is walked; deeper than this is refused, not guessed. */
+const MAX_PART_DEPTH = 20;
+/**
+ * Walk a payload keeping ancestry: the message's own parts, in order, and the
+ * attachment roots, whose subtrees are entered only for a resolved forwarded root.
+ */
+function walk(root, enterAttachmentRoot = false) {
+    const own = [];
+    const attachments = [];
+    const visit = (part, depth) => {
+        if (isAttachment(part) && !(enterAttachmentRoot && depth === 0)) {
+            attachments.push(part);
+            return;
+        }
+        own.push(part);
+        if (depth >= MAX_PART_DEPTH)
+            return;
+        for (const child of asArray(part["parts"]))
+            visit(asRecord(child), depth + 1);
+    };
+    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;
+/**
+ * The message's own text: its first plain part, else its first HTML part as
+ * text. A body Gmail stored apart from the message is fetched from the
+ * attachments endpoint when it is small enough to read; otherwise the result
+ * says so in `bodyFormat` and in the text, never as a silent empty body.
+ */
+function readBody(client, ctx, messageId, payload, max, step) {
+    return Effect.gen(function* () {
+        const own = walk(payload).own;
+        const chosen = ownBody(own);
+        if (!chosen)
+            return { body: "", bodyTruncated: false, bodyFormat: "none" };
+        const format = mimeOf(chosen) === "text/plain" ? "text" : "html";
+        const stored = asRecord(chosen["body"]);
+        let data = text(stored["data"]);
+        const attachmentId = text(stored["attachmentId"]);
+        if (!data && attachmentId) {
+            const size = typeof stored["size"] === "number" ? stored["size"] : undefined;
+            if (max === 0) {
+                return { body: "[… body not read; raise maxBodyChars to read it]", bodyTruncated: true, bodyFormat: format };
+            }
+            if (!messageId || size === undefined || size > MAX_STORED_BODY_BYTES) {
+                return {
+                    body: `[Body of ${size ?? "unknown"} bytes is stored apart from the message and is larger than this connection reads (${MAX_STORED_BODY_BYTES} bytes); open it in Gmail.]`,
+                    bodyTruncated: true,
+                    bodyFormat: "unavailable",
+                };
+            }
+            const fetched = asRecord(yield* client.json({
+                method: "GET",
+                path: `/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`,
+                template: "/messages/{messageId}/attachments/{id}",
+            }, { step }));
+            data = text(fetched["data"]);
+        }
+        const decoded = data ? decodeIn(ctx, chosen, data) : { text: "" };
+        // Uncut: the caller caps it, by characters and by the result's bytes.
+        return {
+            text: format === "html" ? htmlToText(ctx, decoded.text) : decoded.text,
+            bodyFormat: format,
+            ...(decoded.note ? { bodyNote: decoded.note } : {}),
+        };
+    });
+}
+/**
+ * Gmail's ids are short opaque tokens — message and thread ids are sixteen
+ * hex digits, label ids `INBOX` or `Label_123`, attachment ids a few hundred
+ * characters. One far past that is not an id this connection can use. It is
+ * dropped, never cut — a cut id names nothing — and the drop is said out loud:
+ * an object lists the fields it omitted in `omittedIds`, and a list counts
+ * what it left out, so a missing id is never mistaken for an absent one.
+ */
+const ID_BYTES = 256;
+const LABEL_ID_BYTES = 128;
+const ATTACHMENT_ID_BYTES = 1024;
+function idOf(value, maxBytes = ID_BYTES) {
+    const id = text(value);
+    return id !== undefined && jsonBytes(id) <= maxBytes ? id : undefined;
+}
+/**
+ * The usable ids among `fields`, plus `omittedIds` naming each field Gmail
+ * sent an id for that was too long to return.
+ */
+function ids(fields) {
+    const kept = {};
+    const omitted = [];
+    for (const [name, [value, maxBytes]] of Object.entries(fields)) {
+        const id = name === "partId" ? partIdOf(value) : idOf(value, maxBytes);
+        if (id !== undefined)
+            kept[name] = id;
+        else if (text(value) !== undefined)
+            omitted.push(name);
+    }
+    return omitted.length > 0 ? { ...kept, omittedIds: omitted } : kept;
+}
+/** At most this many label ids per message; the rest are counted. */
+const MAX_LISTED_LABELS = 20;
+/** Usable label ids, at most twenty, and how many were left out either way. */
+function labelsOf(labelIds) {
+    const usable = labelIds.filter((id) => idOf(id, LABEL_ID_BYTES) !== undefined);
+    const listed = usable.slice(0, MAX_LISTED_LABELS);
+    const omitted = labelIds.length - listed.length;
+    return omitted > 0 ? { labelIds: listed, labelIdsOmitted: omitted } : { labelIds: listed };
+}
+/** Attachment rows listed per message; the rest are counted, not listed. */
+const MAX_LISTED_ATTACHMENTS = 20;
+function attachmentsOf(ctx, payload) {
+    const all = walk(payload).attachments;
+    return {
+        listed: all.slice(0, MAX_LISTED_ATTACHMENTS).map((part) => {
+            const truncated = [];
+            const clip = clipper(ctx, truncated);
+            return compact({
+                filename: clip(text(part["filename"]) ?? "", FIELD_BYTES, "filename"),
+                mimeType: clip(text(part["mimeType"]), FIELD_BYTES, "mimeType"),
+                truncated,
+                size: typeof asRecord(part["body"])["size"] === "number" ? asRecord(part["body"])["size"] : undefined,
+                ...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. */
+function attachmentBytes(client, ctx, messageId, part) {
+    return Effect.gen(function* () {
+        const stored = asRecord(part["body"]);
+        let source = stored;
+        const freshId = text(stored["attachmentId"]);
+        if (freshId) {
+            source = asRecord(yield* client.json({
+                method: "GET",
+                path: `/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(freshId)}`,
+                template: "/messages/{messageId}/attachments/{id}",
+            }, { step: "attachment" }));
+        }
+        const data = source["data"];
+        if (typeof data !== "string")
+            return undefined;
+        const provenance = gmailBodyProvenance(source);
+        const validateSize = (length) => {
+            if (provenance?.sizeValid === false ||
+                length !== declaredSize(stored) ||
+                (source["size"] !== undefined && length !== declaredSize(source)))
+                throw new ConnectorCallError("connector_call_failed", "Gmail attachment data does not match its declared byte size.", { retryable: false });
+        };
+        // Check the original bytes before decoding data that the privacy boundary may have changed.
+        if (provenance)
+            validateSize(provenance.originalLength);
+        let bytes;
+        try {
+            bytes = base64UrlBytes(data);
+        }
+        catch {
+            throw new ConnectorCallError("connector_call_failed", "Gmail returned invalid base64url attachment data.", {
+                retryable: false,
+            });
+        }
+        if (!provenance)
+            validateSize(bytes.length);
+        return { bytes, changed: provenance?.changed === true };
+    });
+}
+/** Read only a carried part of a fresh message, never an arbitrary download id. */
+function readAttachment(client, ctx, args) {
+    return Effect.gen(function* () {
+        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(yield* client.json({
+            method: "GET",
+            path: `/messages/${encodeURIComponent(messageId)}`,
+            template: "/messages/{id}",
+            query: { format: "full" },
+        }, { step: "message" }));
+        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 truncated = [];
+        const clip = clipper(ctx, truncated);
+        const base = compact({
+            truncated,
+            messageId,
+            ...ids({ partId: [part["partId"]] }),
+            filename: clip(text(part["filename"]) ?? "", FIELD_BYTES, "filename"),
+            mimeType: clip(text(part["mimeType"]) ?? "application/octet-stream", FIELD_BYTES, "mimeType"),
+            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 content = yield* attachmentBytes(client, ctx, messageId, chosen);
+            if (!content)
+                return unavailable("Gmail returned no readable forwarded message body data; open it in Gmail.");
+            const { bytes } = content;
+            const rendered = decodeBytes(ctx, 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(ctx, 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 content = yield* attachmentBytes(client, ctx, messageId, part);
+            if (!content)
+                return unavailable("Gmail returned no attachment data; open it in Gmail.");
+            const { bytes, changed } = content;
+            if (bytes.length > limit)
+                return tooLarge();
+            if (!isText)
+                return { ...envelope, content: encodeForAgent(ctx, changed ? new TextEncoder().encode("[redacted]") : bytes) };
+            const rendered = decodeBytes(ctx, 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 }) };
+        }
+        // Every secret the request sent is replaced before either cut below.
+        if (decoded.length > maxChars || jsonBytes(decoded) > maxBytes)
+            decoded = redactBeforeCut(ctx, decoded);
+        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(ctx, 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
+ * `RESULT_BUDGET_BYTES` however long and however encoded Google's strings are.
+ */
+const FIELD_BYTES = 512;
+const HEADER_BYTES = 4 * 1024;
+/** A string cut to `maxBytes` of JSON, ending in "…" when it was cut. */
+function clipped(ctx, value, maxBytes) {
+    return (value === undefined ? value : clampText(ctx, value, maxBytes, () => "…"));
+}
+/** Per-record clipping provenance; redaction is not a size truncation. */
+function clipper(ctx, cuts) {
+    return (value, max, path) => {
+        const result = clipped(ctx, value, max);
+        if (value !== undefined && result !== redactBeforeCut(ctx, value))
+            cuts.push(path);
+        return result;
+    };
+}
+/** Cut a body at `max` characters and say so in the text itself, after replacing every
+ * secret the request sent: a cut through an echo leaves a fragment nothing redacts. */
+function capped(ctx, whole, max) {
+    if (whole.length <= max)
+        return { body: whole, bodyTruncated: false };
+    const body = redactBeforeCut(ctx, whole);
+    if (body.length <= max)
+        return { body, bodyTruncated: false };
+    const rest = body.length - max;
+    return {
+        body: `${body.slice(0, max)}\n[… ${rest} more characters truncated; raise maxBodyChars to read them]`,
+        bodyTruncated: true,
+    };
+}
+function isoFromMillis(value) {
+    const millis = typeof value === "string" ? Number(value) : value;
+    if (typeof millis !== "number" || !Number.isFinite(millis))
+        return undefined;
+    const date = new Date(millis);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+function labelIdsOf(message) {
+    return asArray(message["labelIds"]).filter((id) => typeof id === "string");
+}
+/**
+ * One message, projected and finished into the result it belongs to, with
+ * its body cut so that the finished result — measured as it will be sent, not
+ * estimated — fits `budget`. `finish` shapes the message into what the tool
+ * returns (a draft's wrapper, say); the identity for a bare message.
+ */
+function projectMessage(client, ctx, value, maxBodyChars, budget = RESULT_BUDGET_BYTES, finish = (message) => message, bodyStep = "body") {
+    return Effect.gen(function* () {
+        const message = asRecord(value);
+        const payload = asRecord(message["payload"]);
+        const read = yield* readBody(client, ctx, idOf(message["id"]), payload, maxBodyChars, bodyStep);
+        const attachments = attachmentsOf(ctx, payload);
+        const truncated = [];
+        const clip = clipper(ctx, truncated);
+        const headerOf = (name, field = name.toLowerCase()) => clip(header(payload, name), HEADER_BYTES, field);
+        const { omittedIds, ...messageIds } = ids({ id: [message["id"]], threadId: [message["threadId"]] });
+        const projected = compact({
+            truncated,
+            ...messageIds,
+            ...labelsOf(labelIdsOf(message)),
+            date: isoFromMillis(message["internalDate"]),
+            from: headerOf("From"),
+            to: headerOf("To"),
+            cc: headerOf("Cc"),
+            bcc: headerOf("Bcc"),
+            replyTo: headerOf("Reply-To", "replyTo"),
+            subject: headerOf("Subject"),
+            messageIdHeader: headerOf("Message-ID", "messageIdHeader"),
+            inReplyTo: headerOf("In-Reply-To", "inReplyTo"),
+            snippet: text(message["snippet"])
+                ? clip(decodeEntities(ctx, message["snippet"]), HEADER_BYTES, "snippet")
+                : undefined,
+            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,
+        });
+        if (!("text" in read))
+            return finish({ ...projected, body: read.body, bodyTruncated: read.bodyTruncated });
+        // Cap by the caller's characters, then by bytes: cut, measure the finished
+        // result, and cut again by exactly what it is over, until it fits. Every
+        // field is counted as sent — `false` is a byte longer than `true` — so a
+        // body at the exact boundary is not a byte over.
+        const byCharacters = capped(ctx, read.text, maxBodyChars);
+        const build = (body) => finish({ ...projected, body, bodyTruncated: byCharacters.bodyTruncated || body !== byCharacters.body });
+        let body = byCharacters.body;
+        let result = build(body);
+        for (let round = 0; round < 8; round += 1) {
+            const over = jsonBytes(result) - budget;
+            if (over <= 0)
+                return result;
+            const target = Math.max(2, jsonBytes(body) - over);
+            const shorter = clampText(ctx, byCharacters.body, target, resultLimitMarker);
+            if (shorter === body)
+                break;
+            body = shorter;
+            result = build(body);
+        }
+        // Nothing left to cut: the metadata alone is past the budget, and the
+        // tool's final size check refuses it rather than sending it.
+        return result;
+    });
+}
+/** Longest cursor this connection issues; the schemas accept no longer. */
+const MAX_CURSOR_LENGTH = 2048;
+async function digest(value) {
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)));
+    return Array.from(bytes.subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The digest naming one call: its tool and the arguments that shape its pages. */
+function callKey(tool, shape) {
+    return digest(JSON.stringify([tool, shape]));
+}
+/** A cursor of connecta's own claims; Gmail's page token, its only downstream text, arrives redacted. */
+function encodeCursor(ctx, claims) {
+    return encodeForAgent(ctx, JSON.stringify(claims), { url: true, claims: true });
+}
+/** The claims of a cursor this call may resume, or a refusal saying why not. */
+function openCursor(cursor, tool, call) {
+    if (cursor === undefined)
+        return undefined;
+    let claims;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(base64UrlBytes(String(cursor))));
+        if (parsed && typeof parsed === "object" && parsed.v === 1)
+            claims = parsed;
+    }
+    catch {
+        claims = undefined;
+    }
+    if (!claims || typeof claims.t !== "string" || typeof claims.c !== "string") {
+        throw new ConnectorCallError("invalid_args", "That is not a cursor this connection issued. Start again without one.");
+    }
+    if (claims.t !== tool || claims.c !== call) {
+        throw new ConnectorCallError("invalid_args", "That cursor came from a different call — another tool, thread, query, or page size. Pass the cursor this same call returned, or start again without one.");
+    }
+    return claims;
+}
+/** Where to resume in `ids`, checked against what the earlier pages saw. */
+async function resumeAt(ids, claims, what) {
+    if (!claims)
+        return 0;
+    const seen = claims.n;
+    if (typeof seen !== "number" ||
+        !Number.isInteger(seen) ||
+        seen < 1 ||
+        seen > ids.length ||
+        claims.f !== (await digest(JSON.stringify(ids.slice(0, seen))))) {
+        throw new ConnectorCallError("conflict", `The ${what} changed before the previous page ended. Read it again from the start, without a cursor.`);
+    }
+    return seen;
+}
+async function cursorAfter(ctx, ids, seen, tool, call) {
+    return encodeCursor(ctx, { v: 1, t: tool, c: call, n: seen, f: await digest(JSON.stringify(ids.slice(0, seen))) });
+}
+/** A page object whose cursor is as long as any this connection issues. */
+const RESERVED_PAGE = { hasMore: true, nextCursor: "x".repeat(4096) };
+function resultLimitMarker(dropped) {
+    return `\n[… ${dropped} more characters truncated at connecta's ${RESULT_BUDGET_BYTES / 1024} KiB per-result limit; read the rest in Gmail]`;
+}
+/**
+ * Every Gmail result's last check: its whole serialized size, wrapper and
+ * 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, budget = RESULT_BUDGET_BYTES) {
+    const size = jsonBytes(result);
+    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;
+}
+function projectThreadSummary(ctx, value, listedSnippet) {
+    const truncated = [];
+    const clip = clipper(ctx, truncated);
+    const thread = asRecord(value);
+    const messages = asArray(thread["messages"]).map(asRecord);
+    const first = asRecord(messages[0]?.["payload"]);
+    const last = asRecord(messages[messages.length - 1]?.["payload"]);
+    const labels = new Set();
+    let latest;
+    for (const message of messages) {
+        for (const id of labelIdsOf(message))
+            labels.add(id);
+        const at = Number(message["internalDate"]);
+        if (Number.isFinite(at) && (latest === undefined || at > latest))
+            latest = at;
+    }
+    const snippet = text(listedSnippet) ?? text(messages[messages.length - 1]?.["snippet"]);
+    return compact({
+        truncated,
+        ...ids({ id: [thread["id"]] }),
+        subject: clip(header(first, "Subject"), FIELD_BYTES, "subject"),
+        from: clip(header(first, "From"), FIELD_BYTES, "from"),
+        lastFrom: messages.length > 1 ? clip(header(last, "From"), FIELD_BYTES, "lastFrom") : undefined,
+        messageCount: messages.length,
+        lastMessageAt: isoFromMillis(latest),
+        unread: labels.has("UNREAD"),
+        ...labelsOf([...labels]),
+        snippet: snippet ? clip(decodeEntities(ctx, snippet), FIELD_BYTES, "snippet") : undefined,
+    });
+}
+function projectDraftSummary(ctx, value) {
+    const truncated = [];
+    const clip = clipper(ctx, truncated);
+    const draft = asRecord(value);
+    const message = asRecord(draft["message"]);
+    const payload = asRecord(message["payload"]);
+    return compact({
+        truncated,
+        ...ids({ draftId: [draft["id"]], messageId: [message["id"]], threadId: [message["threadId"]] }),
+        subject: clip(header(payload, "Subject"), FIELD_BYTES, "subject"),
+        to: clip(header(payload, "To"), FIELD_BYTES, "to"),
+        updatedAt: isoFromMillis(message["internalDate"]),
+        snippet: text(message["snippet"])
+            ? clip(decodeEntities(ctx, message["snippet"]), FIELD_BYTES, "snippet")
+            : undefined,
+    });
+}
+/** Run `work` over `items`, at most `limit` at a time, keeping order. */
+function mapLimited(items, limit, work) {
+    return Effect.all(items.map(work), { concurrency: limit });
+}
+/** A summary lost between listing and reading is omitted, as on the legacy client. */
+function unlessGone(read) {
+    return Effect.suspend(read).pipe(Effect.catch((failure) => (failure._tag === "StatusFailure" &&
+        toConnectorCallError(failure, errors, { classification: "read", dispatches: [] }).code === "not_found") ||
+        (failure._tag === "Refusal" && failure.error.code === "not_found")
+        ? Effect.succeed(undefined)
+        : Effect.fail(failure)));
+}
+// --- Writing drafts ---------------------------------------------------------------
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+const MAILBOX = /^[^\s@<>()",;:\\[\]]+@[^\s@<>()",;:\\[\]]+$/;
+function refuseLineBreaks(name, value) {
+    if (/[\r\n]/.test(value) || value.includes("\u0000")) {
+        throw new ConnectorCallError("invalid_args", `${name} may not contain a line break.`);
+    }
+}
+/**
+ * RFC 2047 encoded words for header text that is not plain ASCII. Each word
+ * carries at most 45 UTF-8 bytes (60 base64 characters, 72 with its armor),
+ * split only between code points, and words fold onto continuation lines.
+ */
+function encodedWords(value) {
+    if (PRINTABLE_ASCII.test(value))
+        return value;
+    const encoder = new TextEncoder();
+    const words = [];
+    let chunk = "";
+    let size = 0;
+    for (const character of value) {
+        const bytes = encoder.encode(character).length;
+        if (size + bytes > 45 && chunk) {
+            words.push(chunk);
+            chunk = "";
+            size = 0;
+        }
+        chunk += character;
+        size += bytes;
+    }
+    if (chunk)
+        words.push(chunk);
+    return words.map((word) => `=?UTF-8?B?${base64(encoder.encode(word))}?=`).join("\r\n ");
+}
+/** `Name <addr>` or `addr`, display name encoded or quoted as needed. */
+function formatAddress(field, raw) {
+    refuseLineBreaks(field, raw);
+    const trimmed = raw.trim();
+    const named = /^(.*?)\s*<([^<>]+)>$/.exec(trimmed);
+    const address = (named ? named[2] : trimmed).trim();
+    if (!MAILBOX.test(address) || !PRINTABLE_ASCII.test(address)) {
+        throw new ConnectorCallError("invalid_args", `${field} has an entry that is not an email address; use "name@example.com" or "Name <name@example.com>".`);
+    }
+    const display = named?.[1]?.trim() ?? "";
+    const quoted = /^"((?:[^"\\]|\\.)*)"$/.exec(display);
+    const name = (quoted ? quoted[1].replace(/\\(.)/g, "$1") : display).trim();
+    if (!name)
+        return address;
+    if (!PRINTABLE_ASCII.test(name))
+        return `${encodedWords(name)} <${address}>`;
+    return /^[A-Za-z0-9 !#$%&'*+\-/=?^_`{|}~]+$/.test(name)
+        ? `${name} <${address}>`
+        : `"${name.replace(/(["\\])/g, "\\$1")}" <${address}>`;
+}
+function base64(bytes) {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
+}
+/** Base64 body lines of 76 characters, as RFC 2045 requires. */
+function base64Lines(value) {
+    return (base64(new TextEncoder().encode(value)).match(/.{1,76}/g) ?? []).join("\r\n");
+}
+/**
+ * Split an address header into its mailboxes, as RFC 5322 reads it: commas
+ * inside a quoted display name, an angle address, or a comment do not
+ * separate, comments are dropped, and a group (`Team: a@x, b@y;`) contributes
+ * its members. Each mailbox is then checked; a header that does not parse is
+ * refused rather than guessed at, because a wrong split sends mail to the
+ * wrong people.
+ */
+function addressEntries(field, value) {
+    if (!value)
+        return [];
+    const entries = [];
+    let current = "";
+    let quoted = false;
+    let escaped = false;
+    let angle = 0;
+    let comment = 0;
+    let group = false;
+    const flush = () => {
+        const entry = current.replace(/\s+/g, " ").trim();
+        if (entry)
+            entries.push(entry);
+        current = "";
+    };
+    for (const character of value) {
+        if (escaped) {
+            current += character;
+            escaped = false;
+        }
+        else if (quoted) {
+            if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                quoted = false;
+            current += character;
+        }
+        else if (comment > 0) {
+            if (character === "(")
+                comment += 1;
+            else if (character === ")")
+                comment -= 1;
+        }
+        else if (character === '"') {
+            quoted = true;
+            current += character;
+        }
+        else if (character === "(") {
+            comment = 1;
+        }
+        else if (character === "<") {
+            angle += 1;
+            current += character;
+        }
+        else if (character === ">") {
+            angle -= 1;
+            current += character;
+        }
+        else if (angle === 0 && character === ":" && !group) {
+            // A group's display name names nobody; its members follow.
+            group = true;
+            current = "";
+        }
+        else if (angle === 0 && character === ";" && group) {
+            group = false;
+            flush();
+        }
+        else if (angle === 0 && character === ",") {
+            flush();
+        }
+        else {
+            current += character;
+        }
+        if (angle < 0 || angle > 1)
+            break;
+    }
+    if (quoted || escaped || angle !== 0 || comment !== 0 || group) {
+        throw new ConnectorCallError("invalid_args", `${field} is not a well-formed address list.`);
+    }
+    flush();
+    // Validate each one now, with this field's name, before anything is built.
+    for (const entry of entries)
+        formatAddress(field, entry);
+    return entries;
+}
+/**
+ * One RFC 5322 message, base64url-encoded as Gmail's `raw` field wants it.
+ * `Date` and `Message-ID` are Gmail's to set, and so is `From` on a new draft:
+ * Gmail fills it with the mailbox's own address. An update keeps the `From`
+ * the draft already had — a send-as alias the user chose in Gmail — and no
+ * argument can set one, so an agent cannot forge a sender.
+ */
+function buildRawMessage(message) {
+    const lines = [];
+    for (const [name, list] of [
+        ["From", message.from],
+        ["To", message.to],
+        ["Cc", message.cc],
+        ["Bcc", message.bcc],
+        ["Reply-To", message.replyTo],
+    ]) {
+        if (list.length === 0)
+            continue;
+        if (list.length > MAX_RECIPIENTS) {
+            throw new ConnectorCallError("invalid_args", `${name} lists more than ${MAX_RECIPIENTS} recipients.`);
+        }
+        lines.push(`${name}: ${list.map((entry) => formatAddress(name.toLowerCase(), entry)).join(",\r\n ")}`);
+    }
+    if (message.subject !== undefined) {
+        refuseLineBreaks("subject", message.subject);
+        lines.push(`Subject: ${encodedWords(message.subject)}`);
+    }
+    if (message.inReplyTo)
+        lines.push(`In-Reply-To: ${message.inReplyTo}`);
+    if (message.references)
+        lines.push(`References: ${message.references}`);
+    lines.push("MIME-Version: 1.0");
+    const plain = [
+        'Content-Type: text/plain; charset="UTF-8"',
+        "Content-Transfer-Encoding: base64",
+        "",
+        base64Lines(message.body),
+    ];
+    if (message.htmlBody === undefined) {
+        lines.push(...plain);
+    }
+    else {
+        const boundary = `connecta-${crypto.randomUUID()}`;
+        lines.push(`Content-Type: multipart/alternative; boundary="${boundary}"`, "", `--${boundary}`, ...plain, `--${boundary}`, 'Content-Type: text/html; charset="UTF-8"', "Content-Transfer-Encoding: base64", "", base64Lines(message.htmlBody), `--${boundary}--`);
+    }
+    return base64(new TextEncoder().encode(`${lines.join("\r\n")}\r\n`))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** At most this many ancestors ride in References; the newest are kept. */
+const MAX_REFERENCES = 20;
+/** Threading for a reply: the answered message's thread, ids, and sender. */
+function replyThreading(client, messageId) {
+    return Effect.gen(function* () {
+        const message = asRecord(yield* client.json({
+            method: "GET",
+            path: `/messages/${encodeURIComponent(messageId)}`,
+            template: "/messages/{id}",
+            query: {
+                format: "metadata",
+                metadataHeaders: ["Message-ID", "References", "Subject", "From", "Reply-To"],
+            },
+        }, { effect: "read", step: "reply" }));
+        const payload = asRecord(message["payload"]);
+        const id = threadingIds(header(payload, "Message-ID"))[0];
+        const chain = [...threadingIds(header(payload, "References"), true), ...(id ? [id] : [])].slice(-MAX_REFERENCES);
+        const subject = oneLine(header(payload, "Subject"));
+        const replyTo = header(payload, "Reply-To");
+        return {
+            threadId: text(message["threadId"]),
+            inReplyTo: id,
+            references: chain.length > 0 ? chain.join("\r\n ") : undefined,
+            subject: subject === undefined ? undefined : /^re:/i.test(subject) ? subject : `Re: ${subject}`,
+            // Parsed only when the caller did not name recipients, so a sender header
+            // this connection cannot read never blocks a reply addressed explicitly.
+            recipients: () => addressEntries(`The replied-to message's ${replyTo ? "Reply-To" : "From"} (pass to explicitly)`, oneLine(replyTo ?? header(payload, "From"))),
+        };
+    });
+}
+/** A header value read back from Gmail, unfolded before it is written again. */
+function oneLine(value) {
+    return value?.replace(/[\r\n]+\s*/g, " ").trim();
+}
+/**
+ * A draft's id, its message id, and the thread Gmail placed it in. Gmail
+ * answered 2xx, so the draft was saved whatever its answer looks like: an id
+ * it sent that cannot be returned, or none at all, still reads as saved —
+ * with `draftId` absent, `omittedIds` or `note` saying why, and where to find
+ * it — never as a failure that invites saving it again.
+ */
+function projectSavedDraft(value) {
+    const draft = asRecord(value);
+    const message = asRecord(draft["message"]);
+    const saved = ids({ draftId: [draft["id"]], messageId: [message["id"]], threadId: [message["threadId"]] });
+    return compact({
+        ...saved,
+        saved: true,
+        sent: false,
+        note: saved["draftId"] === undefined
+            ? "Gmail saved the draft but returned no id this connection can carry. Find it with list_drafts before changing it; do not create it again."
+            : undefined,
+    });
+}
+function addressList(value) {
+    return Array.isArray(value) ? value.map(String) : undefined;
+}
+/** The MIME types update_draft can rebuild: text, in any multipart shape. */
+const REBUILDABLE = new Set(["text/plain", "text/html", "multipart/alternative", "multipart/mixed"]);
+/**
+ * What in an existing draft update_draft could not carry over, by name.
+ * Gmail's update replaces the whole message, so anything the rebuilt message
+ * would not contain — an attachment, an inline image, a forwarded message, a
+ * calendar invitation — would be deleted for good. Such a draft is refused
+ * instead.
+ */
+function unrebuildable(payload) {
+    const found = [];
+    const visit = (part, depth) => {
+        const mime = mimeOf(part);
+        // A disposition the request's redaction rewrote can no longer prove the part is not carried,
+        // nor can a header whose name it rewrote: that header may be the Content-Disposition or Content-ID.
+        const disposition = header(part, "Content-Disposition");
+        if (isAttachment(part) ||
+            header(part, "Content-ID") ||
+            (mime && !REBUILDABLE.has(mime)) ||
+            disposition?.includes("[redacted]") ||
+            asArray(part["headers"]).some((entry) => text(entry?.name)?.includes("[redacted]"))) {
+            found.push(text(part["filename"]) ?? (mime || "an unnamed part"));
+            return;
+        }
+        const children = asArray(part["parts"]);
+        // Past the depth this inspects, what lies below is unknown, and unknown
+        // content is content the update could delete: refuse rather than assume.
+        if (depth >= MAX_PART_DEPTH && children.length > 0) {
+            found.push(`parts nested more than ${MAX_PART_DEPTH} levels deep`);
+            return;
+        }
+        for (const child of children)
+            visit(asRecord(child), depth + 1);
+    };
+    visit(payload, 0);
+    return found;
+}
+// --- Tools ------------------------------------------------------------------------
+/** Each request a read sends names a step, so a deployment serving it as a write sends each once. */
+const indexedSteps = (prefix, count) => Object.fromEntries(Array.from({ length: count }, (_, index) => [`${prefix}${index}`, "once"]));
+/** Gmail splits a conversation into a new thread past 100 messages. */
+const MAX_THREAD_MESSAGES = 100;
+function declarations(client) {
+    const readOnly = { readOnlyHint: true };
+    const bodyChars = (args, fallback) => typeof args["maxBodyChars"] === "number" ? args["maxBodyChars"] : fallback;
+    // Gmail's own page token, carried inside a cursor bound to this call. It is redacted first:
+    // an agent decodes the cursor, and no later pass reads through its encoding.
+    const gmailPage = (ctx, listing, tool, call) => {
+        const rawToken = listing["nextPageToken"];
+        if (rawToken === undefined || rawToken === "")
+            return { hasMore: false, nextCursor: null };
+        if (typeof rawToken !== "string" ||
+            rawToken.includes("[redacted]") ||
+            /^[a-z][a-z0-9+.-]*:/i.test(rawToken) ||
+            [...rawToken].some((character) => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127))
+            throw new ConnectorCallError("connector_call_failed", "Gmail returned invalid paging metadata.", {
+                retryable: false,
+            });
+        const token = rawToken;
+        const cursor = encodeCursor(ctx, { v: 1, t: tool, c: call, p: redactSentSecrets(ctx, token) });
+        if (cursor.length > MAX_CURSOR_LENGTH) {
+            throw new ConnectorCallError("connector_call_failed", "Gmail answered with a page token too long to carry in a cursor; narrow the query to fit one page.", { retryable: false });
+        }
+        return { hasMore: true, nextCursor: cursor };
+    };
+    const compose = (args, ctx, kept) => Effect.gen(function* () {
+        const reply = args["replyToMessageId"] ? yield* replyThreading(client, String(args["replyToMessageId"])) : kept;
+        // What the caller states wins; then what the draft already had; then
+        // what a reply defaults to. A new draft has nothing kept.
+        const raw = buildRawMessage({
+            from: kept.from ?? [],
+            to: addressList(args["to"]) ?? (kept.to?.length ? kept.to : reply.recipients?.()) ?? [],
+            cc: addressList(args["cc"]) ?? kept.cc ?? [],
+            bcc: addressList(args["bcc"]) ?? kept.bcc ?? [],
+            replyTo: kept.replyTo ?? [],
+            subject: args["subject"] ?? kept.subject ?? reply.subject,
+            body: String(args["body"] ?? ""),
+            htmlBody: typeof args["htmlBody"] === "string" ? args["htmlBody"] : undefined,
+            inReplyTo: reply.inReplyTo,
+            references: reply.references,
+        });
+        return { message: compact({ raw, threadId: reply.threadId }) };
+    });
+    return [
+        {
+            name: "search_threads",
+            writeSteps: { list: "once", ...indexedSteps("row", MAX_PAGE_SIZE) },
+            description: "Search Gmail threads with conversation ids, newest first, using Gmail query syntax; returns subject, senders and snippet. Read each thread with get_thread for message ids and bodies.",
+            annotations: readOnly,
+            run: (args, ctx) => Effect.gen(function* () {
+                const limit = args["limit"] ?? DEFAULT_PAGE_SIZE;
+                const call = yield* Effect.promise(() => callKey("search_threads", {
+                    query: args["query"] ?? null,
+                    includeSpamTrash: args["includeSpamTrash"] === true,
+                    limit,
+                }));
+                const claims = openCursor(args["cursor"], "search_threads", call);
+                const listing = asRecord(yield* client.json({
+                    method: "GET",
+                    path: "/threads",
+                    template: "/threads",
+                    query: {
+                        q: args["query"],
+                        includeSpamTrash: args["includeSpamTrash"],
+                        maxResults: limit,
+                        pageToken: claims?.p,
+                    },
+                }, { step: "list" }));
+                const rows = asArray(listing["threads"]).map(asRecord);
+                const threads = yield* mapLimited(rows.map((row, index) => ({ row, index })), SUMMARY_CONCURRENCY, ({ row, index }) => unlessGone(() => Effect.gen(function* () {
+                    return projectThreadSummary(ctx, yield* client.json({
+                        method: "GET",
+                        path: `/threads/${encodeURIComponent(String(row["id"]))}`,
+                        template: "/threads/{id}",
+                        query: { format: "metadata", metadataHeaders: ["Subject", "From", "Date"] },
+                    }, { step: `row${index}` }), row["snippet"]);
+                })));
+                return compact({
+                    threads: threads.filter((thread) => thread !== undefined),
+                    page: gmailPage(ctx, listing, "search_threads", call),
+                });
+            }),
+        },
+        {
+            name: "get_thread",
+            writeSteps: { thread: "once", ...indexedSteps("body", MAX_THREAD_MESSAGES) },
+            description: "Read a Gmail thread's messages and follow page.nextCursor until page.hasMore is false. Returns headers, capped plain-text bodies and attachment metadata; use get_attachment for attachment content.",
+            annotations: readOnly,
+            run: (args, ctx) => Effect.gen(function* () {
+                const thread = asRecord(yield* client.json({
+                    method: "GET",
+                    path: `/threads/${encodeURIComponent(args["threadId"])}`,
+                    template: "/threads/{id}",
+                    query: { format: "full" },
+                }, { step: "thread" }));
+                const max = bodyChars(args, DEFAULT_THREAD_BODY_CHARS);
+                const call = yield* Effect.promise(() => callKey("get_thread", { threadId: args["threadId"], maxBodyChars: max }));
+                const claims = openCursor(args["cursor"], "get_thread", call);
+                const all = asArray(thread["messages"]);
+                const ids = all.map((message) => JSON.stringify(message));
+                const start = yield* Effect.promise(() => resumeAt(ids, claims, "thread"));
+                // The whole result is budgeted: the wrapper (with the longest cursor
+                // this connection issues) first, then messages and their separators
+                // until the next would not fit. A message alone is projected to fit
+                // beside the wrapper, so a page holds at least one and paging ends.
+                const threadId = idOf(thread["id"]) ?? args["threadId"];
+                let bytes = jsonBytes({ id: threadId, messageCount: all.length, messages: [], page: RESERVED_PAGE });
+                const room = RESULT_BUDGET_BYTES - bytes;
+                const messages = [];
+                let next = start;
+                while (next < all.length) {
+                    const projected = yield* projectMessage(client, ctx, all[next], max, room, undefined, `body${next}`);
+                    const size = jsonBytes(projected) + (messages.length > 0 ? 1 : 0);
+                    if (messages.length > 0 && bytes + size > RESULT_BUDGET_BYTES)
+                        break;
+                    messages.push(projected);
+                    bytes += size;
+                    next += 1;
+                }
+                const hasMore = next < all.length;
+                return {
+                    id: threadId,
+                    messageCount: all.length,
+                    messages,
+                    page: {
+                        hasMore,
+                        nextCursor: hasMore ? yield* Effect.promise(() => cursorAfter(ctx, ids, next, "get_thread", call)) : null,
+                    },
+                };
+            }),
+        },
+        {
+            name: "get_message",
+            writeSteps: { message: "once", body: "once" },
+            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,
+            run: (args, ctx) => Effect.gen(function* () {
+                const message = yield* client.json({
+                    method: "GET",
+                    path: `/messages/${encodeURIComponent(args["messageId"])}`,
+                    template: "/messages/{id}",
+                    query: { format: "full" },
+                }, { step: "message" });
+                return yield* projectMessage(client, ctx, message, bodyChars(args, DEFAULT_MESSAGE_BODY_CHARS));
+            }),
+        },
+        {
+            name: "get_attachment",
+            writeSteps: { message: "once", attachment: "once" },
+            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,
+            run: (args, ctx) => Effect.gen(function* () {
+                return yield* readAttachment(client, ctx, args);
+            }),
+        },
+        {
+            name: "list_labels",
+            description: "List all Gmail labels in one bounded reply with the ids messages carry; truncated reports omitted labels. Uses one mailbox read and no continuation. Search by name with label: in search_threads.",
+            annotations: readOnly,
+            run: (args, ctx) => Effect.gen(function* () {
+                const listing = asRecord(yield* client.json({ method: "GET", path: "/labels", template: "/labels" }));
+                const all = asArray(listing["labels"]);
+                // Gmail's labels endpoint is unpaged. Return that list once rather
+                // than re-downloading it to serve artificial ten-row pages. The
+                // ordinary result bound still applies, with explicit omissions.
+                const labels = [];
+                // A label whose id is too long to use is left out and counted, never
+                // returned with a cut id that would name nothing.
+                let omitted = 0;
+                let bytes = jsonBytes({ labels: [], labelsOmitted: all.length, page: { hasMore: false } });
+                let next = 0;
+                while (next < all.length) {
+                    const label = asRecord(all[next]);
+                    const id = idOf(label["id"], LABEL_ID_BYTES);
+                    if (id === undefined) {
+                        omitted += 1;
+                        next += 1;
+                        continue;
+                    }
+                    const truncated = [];
+                    const row = compact({
+                        truncated,
+                        id,
+                        name: clipper(ctx, truncated)(text(label["name"]), FIELD_BYTES, "name"),
+                        type: label["type"] === "system" ? "system" : label["type"] === "user" ? "user" : undefined,
+                    });
+                    const size = jsonBytes(row) + (labels.length > 0 ? 1 : 0);
+                    if (bytes + size > RESULT_BUDGET_BYTES) {
+                        omitted += all.length - next;
+                        break;
+                    }
+                    labels.push(row);
+                    bytes += size;
+                    next += 1;
+                }
+                return compact({
+                    labels,
+                    labelsOmitted: omitted > 0 ? omitted : undefined,
+                    page: { hasMore: false },
+                });
+            }),
+        },
+        {
+            name: "list_drafts",
+            writeSteps: { list: "once", ...indexedSteps("row", MAX_PAGE_SIZE) },
+            description: "List the user's Gmail drafts, newest first, with subject, recipients, and snippet. Use get_draft for a body.",
+            annotations: readOnly,
+            run: (args, ctx) => Effect.gen(function* () {
+                const limit = args["limit"] ?? DEFAULT_PAGE_SIZE;
+                const call = yield* Effect.promise(() => callKey("list_drafts", { query: args["query"] ?? null, limit }));
+                const claims = openCursor(args["cursor"], "list_drafts", call);
+                const listing = asRecord(yield* client.json({
+                    method: "GET",
+                    path: "/drafts",
+                    template: "/drafts",
+                    query: {
+                        q: args["query"],
+                        maxResults: limit,
+                        pageToken: claims?.p,
+                    },
+                }, { step: "list" }));
+                const rows = asArray(listing["drafts"]).map((row, index) => ({ row: asRecord(row), index }));
+                const drafts = yield* mapLimited(rows, SUMMARY_CONCURRENCY, ({ row, index }) => unlessGone(() => Effect.gen(function* () {
+                    return projectDraftSummary(ctx, yield* client.json({
+                        method: "GET",
+                        path: `/drafts/${encodeURIComponent(String(row["id"]))}`,
+                        template: "/drafts/{id}",
+                        query: { format: "metadata" },
+                    }, { step: `row${index}` }));
+                })));
+                return {
+                    drafts: drafts.filter((draft) => draft !== undefined),
+                    page: gmailPage(ctx, listing, "list_drafts", call),
+                };
+            }),
+        },
+        {
+            name: "get_draft",
+            writeSteps: { draft: "once", body: "once" },
+            description: "Get one Gmail draft's headers and plain-text body by draft id. Reading it never sends it.",
+            annotations: readOnly,
+            run: (args, ctx) => Effect.gen(function* () {
+                const draft = asRecord(yield* client.json({
+                    method: "GET",
+                    path: `/drafts/${encodeURIComponent(args["draftId"])}`,
+                    template: "/drafts/{id}",
+                    query: { format: "full" },
+                }, { step: "draft" }));
+                // The draft was read by the id the caller passed, so that is its id
+                // whatever Gmail echoed back.
+                const draftId = idOf(draft["id"]) ?? args["draftId"];
+                // A draft's message id changes on every update; the draft id does not.
+                // The body is fitted against this finished shape, wrapper and all.
+                return yield* projectMessage(client, ctx, draft["message"], bodyChars(args, DEFAULT_MESSAGE_BODY_CHARS), RESULT_BUDGET_BYTES, 
+                // Omissions name the public field: here the message's `id` is
+                // returned as `messageId`.
+                ({ id, omittedIds, ...message }) => compact({
+                    draftId,
+                    messageId: id,
+                    ...message,
+                    omittedIds: Array.isArray(omittedIds)
+                        ? omittedIds.map((name) => (name === "id" ? "messageId" : name))
+                        : undefined,
+                }));
+            }),
+        },
+        {
+            name: "create_draft",
+            writeSteps: { reply: "once", write: "once" },
+            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 writable endpoint; other writes use
+            // call_destructive_tool. The host controls approval.
+            annotations: { readOnlyHint: false, destructiveHint: false },
+            run: (args, ctx) => Effect.gen(function* () {
+                const draft = yield* client.json({
+                    method: "POST",
+                    path: "/drafts",
+                    template: "/drafts",
+                    body: yield* compose(args, ctx, { threadId: undefined, inReplyTo: undefined, references: undefined }),
+                });
+                return projectSavedDraft(draft);
+            }),
+        },
+        {
+            name: "update_draft",
+            writeSteps: { existing: "once", reply: "once", write: "once" },
+            description: "Replace a Gmail draft's body, keeping its sender, recipients, subject, Reply-To, and thread unless restated. Refuses a draft with attachments. Never sends it.",
+            // Destructive: Gmail replaces the draft's whole message, so the body it
+            // held — possibly typed by the user — is gone. Still a draft, never sent.
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            run: (args, ctx) => Effect.gen(function* () {
+                const draftPath = `/drafts/${encodeURIComponent(args["draftId"])}`;
+                // Read the whole draft before replacing it: Gmail's update takes a
+                // whole message, so whatever the rebuilt one leaves out is deleted.
+                // Kept unless restated: From, To, Cc, Bcc, Reply-To, Subject, the
+                // thread, In-Reply-To, and References. Any other header is not.
+                const existing = asRecord(yield* client.json({ method: "GET", path: draftPath, template: "/drafts/{id}", query: { format: "full" } }, { effect: "read", step: "existing" }));
+                const message = asRecord(existing["message"]);
+                const payload = asRecord(message["payload"]);
+                const lost = unrebuildable(payload);
+                if (lost.length > 0) {
+                    throw new ConnectorCallError("invalid_args", `This draft carries content update_draft cannot rebuild (${lost.slice(0, 5).join(", ")}${lost.length > 5 ? ", …" : ""}), and Gmail's update replaces the whole message, so it would be deleted. Nothing was changed. Edit this draft in Gmail, or write a new one with create_draft.`);
+                }
+                const keep = (name, argument) => args[argument] === undefined
+                    ? addressEntries(`The draft's ${name} (pass ${argument} explicitly)`, oneLine(header(payload, name)))
+                    : undefined;
+                const references = threadingIds(header(payload, "References"), true);
+                const inReplyTo = threadingIds(header(payload, "In-Reply-To"), true);
+                const kept = {
+                    threadId: text(message["threadId"]),
+                    inReplyTo: inReplyTo.length > 0 ? inReplyTo.join("\r\n ") : undefined,
+                    references: references.length > 0 ? references.join("\r\n ") : undefined,
+                    subject: oneLine(header(payload, "Subject")),
+                    from: addressEntries("The draft's From", oneLine(header(payload, "From"))),
+                    replyTo: addressEntries("The draft's Reply-To", oneLine(header(payload, "Reply-To"))),
+                    ...defined({ to: keep("To", "to"), cc: keep("Cc", "cc"), bcc: keep("Bcc", "bcc") }),
+                };
+                const draft = yield* client.json({
+                    method: "PUT",
+                    path: draftPath,
+                    template: "/drafts/{id}",
+                    body: yield* compose(args, ctx, kept),
+                });
+                return projectSavedDraft(draft);
+            }),
+        },
+    ];
+}
+/** Internal size provenance becomes one top-level standard report, before fields narrow it. */
+function standardResult(value, tool) {
+    const cuts = new Set();
+    const visit = (value, path) => {
+        if (Array.isArray(value))
+            return value.map((item) => visit(item, `${path}[]`));
+        if (value === null || typeof value !== "object")
+            return value;
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            const target = (name) => (path ? `${path}.${name}` : name);
+            if (key === "truncated") {
+                for (const field of asArray(child))
+                    cuts.add(target(String(field)));
+            }
+            else if (key === "bodyTruncated" || key === "contentTruncated") {
+                if (child === true)
+                    cuts.add(target(key === "bodyTruncated" ? "body" : "content"));
+            }
+            else if (key === "omittedIds") {
+                for (const name of asArray(child))
+                    cuts.add(target(String(name)));
+            }
+            else if (["labelIdsOmitted", "attachmentsOmitted", "labelsOmitted"].includes(key)) {
+                if (Number(child) > 0)
+                    cuts.add(target(key === "labelsOmitted" && tool === "list_labels" ? "items[]" : key.replace("Omitted", "") + "[]"));
+            }
+            else if (key === "nextCursor" && child === null) {
+                // A terminal page has no cursor.
+            }
+            else
+                out[key] = visit(child, target(key));
+        }
+        return out;
+    };
+    const raw = asRecord(value);
+    const key = tool === "search_threads"
+        ? "threads"
+        : tool === "list_drafts"
+            ? "drafts"
+            : tool === "list_labels"
+                ? "labels"
+                : undefined;
+    const shaped = key ? { ...raw, items: raw[key] } : raw;
+    if (key)
+        delete shaped[key];
+    const result = asRecord(visit(shaped, ""));
+    if (cuts.size)
+        result["truncated"] = [...cuts];
+    return result;
+}
+/** Gmail only reads mail and saves drafts. Sending has no dispatch path. */
+export function gmailTools({ connection }) {
+    return declarations(googleClient(connection, GMAIL.provider, { standard: true, index })).map((declaration) => {
+        const name = declaration.name;
+        const isList = name === "search_threads" || name === "list_labels" || name === "list_drafts";
+        const spec = {
+            name,
+            description: declaration.description,
+            input: inputs[name],
+            output: outputs[name],
+            ...(declaration.writeSteps ? { writeSteps: declaration.writeSteps } : {}),
+            run: (supplied) => Effect.gen(function* () {
+                const active = yield* Effect.serviceOption(Operation);
+                if (Option.isNone(active) || !active.value)
+                    return yield* Effect.die(new Error("Gmail needs its call context."));
+                const ctx = active.value;
+                const { fields, ...args } = supplied;
+                const problem = fieldsProblem(fields, new Set(Object.keys(isList ? rows[name].fields : outputs[name].fields)), isList ? "an item" : "the result");
+                if (problem)
+                    return yield* Effect.fail(new Refusal({ error: problem }));
+                if (args["cursor"] !== undefined)
+                    args["cursor"] = yield* boundCursor.decode(name, args, args["cursor"]);
+                let result = standardResult(yield* declaration.run(args, ctx), name);
+                if (result["page"]?.nextCursor)
+                    result["page"].nextCursor = yield* boundCursor.encode(name, args, result["page"].nextCursor, (json) => encodeForAgent(ctx, json, { url: true, claims: true }));
+                if (isList)
+                    result["items"] = selectFields(result["items"], fields);
+                else {
+                    const { truncated, page } = result;
+                    result = asRecord(selectFields(result, fields));
+                    if (page !== undefined)
+                        result["page"] = page;
+                    // Size provenance describes the full projection even when fields omit the cut value.
+                    if (truncated !== undefined)
+                        result["truncated"] = truncated;
+                }
+                return deliverable(name, result, name === "get_attachment" && typeof args["maxBytes"] === "number" ? args["maxBytes"] : RESULT_BUDGET_BYTES);
+            }).pipe(Effect.catchDefect((defect) => defect instanceof ConnectorCallError ? Effect.fail(new Refusal({ error: defect })) : Effect.die(defect))),
+        };
+        return declaration.annotations.readOnlyHint === true
+            ? read(connection, spec)
+            : write(connection, { ...spec, destructive: declaration.annotations.destructiveHint !== false });
+    });
+}