Skip to content

A personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.

TypeScript
31.9 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { type DefaultTreeAdapterMap, parseFragment } from "parse5";
import { z } from "zod";
import {
  type CalendarEvent,
  calendarRangeSchema,
  type EmailDraft,
  type EventDraft,
  emailDraftSchema,
  eventDraftSchema,
  type Mail,
} from "../../domain/src/index.ts";

const GMAIL = "https://gmail.googleapis.com/gmail/v1/users/me";
const CALENDAR = "https://www.googleapis.com/calendar/v3";
export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
export const MAX_TOTAL_ATTACHMENT_BYTES = 20 * 1024 * 1024;
const MAX_JSON_BYTES = Math.ceil((MAX_ATTACHMENT_BYTES * 4) / 3) + 1024 * 1024;

export class OutcomeUnknownError extends Error {
  readonly code = "outcome_unknown";
  constructor(
    message = "Google may have completed this action. Check Google before trying again.",
  ) {
    super(message);
    this.name = "OutcomeUnknownError";
  }
}

export class GoogleApiError extends Error {
  constructor(
    readonly status: number,
    detail: string,
  ) {
    super(`Google API (${status}): ${detail}`);
    this.name = "GoogleApiError";
  }
}

export class RecurringEventError extends Error {
  readonly status = 422;
  constructor() {
    super(
      "Recurring events cannot be changed here yet. Open Google Calendar to choose one occurrence or the whole series.",
    );
    this.name = "RecurringEventError";
  }
}

export interface CalendarListEntry {
  id: string;
  name: string;
  timeZone: string;
  accessRole: string;
}
export interface ListEventsOptions {
  calendarId?: string;
  timeMin?: string;
  timeMax?: string;
}

interface GmailPart {
  mimeType?: string;
  filename?: string;
  headers?: { name: string; value: string }[];
  body?: { data?: string; size?: number; attachmentId?: string };
  parts?: GmailPart[];
}
const partSchema: z.ZodType<GmailPart> = z.lazy(() =>
  z.object({
    mimeType: z.string().optional(),
    filename: z.string().optional(),
    headers: z.array(z.object({ name: z.string(), value: z.string() })).optional(),
    body: z
      .object({
        data: z.string().optional(),
        size: z.number().nonnegative().optional(),
        attachmentId: z.string().optional(),
      })
      .optional(),
    parts: z.array(partSchema).optional(),
  }),
);
const messageSchema = z.object({
  id: z.string().min(1),
  threadId: z.string().min(1),
  snippet: z.string().default(""),
  internalDate: z.string().optional(),
  labelIds: z.array(z.string()).default([]),
  payload: partSchema.optional(),
});
const googleEventSchema = z.object({
  id: z.string().min(1),
  etag: z.string().optional(),
  recurrence: z.array(z.string()).optional(),
  recurringEventId: z.string().optional(),
  summary: z.string().default("(Untitled event)"),
  start: z.object({
    date: z.string().optional(),
    dateTime: z.string().optional(),
    timeZone: z.string().optional(),
  }),
  end: z.object({ date: z.string().optional(), dateTime: z.string().optional() }),
  location: z.string().default(""),
  description: z.string().default(""),
  attendees: z.array(z.object({ email: z.string() })).default([]),
});
export interface MailAttachment {
  name: string;
  mimeType: string;
  bytes: Uint8Array;
}

function idPath(id: string): string {
  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error("Invalid Google resource ID");
  return encodeURIComponent(id);
}
function calendarPath(calendarId: string): string {
  if (
    !calendarId ||
    calendarId.length > 1024 ||
    Array.from(calendarId).some((char) => char.charCodeAt(0) <= 32 || char.charCodeAt(0) === 127) ||
    calendarId === "." ||
    calendarId === ".."
  )
    throw new Error("Invalid Google calendar ID");
  return `${CALENDAR}/calendars/${encodeURIComponent(calendarId)}/events`;
}
function singleLine(value: string, field: string): string {
  if (Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127))
    throw new Error(`Invalid ${field}: header control characters are not allowed`);
  return value;
}
function decodeBase64url(encoded: string, limit = MAX_ATTACHMENT_BYTES): Buffer {
  if (encoded.length > Math.ceil((limit * 4) / 3) + 4)
    throw new Error("Attachment or message body exceeds the size limit");
  if (!/^[A-Za-z0-9_-]*={0,2}$/.test(encoded))
    throw new Error("Invalid base64url attachment or message body");
  const bytes = Buffer.from(encoded, "base64url");
  if (bytes.length > limit) throw new Error("Attachment or message body is too large");
  if (bytes.toString("base64url") !== encoded.replace(/=+$/, ""))
    throw new Error("Invalid base64url attachment or message body");
  return bytes;
}
function headers(part?: GmailPart): Map<string, string> {
  return new Map((part?.headers ?? []).map(({ name, value }) => [name.toLowerCase(), value]));
}
function decodeHeader(value: string): string {
  // RFC 2047: ignore linear whitespace, including folding, between encoded words.
  return value
    .replace(/(\?=)(?:[ \t]|\r\n[ \t])+(?==\?)/g, "$1")
    .replace(
      /=\?([^?]+)\?([bq])\?([^?]*)\?=/gi,
      (original, charset: string, encoding: string, text: string) => {
        try {
          const bytes =
            encoding.toLowerCase() === "b"
              ? Buffer.from(text, "base64")
              : Buffer.from(
                  text
                    .replace(/_/g, " ")
                    .replace(/=([0-9a-f]{2})/gi, (_, code: string) =>
                      String.fromCharCode(Number.parseInt(code, 16)),
                    ),
                  "latin1",
                );
          return new TextDecoder(charset.split("*")[0]).decode(bytes);
        } catch {
          return original;
        }
      },
    );
}
function decodeSnippet(value: string): string {
  const entities: Record<string, string> = {
    amp: "&",
    lt: "<",
    gt: ">",
    quot: '"',
    apos: "'",
    nbsp: " ",
  };
  return value.replace(
    /&(#x[\da-f]+|#\d+|amp|lt|gt|quot|apos|nbsp);/gi,
    (original, entity: string) => {
      if (!entity.startsWith("#")) return entities[entity.toLowerCase()] ?? original;
      const code =
        entity[1].toLowerCase() === "x"
          ? Number.parseInt(entity.slice(2), 16)
          : Number.parseInt(entity.slice(1), 10);
      // Surrogates are not scalar values: fromCodePoint throws on them, and one
      // such reference in a snippet must not reject the whole message list.
      const scalar = code >= 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff);
      return scalar ? String.fromCodePoint(code) : original;
    },
  );
}
function addresses(value: string): string[] {
  // Comments may contain addresses, nested comments and escaped parentheses.
  // Quoted display names treat parentheses literally instead.
  let uncommented = "";
  let depth = 0;
  let quoted = false;
  let escaped = false;
  // Encoded words are display text, never mailbox syntax, even if their raw
  // payload happens to contain an address or parentheses.
  for (const character of value.replace(/=\?[^?]+\?[bq]\?[^?]*\?=/gi, "")) {
    if (escaped) {
      if (!depth) uncommented += character;
      escaped = false;
    } else if (character === "\\") {
      if (!depth) uncommented += character;
      escaped = true;
    } else if (!depth && character === '"') {
      quoted = !quoted;
      uncommented += character;
    } else if (!quoted && character === "(") {
      if (!depth) uncommented += " ";
      depth++;
    } else if (depth && character === ")") {
      depth--;
    } else if (!depth) uncommented += character;
  }
  // A quoted display name may itself contain an e-mail-looking string; only
  // addresses outside display names count.
  return (
    uncommented
      .replace(/"(?:[^"\\]|\\.)*"\s*(?=<)/g, " ")
      .match(/[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9.-]+/g) ?? []
  );
}
/** Extract text from a parsed HTML tree. Nothing is rendered or fetched. */
function htmlToPlainText(html: string): string {
  const root = parseFragment(html);
  const excluded = new Set([
    "script",
    "style",
    "head",
    "template",
    "noscript",
    "iframe",
    "object",
    "svg",
    "math",
  ]);
  const blocks = new Set([
    "address",
    "article",
    "aside",
    "blockquote",
    "div",
    "footer",
    "form",
    "h1",
    "h2",
    "h3",
    "h4",
    "h5",
    "h6",
    "header",
    "hr",
    "li",
    "main",
    "ol",
    "p",
    "pre",
    "section",
    "table",
    "tr",
    "ul",
  ]);
  const stack: (DefaultTreeAdapterMap["node"] | string)[] = [root];
  const text: string[] = [];
  while (stack.length) {
    const node = stack.pop();
    if (node === undefined) break;
    if (typeof node === "string") {
      text.push(node);
      continue;
    }
    if ("value" in node) {
      text.push(node.value);
      continue;
    }
    if ("tagName" in node) {
      if (excluded.has(node.tagName)) continue;
      if (node.tagName === "br") {
        text.push("\n");
        continue;
      }
      if (blocks.has(node.tagName)) {
        text.push("\n");
        stack.push("\n");
      }
      if (node.tagName === "td" || node.tagName === "th") stack.push("\t");
    }
    if ("childNodes" in node) {
      for (let index = node.childNodes.length - 1; index >= 0; index--)
        stack.push(node.childNodes[index]);
    }
  }
  return text
    .join("")
    .replace(/[\t \u00a0]+/g, " ")
    .replace(/ *\n */g, "\n")
    .replace(/\n{3,}/g, "\n\n")
    .trim();
}
/** UTF-8 when the declared charset is not one TextDecoder knows (`unknown-8bit`, `utf-7`). */
function decoderFor(charset: string): TextDecoder {
  try {
    return new TextDecoder(charset);
  } catch {
    return new TextDecoder();
  }
}
/**
 * Replace unpaired surrogates with U+FFFD so encodeURIComponent cannot throw "URI
 * malformed" on a sender-supplied name. (String.prototype.toWellFormed, but the
 * project targets ES2023.)
 */
const wellFormed = (value: string): string =>
  value.replace(
    /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g,
    "\uFFFD",
  );

function isAttachedPart(part: GmailPart): boolean {
  return (
    Boolean(part.filename) ||
    part.mimeType === "message/rfc822" ||
    headers(part).get("content-disposition")?.split(";")[0].trim().toLowerCase() === "attachment"
  );
}

function mapMessage(message: z.infer<typeof messageSchema>): Mail {
  const metadata = headers(message.payload);
  const plain: string[] = [];
  const html: string[] = [];
  const attachments: string[] = [];
  const visit = (part: GmailPart, depth: number) => {
    if (depth > 30) throw new Error("Gmail message MIME nesting exceeds the limit");
    // Attachments carry their own content (or an attached message); never merge
    // their parts into the parent text. Unattached remote text is hydrated above
    // and still counts as message text.
    const attached = isAttachedPart(part);
    if (attached && part.body?.attachmentId) {
      const name =
        part.filename ||
        (part.mimeType === "message/rfc822" ? "forwarded-message.eml" : "attachment");
      attachments.push(
        `${message.id}:${part.body.attachmentId}:${encodeURIComponent(wellFormed(name))}`,
      );
    }
    if (
      !attached &&
      (part.mimeType === "text/plain" || part.mimeType === "text/html") &&
      part.body?.data
    ) {
      const charset =
        headers(part)
          .get("content-type")
          ?.match(/charset=["']?([^;"'\s]+)/i)?.[1] ?? "utf-8";
      const text = decoderFor(charset).decode(decodeBase64url(part.body.data, 1024 * 1024));
      if (part.mimeType === "text/plain") plain.push(text);
      else html.push(htmlToPlainText(text));
    }
    if (!attached) for (const child of part.parts ?? []) visit(child, depth + 1);
  };
  if (message.payload) visit(message.payload, 0);
  const rawFrom = metadata.get("from") ?? "";
  const from = decodeHeader(rawFrom);
  const address = addresses(rawFrom)[0] ?? from;
  const displayName = from.includes("<")
    ? from.slice(0, from.indexOf("<")).trim().replace(/^"|"$/g, "")
    : "";
  const sender = displayName || address;
  const time = message.internalDate
    ? Number(message.internalDate)
    : Date.parse(metadata.get("date") ?? "");
  const date = new Date(time);
  const body = plain.length
    ? plain.join("\n\n")
    : html.length
      ? html.join("\n\n")
      : decodeSnippet(message.snippet);
  if (body.length > 1024 * 1024) throw new Error("Gmail message text exceeds the 1 MiB limit");
  return {
    id: message.id,
    threadId: message.threadId,
    from: address,
    sender,
    to: addresses(metadata.get("to") ?? ""),
    subject: decodeHeader(metadata.get("subject") ?? "(No subject)"),
    body,
    date: Number.isFinite(date.getTime()) ? date.toISOString() : "",
    unread: message.labelIds.includes("UNREAD"),
    label: message.labelIds.includes("INBOX")
      ? "Inbox"
      : message.labelIds.includes("SENT")
        ? "Sent"
        : "Mail",
    attachments,
  };
}
function mapEvent(value: unknown, calendarId: string, calendarTimeZone = "UTC"): CalendarEvent {
  const event = googleEventSchema.parse(value);
  const allDay = Boolean(event.start.date);
  const start = allDay ? event.start.date : event.start.dateTime;
  const end = allDay ? event.end.date : event.end.dateTime;
  if (!start || !end || !Number.isFinite(Date.parse(start)) || !Number.isFinite(Date.parse(end)))
    throw new Error("Invalid Google event time range");
  return {
    id: event.id,
    calendarId,
    title: event.summary,
    start,
    end,
    allDay,
    timeZone: event.start.timeZone ?? calendarTimeZone,
    location: event.location,
    description: event.description,
    attendees: event.attendees.map((attendee) => attendee.email),
  };
}
function eventBody(draft: EventDraft, patch = false) {
  return {
    summary: draft.title,
    start: draft.allDay
      ? { date: draft.start, ...(patch ? { dateTime: null } : {}) }
      : { dateTime: draft.start, timeZone: draft.timeZone, ...(patch ? { date: null } : {}) },
    end: draft.allDay
      ? { date: draft.end, ...(patch ? { dateTime: null } : {}) }
      : { dateTime: draft.end, timeZone: draft.timeZone, ...(patch ? { date: null } : {}) },
    location: draft.location,
    description: draft.description,
    attendees: draft.attendees.map((email) => ({ email })),
  };
}
function encodedSubject(subject: string): string {
  const chunks: string[] = [];
  let chunk = "";
  for (const char of subject) {
    if (Buffer.byteLength(chunk + char) > 42) {
      chunks.push(chunk);
      chunk = "";
    }
    chunk += char;
  }
  if (chunk) chunks.push(chunk);
  return chunks.map((part) => `=?UTF-8?B?${Buffer.from(part).toString("base64")}?=`).join("\r\n ");
}
function wrapBase64(bytes: Uint8Array): string {
  return (
    Buffer.from(bytes)
      .toString("base64")
      .match(/.{1,76}/g)
      ?.join("\r\n") ?? ""
  );
}
function validateAttachments(attachments: MailAttachment[]): void {
  if (attachments.length > 10) throw new Error("Attachment count exceeds the limit of 10");
  let total = 0;
  for (const attachment of attachments) {
    singleLine(attachment.name, "attachment name");
    if (!attachment.name || Buffer.byteLength(attachment.name) > 180)
      throw new Error("Invalid attachment name length");
    if (!/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/.test(attachment.mimeType))
      throw new Error("Invalid attachment MIME type");
    if (attachment.bytes.length > MAX_ATTACHMENT_BYTES)
      throw new Error("Attachment is too large (10 MiB limit)");
    total += attachment.bytes.length;
  }
  if (total > MAX_TOTAL_ATTACHMENT_BYTES)
    throw new Error("Total attachment size exceeds the 20 MiB limit");
}

async function readJson(response: Response): Promise<unknown> {
  if (Number(response.headers.get("content-length")) > MAX_JSON_BYTES) {
    await response.body?.cancel();
    throw new Error("Google response exceeds the size limit");
  }
  if (!response.body) throw new Error("Google returned an empty response");
  const reader = response.body.getReader();
  const chunks: Uint8Array[] = [];
  let length = 0;
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      length += value.length;
      if (length > MAX_JSON_BYTES) {
        await reader.cancel();
        throw new Error("Google response exceeds the size limit");
      }
      chunks.push(value);
    }
    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
  } finally {
    reader.releaseLock();
  }
}

export class GoogleClient {
  private readonly fetcher: typeof fetch;
  private readonly getAccessToken: () => Promise<string>;
  constructor(options: { getAccessToken: () => Promise<string>; fetch?: typeof fetch }) {
    this.fetcher = options.fetch ?? fetch;
    this.getAccessToken = options.getAccessToken;
  }

  private async mapMessage(message: z.infer<typeof messageSchema>): Promise<Mail> {
    const hydrate = async (part: GmailPart, depth: number): Promise<void> => {
      if (depth > 30) throw new Error("Gmail message MIME nesting exceeds the limit");
      // Attached MIME trees are not part of the parent body. Leave their content
      // lazy, matching the module-level mapMessage visible-text extractor.
      if (isAttachedPart(part)) return;
      if (
        (part.mimeType === "text/plain" || part.mimeType === "text/html") &&
        part.body?.data === undefined &&
        part.body?.attachmentId
      ) {
        if ((part.body.size ?? 0) > 1024 * 1024)
          throw new Error("Gmail message text exceeds the 1 MiB limit");
        const bytes = await this.getAttachment(message.id, part.body.attachmentId);
        if (bytes.length > 1024 * 1024)
          throw new Error("Gmail message text exceeds the 1 MiB limit");
        part.body.data = Buffer.from(bytes).toString("base64url");
      }
      for (const child of part.parts ?? []) await hydrate(child, depth + 1);
    };
    if (message.payload) await hydrate(message.payload, 0);
    return mapMessage(message);
  }

  async getThread(threadId: string): Promise<Mail[]> {
    const thread = z
      .object({ id: z.string(), messages: z.array(messageSchema).default([]) })
      .parse(await this.request(`${GMAIL}/threads/${idPath(threadId)}?format=full`));
    if (thread.id !== threadId || thread.messages.some((message) => message.threadId !== threadId))
      throw new Error("Google returned messages from a different thread");
    return Promise.all(thread.messages.map((message) => this.mapMessage(message)));
  }

  async listCalendars(): Promise<CalendarListEntry[]> {
    const entries: CalendarListEntry[] = [];
    const tokens = new Set<string>();
    let pageToken: string | undefined;
    do {
      const params = new URLSearchParams({ maxResults: "250" });
      if (pageToken) params.set("pageToken", pageToken);
      const result = z
        .object({
          items: z
            .array(
              z.object({
                id: z.string().min(1),
                summary: z.string().default("(Untitled calendar)"),
                summaryOverride: z.string().optional(),
                // Google marks the calendar time zone as optional.
                timeZone: z.string().default("UTC"),
                accessRole: z.string(),
              }),
            )
            .default([]),
          nextPageToken: z.string().min(1).optional(),
        })
        .parse(await this.request(`${CALENDAR}/users/me/calendarList?${params}`));
      entries.push(
        ...result.items.map((calendar) => ({
          id: calendar.id,
          name: calendar.summaryOverride ?? calendar.summary,
          timeZone: calendar.timeZone,
          accessRole: calendar.accessRole,
        })),
      );
      pageToken = result.nextPageToken;
      if (pageToken) {
        if (tokens.has(pageToken) || tokens.size >= 10)
          throw new Error("Google calendar list exceeded the pagination limit");
        tokens.add(pageToken);
      }
    } while (pageToken);
    return entries;
  }

  private async readSingleEvent(
    calendarId: string,
    eventId: string,
  ): Promise<z.infer<typeof googleEventSchema>> {
    const event = googleEventSchema.parse(
      await this.request(`${calendarPath(calendarId)}/${idPath(eventId)}`),
    );
    if (event.id !== eventId) throw new Error("Google returned a different event");
    if (event.recurrence !== undefined || event.recurringEventId !== undefined)
      throw new RecurringEventError();
    return event;
  }

  async validateSingleEvent(calendarId: string, eventId: string): Promise<void> {
    await this.readSingleEvent(calendarId, eventId);
  }

  async reviewEvent(
    calendarId: string,
    eventId: string,
  ): Promise<{ event: CalendarEvent; version: string }> {
    const current = await this.readSingleEvent(calendarId, eventId);
    const version = this.eventVersion(current);
    const timeZone =
      current.start.timeZone ??
      z
        // Google marks the calendar time zone as optional.
        .object({ timeZone: z.string().min(1).default("UTC") })
        .parse(
          await this.request(`${CALENDAR}/users/me/calendarList/${encodeURIComponent(calendarId)}`),
        ).timeZone;
    return { event: mapEvent(current, calendarId, timeZone), version };
  }

  private eventVersion(event: z.infer<typeof googleEventSchema>, expectedVersion?: string): string {
    if (!event.etag?.trim()) throw new Error("Google event has no ETag; prepare a fresh review");
    const version = singleLine(event.etag, "event ETag");
    if (expectedVersion !== undefined && version !== expectedVersion)
      throw new GoogleApiError(409, "This event changed since review. Prepare a new action.");
    return version;
  }

  private async request(
    url: string,
    method = "GET",
    body?: unknown,
    conditionalHeaders: Record<string, string> = {},
  ): Promise<unknown> {
    const write = method !== "GET";
    // Credential failures happen before dispatch, so their outcome is definite.
    const token = await this.getAccessToken();
    if (!token || /[\r\n]/.test(token))
      throw new Error("Google access token is missing or invalid; reconnect Google");
    let response: Response;
    try {
      response = await this.fetcher(url, {
        method,
        headers: {
          Authorization: `Bearer ${token}`,
          Accept: "application/json",
          ...(body === undefined ? {} : { "Content-Type": "application/json" }),
          ...conditionalHeaders,
        },
        body: body === undefined ? undefined : JSON.stringify(body),
        signal: AbortSignal.timeout(30000),
        redirect: "error",
      });
    } catch {
      if (write) throw new OutcomeUnknownError();
      throw new Error("Could not reach Google; check the connection and try again");
    }
    if (write && (response.status >= 500 || response.status === 408)) {
      try {
        await response.body?.cancel();
      } catch {
        throw new OutcomeUnknownError();
      }
      throw new OutcomeUnknownError();
    }
    if (!response.ok) {
      let detail = response.statusText || "Request failed";
      try {
        const result = z
          .object({ error: z.object({ message: z.string() }) })
          .safeParse(await readJson(response));
        if (result.success) detail = result.data.error.message.slice(0, 500);
      } catch {
        /* Preserve the definite HTTP rejection even if its body is not JSON. */
      }
      throw new GoogleApiError(response.status, detail);
    }
    if (method === "DELETE" && response.status === 204) return undefined;
    try {
      return await readJson(response);
    } catch {
      if (write) throw new OutcomeUnknownError();
      throw new Error("Google returned an invalid or oversized response");
    }
  }

  /** The latest 30 matching messages. Permission/read failures propagate visibly. */
  async listMail(query = "in:inbox"): Promise<Mail[]> {
    const params = new URLSearchParams({ maxResults: "30", q: query });
    const list = z
      .object({ messages: z.array(z.object({ id: z.string() })).default([]) })
      .parse(await this.request(`${GMAIL}/messages?${params}`));
    return Promise.all(
      list.messages
        .slice(0, 30)
        .map(async ({ id }) =>
          this.mapMessage(
            messageSchema.parse(await this.request(`${GMAIL}/messages/${idPath(id)}?format=full`)),
          ),
        ),
    );
  }

  /** At most 100 occurrences in a bounded window, beginning at local midnight by default. */
  async listEvents(options: ListEventsOptions = {}): Promise<CalendarEvent[]> {
    return (await this.listEventsPage(options)).events;
  }

  /** Retain the provider's completeness marker without fetching additional pages. */
  async listEventsPage(options: ListEventsOptions = {}) {
    const calendarId = options.calendarId ?? "primary";
    const path = calendarPath(calendarId);
    const midnight = new Date();
    midnight.setHours(0, 0, 0, 0);
    const timeMin = options.timeMin ?? midnight.toISOString();
    const timestamp = z.iso.datetime({ offset: true });
    if (!timestamp.safeParse(timeMin).success)
      throw new Error("Invalid calendar timeMin: use a date-time with an explicit offset");
    const timeMax =
      options.timeMax ?? new Date(Date.parse(timeMin) + 31 * 24 * 60 * 60 * 1000).toISOString();
    if (!timestamp.safeParse(timeMax).success)
      throw new Error("Invalid calendar timeMax: use a date-time with an explicit offset");
    calendarRangeSchema.parse({ timeMin, timeMax });
    const params = new URLSearchParams({
      maxResults: "100",
      singleEvents: "true",
      orderBy: "startTime",
      timeMin,
      timeMax,
    });
    const result = z
      .object({
        items: z.array(z.unknown()).default([]),
        timeZone: z.string().default("UTC"),
        nextPageToken: z.string().min(1).optional(),
      })
      .parse(await this.request(`${path}?${params}`));
    return {
      events: result.items.slice(0, 100).map((item) => mapEvent(item, calendarId, result.timeZone)),
      truncated: Boolean(result.nextPageToken) || result.items.length > 100,
    };
  }

  async getAttachment(messageId: string, attachmentId: string): Promise<Uint8Array> {
    const data = z
      .object({ data: z.string(), size: z.number().int().nonnegative().optional() })
      .parse(
        await this.request(
          `${GMAIL}/messages/${idPath(messageId)}/attachments/${idPath(attachmentId)}`,
        ),
      );
    if (data.size !== undefined && data.size > MAX_ATTACHMENT_BYTES)
      throw new Error("Attachment is too large (10 MiB limit)");
    const bytes = decodeBase64url(data.data);
    if (data.size !== undefined && data.size !== bytes.length)
      throw new Error("Google attachment size does not match its actual byte length");
    return new Uint8Array(bytes);
  }

  async sendEmail(
    input: EmailDraft,
    attachments: MailAttachment[],
  ): Promise<{ id: string; threadId?: string }> {
    const draft = emailDraftSchema.parse(input);
    singleLine(draft.subject, "subject");
    for (const address of [...draft.to, ...draft.cc, ...draft.bcc])
      singleLine(address, "recipient");
    validateAttachments(attachments);
    if (draft.threadId && !draft.replyToMessageId)
      throw new Error("Replies require replyToMessageId to resolve the source message headers");
    let threadId: string | undefined;
    const replyHeaders: string[] = [];
    if (draft.replyToMessageId) {
      const params = new URLSearchParams({ format: "metadata" });
      for (const name of ["Message-ID", "References", "Subject"])
        params.append("metadataHeaders", name);
      const source = messageSchema.parse(
        await this.request(`${GMAIL}/messages/${idPath(draft.replyToMessageId)}?${params}`),
      );
      if (draft.threadId && source.threadId !== draft.threadId)
        throw new Error("Reply thread does not match the source message");
      threadId = source.threadId;
      const metadata = headers(source.payload);
      const messageId = singleLine(metadata.get("message-id") ?? "", "Message-ID");
      if (!/^<[^<>\s]+@[^<>\s]+>$/.test(messageId))
        throw new Error("Source message has no valid Message-ID for reply threading");
      const normalizedSubject = (subject: string) =>
        decodeHeader(subject)
          .replace(/^(?:\s*re:\s*)+/i, "")
          .trim();
      if (normalizedSubject(draft.subject) !== normalizedSubject(metadata.get("subject") ?? ""))
        throw new Error("Reply subject must match the source message subject");
      const references = singleLine(metadata.get("references") ?? "", "References").trim();
      if (references && !/^(?:<[^<>\s]+@[^<>\s]+>\s*)+$/.test(references))
        throw new Error("Source message has invalid References headers");
      const chain = [...new Set([...(references.match(/<[^<>\s]+>/g) ?? []), messageId])];
      if (chain.join(" ").length > 950)
        throw new Error("Reply References header exceeds the supported length");
      replyHeaders.push(`In-Reply-To: ${messageId}`, `References: ${chain.join(" ")}`);
    }
    const profile = z
      .object({ emailAddress: z.email() })
      .parse(await this.request(`${GMAIL}/profile`));
    const mimeHeaders = [
      `From: ${singleLine(profile.emailAddress, "sender")}`,
      `To: ${draft.to.join(",\r\n ")}`,
      ...(draft.cc.length ? [`Cc: ${draft.cc.join(",\r\n ")}`] : []),
      ...(draft.bcc.length ? [`Bcc: ${draft.bcc.join(",\r\n ")}`] : []),
      `Subject: ${encodedSubject(draft.subject)}`,
      `Date: ${new Date().toUTCString()}`,
      `Message-ID: <${randomUUID()}@openmuse.invalid>`,
      ...replyHeaders,
      "MIME-Version: 1.0",
    ];
    const textPart = [
      "Content-Type: text/plain; charset=UTF-8",
      "Content-Transfer-Encoding: base64",
      "",
      wrapBase64(Buffer.from(draft.body.replace(/\r\n|\r|\n/g, "\r\n"))),
    ].join("\r\n");
    let mime: string;
    if (!attachments.length) mime = [...mimeHeaders, textPart].join("\r\n");
    else {
      const boundary = `openmuse_${randomUUID()}`;
      const parts = [
        textPart,
        ...attachments.map((attachment) => {
          const name = encodeURIComponent(wellFormed(attachment.name)).replace(
            /['()*]/g,
            (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
          );
          return [
            `Content-Type: ${attachment.mimeType}`,
            `Content-Disposition: attachment; filename*=UTF-8''${name}`,
            "Content-Transfer-Encoding: base64",
            "",
            wrapBase64(attachment.bytes),
          ].join("\r\n");
        }),
      ];
      mime = [
        ...mimeHeaders,
        `Content-Type: multipart/mixed; boundary="${boundary}"`,
        "",
        ...parts.map((part) => `--${boundary}\r\n${part}`),
        `--${boundary}--`,
        "",
      ].join("\r\n");
    }
    const result = await this.request(`${GMAIL}/messages/send`, "POST", {
      raw: Buffer.from(mime).toString("base64url"),
      ...(threadId ? { threadId } : {}),
    });
    const parsed = z
      .object({ id: z.string().min(1), threadId: z.string().optional() })
      .safeParse(result);
    if (!parsed.success) throw new OutcomeUnknownError();
    return parsed.data;
  }

  async createEvent(input: EventDraft): Promise<CalendarEvent> {
    const draft = eventDraftSchema.parse(input);
    const result = await this.request(
      `${calendarPath(draft.calendarId)}?sendUpdates=all`,
      "POST",
      eventBody(draft),
    );
    try {
      return mapEvent(result, draft.calendarId, draft.timeZone);
    } catch {
      throw new OutcomeUnknownError();
    }
  }

  async updateEvent(
    eventId: string,
    input: EventDraft,
    expectedVersion?: string,
  ): Promise<CalendarEvent> {
    const draft = eventDraftSchema.parse(input);
    const current = await this.readSingleEvent(draft.calendarId, eventId);
    const result = await this.request(
      `${calendarPath(draft.calendarId)}/${idPath(eventId)}?sendUpdates=all`,
      "PATCH",
      eventBody(draft, true),
      { "If-Match": this.eventVersion(current, expectedVersion) },
    );
    try {
      return mapEvent(result, draft.calendarId, draft.timeZone);
    } catch {
      throw new OutcomeUnknownError();
    }
  }

  async deleteEvent(calendarId: string, eventId: string, expectedVersion?: string): Promise<void> {
    const current = await this.readSingleEvent(calendarId, eventId);
    await this.request(
      `${calendarPath(calendarId)}/${idPath(eventId)}?sendUpdates=all`,
      "DELETE",
      undefined,
      { "If-Match": this.eventVersion(current, expectedVersion) },
    );
  }
}