mcp-scraper 0.69.0 → 0.72.0

package/dist/chunk-MB72PA6S.js

@@ -0,0 +1,2003 @@
+import {
+  getOwnedServiceConnection,
+  getSessionSecret,
+  reconcileDiscoveredNangoConnections,
+  recordServiceConnectionHealth,
+  setServiceConnectionProviderIdentity,
+  updateServiceConnectionTools
+} from "./chunk-PJEEKOUM.js";
+import {
+  createConnectedDataArtifact,
+  createConnectedDataBinaryArtifact
+} from "./chunk-T3MZISOF.js";
+import {
+  recordVendorUsage,
+  runWithCostContext
+} from "./chunk-CXY5WV45.js";
+import {
+  CONNECTED_COMPUTE_CREDITS_PER_SECOND,
+  CONNECTED_FUNCTION_RUN_CREDITS,
+  CONNECTED_FUNCTION_RUN_MC,
+  CONNECTED_PROXY_REQUEST_CREDITS,
+  CONNECTED_USAGE_RATE_POLICY_VERSION,
+  LedgerOperation,
+  MC_PER_CREDIT,
+  calculateConnectedUsageCharge
+} from "./chunk-FVL4GUTP.js";
+import {
+  debitMcIdempotent,
+  getDb,
+  getUserByEmail,
+  reconcileBalanceMc
+} from "./chunk-WEFPBAAG.js";
+
+// src/api/gmail-service.ts
+import { createHash as createHash4, createHmac, timingSafeEqual } from "crypto";
+
+// src/api/main-nango-transport.ts
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+
+// src/api/connected-usage-billing.ts
+import { createHash, randomUUID } from "crypto";
+import { z } from "zod";
+
+// src/api/connected-cost-telemetry.ts
+async function recordNangoConnectionCost(userId, connectionMonths) {
+  if (!Number.isFinite(connectionMonths) || connectionMonths <= 0) return;
+  await runWithCostContext(
+    { op: LedgerOperation.CONNECTED_ACCOUNT_FEE, userId: Number(userId) },
+    () => recordVendorUsage({
+      vendor: "nango_connection",
+      units: connectionMonths,
+      unitType: "connection_month"
+    })
+  );
+}
+async function recordNangoUsageCost(userId, usage) {
+  const dimensions = [
+    { vendor: "nango_function_run", units: usage.functionRuns, unitType: "function_run" },
+    { vendor: "nango_proxy_request", units: usage.proxyRequests, unitType: "proxy_request" },
+    { vendor: "nango_compute", units: usage.computeMilliseconds / 1e3, unitType: "compute_second" }
+  ];
+  await runWithCostContext(
+    { op: LedgerOperation.CONNECTED_USAGE, userId: Number(userId) },
+    async () => {
+      for (const dimension of dimensions) {
+        if (!Number.isFinite(dimension.units) || dimension.units <= 0) continue;
+        await recordVendorUsage(dimension);
+      }
+    }
+  );
+}
+
+// src/api/connected-usage-billing.ts
+var CONNECTED_USAGE_BILLING_CLASS = "connected_usage";
+var CONNECTED_USAGE_DEFAULT_SOURCE_SURFACE = "mastra_scheduler";
+var ConnectedUsageSafeMetadataSchema = z.object({
+  toolName: z.string().trim().min(1).max(200).optional(),
+  operationKind: z.enum(["read", "action", "sync", "export", "proxy", "other"]).optional(),
+  outcome: z.enum(["success", "error", "partial"]).optional(),
+  requestId: z.string().trim().min(1).max(200).optional(),
+  occurrenceId: z.string().trim().min(1).max(200).optional(),
+  scheduleId: z.string().trim().min(1).max(200).optional(),
+  nangoOperationId: z.string().trim().min(1).max(200).optional(),
+  startedAt: z.string().datetime({ offset: true }).optional(),
+  completedAt: z.string().datetime({ offset: true }).optional()
+}).strict();
+var ConnectedUsageSettlementInputSchema = z.object({
+  identity: z.string().trim().min(1).max(320),
+  idempotencyKey: z.string().trim().min(1).max(500),
+  ratePolicyVersion: z.string().trim().min(1).max(100),
+  connectionId: z.string().trim().min(1).max(500),
+  providerConfigKey: z.string().trim().min(1).max(200),
+  functionRuns: z.number().int().safe().nonnegative(),
+  proxyRequests: z.number().int().safe().nonnegative(),
+  computeMilliseconds: z.number().int().safe().nonnegative(),
+  sourceSurface: z.enum(["main_mcp", "mastra_scheduler", "nango_reconciliation"]).default(CONNECTED_USAGE_DEFAULT_SOURCE_SURFACE),
+  metadata: ConnectedUsageSafeMetadataSchema.optional()
+}).strict();
+var ConnectedUsagePreflightInputSchema = z.object({
+  identity: z.string().trim().min(1).max(320),
+  ratePolicyVersion: z.string().trim().min(1).max(100)
+}).strict();
+var ConnectedUsageBillingError = class extends Error {
+  constructor(code, message, httpStatus, details = {}) {
+    super(message);
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.details = details;
+    this.name = "ConnectedUsageBillingError";
+  }
+  code;
+  httpStatus;
+  details;
+};
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function eventKey(idempotencyKey) {
+  return `connected-usage:${hash(idempotencyKey)}`;
+}
+function debitKey(idempotencyKey) {
+  return `connected-usage-debit:${hash(idempotencyKey)}`;
+}
+function normalizeIdentity(identity) {
+  return identity.trim().toLowerCase();
+}
+async function resolveUser(identity) {
+  const user = await getUserByEmail(normalizeIdentity(identity));
+  if (!user) throw new ConnectedUsageBillingError("user_not_found", "billing identity was not found", 404);
+  return user;
+}
+function canonicalFingerprint(args) {
+  const metadata = {
+    toolName: args.metadata.toolName ?? null,
+    operationKind: args.metadata.operationKind ?? null,
+    outcome: args.metadata.outcome ?? null,
+    requestId: args.metadata.requestId ?? null,
+    occurrenceId: args.metadata.occurrenceId ?? null,
+    scheduleId: args.metadata.scheduleId ?? null,
+    nangoOperationId: args.metadata.nangoOperationId ?? null,
+    startedAt: args.metadata.startedAt ?? null,
+    completedAt: args.metadata.completedAt ?? null
+  };
+  return hash(JSON.stringify({
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    connectionId: args.connectionId,
+    providerConfigKey: args.providerConfigKey,
+    usage: args.usage,
+    sourceSurface: args.sourceSurface,
+    metadata
+  }));
+}
+function encodeMetadata(metadata) {
+  const encoded = JSON.stringify(metadata);
+  if (encoded.length > 4e3) throw new ConnectedUsageBillingError("invalid_request", "connected usage metadata is too large", 400);
+  return encoded;
+}
+function decodeMetadata(row) {
+  try {
+    const parsed = JSON.parse(row.metadata ?? "");
+    if (parsed.contract !== "connected_usage_receipt" || parsed.ratePolicyVersion !== CONNECTED_USAGE_RATE_POLICY_VERSION || typeof parsed.fingerprint !== "string" || typeof parsed.connectionId !== "string" || typeof parsed.providerConfigKey !== "string" || !parsed.usage || !parsed.charge) {
+      throw new Error("invalid connected usage receipt metadata");
+    }
+    return parsed;
+  } catch {
+    throw new ConnectedUsageBillingError("idempotency_key_conflict", "the idempotency key is already bound to an incompatible billing receipt", 409);
+  }
+}
+async function readEvent(key) {
+  const result = await getDb().execute({
+    sql: "SELECT id, user_id, billing_class, source_surface, status, amount_mc, metadata FROM billing_events WHERE idempotency_key = ? LIMIT 1",
+    args: [key]
+  });
+  return result.rows[0] ? result.rows[0] : null;
+}
+async function hasOtherPendingReceipt(userId, excludingKey) {
+  const result = await getDb().execute({
+    sql: `SELECT 1
+          FROM billing_events
+          WHERE user_id = ?
+            AND billing_class = ?
+            AND status = 'cost_pending'
+            ${excludingKey ? "AND idempotency_key <> ?" : ""}
+          LIMIT 1`,
+    args: excludingKey ? [userId, CONNECTED_USAGE_BILLING_CLASS, excludingKey] : [userId, CONNECTED_USAGE_BILLING_CLASS]
+  });
+  return result.rows.length > 0;
+}
+function debitKeyFromEventKey(key) {
+  const prefix = "connected-usage:";
+  const digest = key.startsWith(prefix) ? key.slice(prefix.length) : "";
+  return /^[a-f0-9]{64}$/.test(digest) ? `connected-usage-debit:${digest}` : null;
+}
+async function retryPendingConnectedUsageReceipts(user) {
+  const result = await getDb().execute({
+    sql: `SELECT id, user_id, idempotency_key, billing_class, source_surface, status, amount_mc, metadata
+          FROM billing_events
+          WHERE user_id = ? AND billing_class = ? AND status = 'cost_pending'
+          ORDER BY created_at ASC
+          LIMIT 10`,
+    args: [user.id, CONNECTED_USAGE_BILLING_CLASS]
+  });
+  for (const raw of result.rows) {
+    const row = raw;
+    const key = String(row.idempotency_key ?? "");
+    const durableDebitKey = debitKeyFromEventKey(key);
+    let metadata;
+    try {
+      metadata = decodeMetadata(row);
+    } catch {
+      return;
+    }
+    if (!durableDebitKey || Number(row.user_id) !== user.id || row.billing_class !== CONNECTED_USAGE_BILLING_CLASS || Number(row.amount_mc) !== metadata.charge.amountMc) {
+      return;
+    }
+    if (metadata.charge.amountMc > 0) {
+      const debit = await debitMcIdempotent(
+        user.id,
+        metadata.charge.amountMc,
+        LedgerOperation.CONNECTED_USAGE,
+        `connected-usage:${metadata.providerConfigKey}`,
+        durableDebitKey
+      );
+      if (!debit.ok) return;
+    }
+    const settledMetadata = { ...metadata };
+    delete settledMetadata.reason;
+    await getDb().execute({
+      sql: `UPDATE billing_events
+            SET status = 'settled', metadata = ?, settled_at = datetime('now')
+            WHERE idempotency_key = ? AND user_id = ? AND billing_class = ? AND status = 'cost_pending'`,
+      args: [encodeMetadata(settledMetadata), key, user.id, CONNECTED_USAGE_BILLING_CLASS]
+    });
+  }
+}
+function assertRatePolicyVersion(ratePolicyVersion) {
+  if (ratePolicyVersion !== CONNECTED_USAGE_RATE_POLICY_VERSION) {
+    throw new ConnectedUsageBillingError(
+      "rate_policy_mismatch",
+      "connected usage receipt rate policy does not match the active policy",
+      409,
+      { expectedRatePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION }
+    );
+  }
+}
+async function preflightConnectedUsage(rawInput) {
+  const parsed = ConnectedUsagePreflightInputSchema.safeParse(rawInput);
+  if (!parsed.success) {
+    throw new ConnectedUsageBillingError("invalid_request", "invalid connected usage preflight request", 400);
+  }
+  assertRatePolicyVersion(parsed.data.ratePolicyVersion);
+  const user = await resolveUser(parsed.data.identity);
+  await retryPendingConnectedUsageReceipts(user);
+  if (await hasOtherPendingReceipt(user.id)) {
+    throw new ConnectedUsageBillingError(
+      "pending_cost",
+      "a previous connected usage receipt has unresolved cost",
+      409
+    );
+  }
+  const balanceMc = await reconcileBalanceMc(user.id, user.balance_mc);
+  if (balanceMc < CONNECTED_FUNCTION_RUN_MC) {
+    throw new ConnectedUsageBillingError(
+      "insufficient_credits",
+      "the wallet cannot cover the minimum connected function charge",
+      402,
+      { balanceMc, requiredMc: CONNECTED_FUNCTION_RUN_MC }
+    );
+  }
+  return {
+    allowed: true,
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    minimumMc: CONNECTED_FUNCTION_RUN_MC,
+    minimumCredits: CONNECTED_FUNCTION_RUN_CREDITS,
+    balanceMc
+  };
+}
+function assertMatchingReceipt(row, userId, sourceSurface, fingerprint, amountMc) {
+  const metadata = decodeMetadata(row);
+  if (Number(row.user_id) !== userId || row.billing_class !== CONNECTED_USAGE_BILLING_CLASS || row.source_surface !== sourceSurface || Number(row.amount_mc) !== amountMc || metadata.fingerprint !== fingerprint) {
+    throw new ConnectedUsageBillingError("idempotency_key_conflict", "the idempotency key is already bound to different connected usage", 409);
+  }
+  return metadata;
+}
+function costBreakdown(usage, charge) {
+  return [
+    {
+      key: "function_runs",
+      label: "Connected function runs",
+      quantity: usage.functionRuns,
+      quantityUnit: "function_run",
+      rateCredits: CONNECTED_FUNCTION_RUN_CREDITS,
+      rateUnit: "function_run",
+      amountMc: charge.functionRunMc,
+      credits: charge.functionRunMc / MC_PER_CREDIT
+    },
+    {
+      key: "proxy_requests",
+      label: "Connected proxy requests",
+      quantity: usage.proxyRequests,
+      quantityUnit: "proxy_request",
+      rateCredits: CONNECTED_PROXY_REQUEST_CREDITS,
+      rateUnit: "proxy_request",
+      amountMc: charge.proxyRequestMc,
+      credits: charge.proxyRequestMc / MC_PER_CREDIT
+    },
+    {
+      key: "compute",
+      label: "Connected function compute",
+      quantity: usage.computeMilliseconds,
+      quantityUnit: "millisecond",
+      rateCredits: CONNECTED_COMPUTE_CREDITS_PER_SECOND,
+      rateUnit: "compute_second",
+      amountMc: charge.computeMc,
+      credits: charge.computeMc / MC_PER_CREDIT
+    }
+  ];
+}
+function mapSettlement(row, metadata, balanceMc, duplicate) {
+  const reason = row.status === "cost_pending" ? metadata.reason : void 0;
+  return {
+    id: row.id,
+    status: row.status === "settled" ? "settled" : "cost_pending",
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    connectionId: metadata.connectionId,
+    providerConfigKey: metadata.providerConfigKey,
+    amountMc: metadata.charge.amountMc,
+    credits: metadata.charge.credits,
+    functionRunMc: metadata.charge.functionRunMc,
+    proxyRequestMc: metadata.charge.proxyRequestMc,
+    computeMc: metadata.charge.computeMc,
+    usage: metadata.usage,
+    costBreakdown: costBreakdown(metadata.usage, metadata.charge),
+    balanceMc,
+    ...reason ? { reason } : {},
+    duplicate
+  };
+}
+async function settleConnectedUsage(rawInput) {
+  const parsed = ConnectedUsageSettlementInputSchema.safeParse(rawInput);
+  if (!parsed.success) {
+    throw new ConnectedUsageBillingError(
+      "invalid_request",
+      "invalid connected usage settlement request",
+      400,
+      { fields: [...new Set(parsed.error.issues.map((issue) => issue.path.join(".")).filter(Boolean))] }
+    );
+  }
+  const input = parsed.data;
+  assertRatePolicyVersion(input.ratePolicyVersion);
+  const user = await resolveUser(input.identity);
+  const usage = {
+    functionRuns: input.functionRuns,
+    proxyRequests: input.proxyRequests,
+    computeMilliseconds: input.computeMilliseconds
+  };
+  const charge = calculateConnectedUsageCharge(usage);
+  const safeMetadata = input.metadata ?? {};
+  const fingerprint = canonicalFingerprint({
+    connectionId: input.connectionId,
+    providerConfigKey: input.providerConfigKey,
+    usage,
+    sourceSurface: input.sourceSurface,
+    metadata: safeMetadata
+  });
+  const storedMetadata = {
+    contract: "connected_usage_receipt",
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    fingerprint,
+    connectionId: input.connectionId,
+    providerConfigKey: input.providerConfigKey,
+    usage,
+    charge,
+    safeMetadata
+  };
+  const key = eventKey(input.idempotencyKey);
+  if (await hasOtherPendingReceipt(user.id, key)) {
+    throw new ConnectedUsageBillingError(
+      "pending_cost",
+      "a previous connected usage receipt has unresolved cost",
+      409
+    );
+  }
+  const inserted = await getDb().execute({
+    sql: `INSERT OR IGNORE INTO billing_events
+            (id, user_id, idempotency_key, billing_class, source_surface, status, amount_mc, metadata)
+          VALUES (?, ?, ?, ?, ?, 'settling', ?, ?)`,
+    args: [randomUUID(), user.id, key, CONNECTED_USAGE_BILLING_CLASS, input.sourceSurface, charge.amountMc, encodeMetadata(storedMetadata)]
+  });
+  let event = await readEvent(key);
+  if (!event) throw new Error("connected usage receipt insert completed without a readable event");
+  let eventMetadata = assertMatchingReceipt(event, user.id, input.sourceSurface, fingerprint, charge.amountMc);
+  const duplicate = inserted.rowsAffected === 0;
+  if (event.status === "settled") {
+    return mapSettlement(event, eventMetadata, await reconcileBalanceMc(user.id, user.balance_mc), true);
+  }
+  if (!["settling", "cost_pending"].includes(event.status)) {
+    throw new ConnectedUsageBillingError("idempotency_key_conflict", "the connected usage receipt has an incompatible status", 409);
+  }
+  if (event.status === "cost_pending") {
+    await getDb().execute({
+      sql: "UPDATE billing_events SET status = 'settling', metadata = ? WHERE idempotency_key = ? AND status = 'cost_pending'",
+      args: [encodeMetadata(storedMetadata), key]
+    });
+  }
+  if (charge.amountMc === 0) {
+    await getDb().execute({
+      sql: "UPDATE billing_events SET status = 'settled', settled_at = datetime('now') WHERE idempotency_key = ? AND status = 'settling'",
+      args: [key]
+    });
+  } else {
+    const debit = await debitMcIdempotent(
+      user.id,
+      charge.amountMc,
+      LedgerOperation.CONNECTED_USAGE,
+      `connected-usage:${input.providerConfigKey}`,
+      debitKey(input.idempotencyKey)
+    );
+    if (!debit.ok) {
+      const pendingMetadata = { ...storedMetadata, reason: "insufficient_credits" };
+      await getDb().execute({
+        sql: "UPDATE billing_events SET status = 'cost_pending', metadata = ? WHERE idempotency_key = ? AND status = 'settling'",
+        args: [encodeMetadata(pendingMetadata), key]
+      });
+      event = await readEvent(key);
+      if (!event) throw new Error("connected usage pending receipt was lost");
+      eventMetadata = assertMatchingReceipt(event, user.id, input.sourceSurface, fingerprint, charge.amountMc);
+      return mapSettlement(event, eventMetadata, debit.balance_mc, duplicate || debit.duplicate);
+    }
+    await getDb().execute({
+      sql: "UPDATE billing_events SET status = 'settled', metadata = ?, settled_at = datetime('now') WHERE idempotency_key = ? AND status IN ('settling', 'cost_pending')",
+      args: [encodeMetadata(storedMetadata), key]
+    });
+    if (!debit.duplicate) await recordNangoUsageCost(user.id, usage);
+  }
+  event = await readEvent(key);
+  if (!event) throw new Error("connected usage settlement completed without an event receipt");
+  eventMetadata = assertMatchingReceipt(event, user.id, input.sourceSurface, fingerprint, charge.amountMc);
+  return mapSettlement(
+    event,
+    eventMetadata,
+    await reconcileBalanceMc(user.id, user.balance_mc),
+    duplicate
+  );
+}
+async function listConnectedUsageHistory(userId, limit = 100) {
+  const result = await getDb().execute({
+    sql: `SELECT id, user_id, billing_class, source_surface, status, amount_mc, metadata, created_at
+          FROM billing_events
+          WHERE user_id = ? AND billing_class = ? AND status IN ('settled', 'cost_pending')
+          ORDER BY created_at DESC
+          LIMIT ?`,
+    args: [userId, CONNECTED_USAGE_BILLING_CLASS, Math.max(1, Math.min(250, Math.round(limit)))]
+  });
+  const history = [];
+  for (const raw of result.rows) {
+    const row = raw;
+    try {
+      const receipt = decodeMetadata(row);
+      history.push({
+        id: row.id,
+        createdAt: String(row.created_at ?? ""),
+        status: row.status === "settled" ? "settled" : "cost_pending",
+        connectionId: receipt.connectionId,
+        providerConfigKey: receipt.providerConfigKey,
+        amountMc: receipt.charge.amountMc,
+        credits: receipt.charge.credits,
+        usage: receipt.usage,
+        costBreakdown: costBreakdown(receipt.usage, receipt.charge),
+        metadata: receipt.safeMetadata
+      });
+    } catch {
+    }
+  }
+  return history;
+}
+
+// src/api/connected-tool-policy.ts
+function classifyConnectedTool(tool) {
+  if (tool.annotations?.readOnlyHint === true) return "read";
+  if (tool.annotations?.readOnlyHint === false) return "action";
+  return /^(get|list|search|query|read|download|fetch|find|lookup|inspect|describe|check)-/i.test(tool.name) ? "read" : "action";
+}
+function normalizedPolicyMap(value) {
+  return new Map(Object.entries(value ?? {}).map(([name, entries]) => [
+    name,
+    [...new Set(entries.map((entry) => entry.trim()).filter(Boolean))].sort()
+  ]));
+}
+function buildConnectedToolPolicyRegistry(args) {
+  const permissionPolicies = normalizedPolicyMap(args.requiredPermissionsByTool);
+  const featurePolicies = normalizedPolicyMap(args.requiredFeaturesByTool);
+  const granted = new Set(args.grantedPermissions ?? []);
+  const enabled = new Set(args.enabledFeatures ?? []);
+  const adminBlocked = new Set(args.adminBlockedTools ?? []);
+  const policies = /* @__PURE__ */ new Map();
+  for (const tool of args.tools) {
+    const classification = classifyConnectedTool(tool);
+    const requiredPermissions = permissionPolicies.get(tool.name) ?? [];
+    const requiredFeatures = featurePolicies.get(tool.name) ?? [];
+    const missingPermissions = requiredPermissions.filter((permission) => !granted.has(permission));
+    const missingFeatures = requiredFeatures.filter((feature) => !enabled.has(feature));
+    const blockedReason = !args.connectionActive ? "inactive_connection" : adminBlocked.has(tool.name) ? "admin_blocked" : classification === "action" && !args.actionsEnabled ? "actions_disabled" : requiredPermissions.length > 0 && args.permissionVerification === "unavailable" ? "permission_verification_unavailable" : missingPermissions.length > 0 ? "missing_permission" : missingFeatures.length > 0 ? "missing_app_feature" : null;
+    policies.set(tool.name, {
+      name: tool.name,
+      classification,
+      requiredPermissions,
+      requiredFeatures,
+      available: blockedReason === null,
+      blockedReason,
+      missingPermissions,
+      missingFeatures
+    });
+  }
+  return policies;
+}
+function connectedToolPolicyOrThrow(registry, toolName) {
+  const policy = registry.get(toolName);
+  if (!policy) throw new Error("connected_tool_policy_missing");
+  return policy;
+}
+
+// src/api/main-nango-transport.ts
+var DEFAULT_NANGO_MCP_URL = "https://api.nango.dev/mcp";
+var NANGO_TIMEOUT_MS = 2e4;
+var NANGO_TOOL_CALL_TIMEOUT_MS = 24e4;
+var NANGO_CONNECTION_PAGE_SIZE = 100;
+var NANGO_CONNECTION_MAX_PAGES = 20;
+var PROVIDER_IDENTITY_RETRY_MS = 6 * 60 * 60 * 1e3;
+var MAIN_INTEGRATION_CONTRACT_VERSION = "2026-07-16.1";
+var MAIN_INTEGRATION_CONTRACT_HASH = "f037859ec80c2ea2fac6e4a67c1a59f3200dd22d3642c97789b9bb3236723d3e";
+var MainNangoTransportError = class extends Error {
+  status;
+  code;
+  retryable;
+  retryAfterMs;
+  constructor(message, status, code, retryable = status === 429 || status >= 500, retryAfterMs = null) {
+    super(message);
+    this.name = "MainNangoTransportError";
+    this.status = status;
+    this.code = code;
+    this.retryable = retryable;
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+function nangoClientErrorText(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return "";
+  }
+}
+function retryAfterMsFromText(value) {
+  const milliseconds = value.match(/retry[_ -]?after[_ -]?ms[^0-9]{0,20}(\d{1,7})/i);
+  if (milliseconds) return Math.min(Math.max(Number(milliseconds[1]), 1e3), 6e4);
+  const seconds = value.match(/retry[_ -]?after[^0-9]{0,20}(\d{1,4})/i);
+  if (seconds) return Math.min(Math.max(Number(seconds[1]), 1) * 1e3, 6e4);
+  return null;
+}
+function normalizeNangoClientError(error) {
+  if (error instanceof MainNangoTransportError) return error;
+  const detail = nangoClientErrorText(error);
+  const structured = error && typeof error === "object" ? error : null;
+  if (structured?.code === -32001 || structured?.name === "RequestTimeout" || /Request timed out|RequestTimeout|Maximum total timeout exceeded/i.test(detail)) {
+    return new MainNangoTransportError(
+      "The connected service operation timed out before returning a result. Retry failed items or use a smaller batch.",
+      503,
+      "mcp_request_timeout",
+      true
+    );
+  }
+  if (/SERVICE_DISABLED|accessNotConfigured/i.test(detail)) {
+    return new MainNangoTransportError(
+      "The provider API required by this connection is disabled. Enable it in the provider project, wait for propagation, then retry.",
+      409,
+      "provider_api_disabled",
+      false
+    );
+  }
+  if (/PERMISSION_DENIED|insufficientPermissions|insufficient permission/i.test(detail)) {
+    return new MainNangoTransportError(
+      "The connected account does not have permission to run this provider operation.",
+      403,
+      "missing_provider_permission",
+      false
+    );
+  }
+  if (/RESOURCE_EXHAUSTED|rate.?limit|status["']?\s*:\s*429/i.test(detail)) {
+    return new MainNangoTransportError(
+      "The connected provider is temporarily rate limited.",
+      429,
+      "upstream_rate_limited",
+      true,
+      retryAfterMsFromText(detail)
+    );
+  }
+  if (/UNAUTHENTICATED|invalid_grant|status["']?\s*:\s*401/i.test(detail)) {
+    return new MainNangoTransportError("The service connection requires reconnection.", 409, "connection_inactive", false);
+  }
+  return new MainNangoTransportError("The service connection is temporarily unavailable.", 503, "connection_transport_unavailable");
+}
+async function callNangoToolWithBudget(client, tool, input) {
+  return client.callTool(
+    { name: tool, arguments: input },
+    { timeout: NANGO_TOOL_CALL_TIMEOUT_MS }
+  );
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function arrayAt(payload, key) {
+  if (Array.isArray(payload)) return payload;
+  const root = asRecord(payload);
+  if (Array.isArray(root?.[key])) return root[key];
+  if (Array.isArray(root?.data)) return root.data;
+  const data = asRecord(root?.data);
+  return Array.isArray(data?.[key]) ? data[key] : [];
+}
+function nangoSecret() {
+  const secret = process.env.NANGO_SECRET_KEY?.trim();
+  if (!secret) throw new MainNangoTransportError("Nango is not configured.", 503, "nango_not_configured");
+  return secret;
+}
+function nangoMcpUrl() {
+  try {
+    return new URL(process.env.NANGO_MCP_URL?.trim() || DEFAULT_NANGO_MCP_URL);
+  } catch {
+    throw new MainNangoTransportError("Nango MCP URL is invalid.", 503, "nango_invalid_url");
+  }
+}
+async function nangoRequest(path, options = {}) {
+  const url = new URL(path, `${nangoMcpUrl().origin}/`);
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== void 0) url.searchParams.set(key, String(value));
+  }
+  let response;
+  try {
+    response = await fetch(url, {
+      method: options.method ?? "GET",
+      headers: {
+        authorization: `Bearer ${nangoSecret()}`,
+        accept: "application/json",
+        ...options.body ? { "content-type": "application/json" } : {},
+        ...options.headers
+      },
+      body: options.body ? JSON.stringify(options.body) : void 0,
+      signal: AbortSignal.timeout(NANGO_TIMEOUT_MS)
+    });
+  } catch {
+    throw new MainNangoTransportError("Nango is temporarily unavailable.", 503, "connection_transport_unavailable");
+  }
+  const raw = await response.text();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch {
+    throw new MainNangoTransportError("Nango returned an invalid response.", 502, "nango_invalid_response");
+  }
+  if (!response.ok) {
+    const status = response.status === 400 || response.status === 403 || response.status === 404 || response.status === 409 || response.status === 429 || response.status === 503 ? response.status : 502;
+    throw new MainNangoTransportError(
+      status === 429 ? "The connected provider is temporarily rate limited." : "Nango request failed.",
+      status,
+      status === 429 ? "upstream_rate_limited" : status === 404 ? "connection_not_found" : "connection_transport_unavailable",
+      status === 429 || status >= 500,
+      status === 429 ? retryAfterMsFromText(`retry-after: ${response.headers.get("retry-after") ?? ""}`) : null
+    );
+  }
+  return payload;
+}
+function normalizedIdentity(value) {
+  const valueText = text(value);
+  return valueText ? valueText.normalize("NFKC").toLowerCase() : null;
+}
+function connectionIdentityMatches(value, identity) {
+  const row = asRecord(value);
+  const tags = asRecord(row?.tags);
+  const endUser = asRecord(row?.end_user);
+  const expected = normalizedIdentity(identity);
+  if (!expected) return false;
+  const emails = [normalizedIdentity(tags?.end_user_email), normalizedIdentity(endUser?.email)].filter((candidate) => !!candidate);
+  if (emails.some((candidate) => candidate !== expected)) return false;
+  const ids = [normalizedIdentity(tags?.end_user_id), normalizedIdentity(endUser?.id)].filter((candidate) => !!candidate && candidate.includes("@"));
+  if (ids.some((candidate) => candidate !== expected)) return false;
+  return emails.length > 0 ? emails.includes(expected) : ids.includes(expected);
+}
+function discoveredConnection(value) {
+  const row = asRecord(value);
+  const upstreamConnectionId = text(row?.connection_id);
+  const providerConfigKey = text(row?.provider_config_key);
+  if (!upstreamConnectionId || !providerConfigKey) return null;
+  const errors = Array.isArray(row?.errors) ? row.errors : [];
+  const authError = errors.some((error) => text(asRecord(error)?.type) === "auth");
+  return {
+    upstreamConnectionId,
+    providerConfigKey,
+    provider: text(row?.provider) ?? providerConfigKey,
+    // Nango's end-user fields identify the MCP Scraper tenant, not the
+    // provider-side principal that authorized this connection.
+    label: null,
+    lifecycleStatus: authError ? "needs_reauth" : "connected",
+    reconnectRequired: authError,
+    createdAt: text(row?.created_at) ?? text(row?.created),
+    updatedAt: text(row?.updated_at)
+  };
+}
+var IDENTITY_SUPPORTED_PROVIDERS = /* @__PURE__ */ new Set([
+  "facebook",
+  "github-getting-started",
+  "google-analytics",
+  "google-calendar",
+  "google-drive",
+  "google-mail",
+  "google-search-console",
+  "linkedin",
+  "meta-marketing-api",
+  "slack",
+  "twitter-v2",
+  "xero",
+  "youtube",
+  "zoom"
+]);
+function scalarId(value) {
+  const valueText = text(value);
+  if (valueText) return valueText;
+  return typeof value === "number" && Number.isFinite(value) ? String(value) : null;
+}
+function providerEmail(value) {
+  const email = text(value)?.toLowerCase() ?? null;
+  return email && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? email : null;
+}
+function compactProviderIdentity(identity) {
+  return identity.id || identity.email || identity.name ? identity : null;
+}
+async function providerProxyJson(args) {
+  return nangoRequest(`/proxy${args.path}`, {
+    query: args.query,
+    headers: {
+      "connection-id": args.upstreamConnectionId,
+      "provider-config-key": args.providerConfigKey,
+      ...args.baseUrlOverride ? { "base-url-override": args.baseUrlOverride } : {}
+    }
+  });
+}
+var GMAIL_PROXY_PATHS = [
+  { method: "GET", pattern: /^\/gmail\/v1\/users\/me\/messages$/ },
+  { method: "GET", pattern: /^\/gmail\/v1\/users\/me\/messages\/[A-Za-z0-9_-]+$/ },
+  { method: "GET", pattern: /^\/gmail\/v1\/users\/me\/messages\/[A-Za-z0-9_-]+\/attachments\/[A-Za-z0-9_-]+$/ },
+  { method: "GET", pattern: /^\/gmail\/v1\/users\/me\/labels$/ },
+  { method: "POST", pattern: /^\/gmail\/v1\/users\/me\/messages\/batchModify$/ },
+  { method: "POST", pattern: /^\/gmail\/v1\/users\/me\/messages\/batchDelete$/ },
+  { method: "POST", pattern: /^\/gmail\/v1\/users\/me\/messages\/[A-Za-z0-9_-]+\/(?:trash|untrash)$/ }
+];
+var GMAIL_QUERY_KEYS = /* @__PURE__ */ new Set(["q", "maxResults", "pageToken", "format", "metadataHeaders", "fields"]);
+async function callGmailProviderProxyDirect(args) {
+  const connection = await requireOwnedActiveConnection(args.identity, args.connectionId);
+  if (connection.providerConfigKey !== "google-mail") {
+    throw new MainNangoTransportError("Service connection not found.", 404, "connection_not_found", false);
+  }
+  if (!GMAIL_PROXY_PATHS.some((rule) => rule.method === args.method && rule.pattern.test(args.path))) {
+    throw new MainNangoTransportError("The Gmail provider operation is not allowed.", 403, "tool_not_allowed", false);
+  }
+  if (Object.keys(args.query ?? {}).some((key) => !GMAIL_QUERY_KEYS.has(key))) {
+    throw new MainNangoTransportError("The Gmail provider query is not allowed.", 400, "invalid_request", false);
+  }
+  const isAction = args.method === "POST";
+  if (isAction && !connection.actionsEnabled) {
+    throw new MainNangoTransportError("Actions are disabled for this service connection.", 403, "actions_disabled", false);
+  }
+  await preflightConnectedUsage({ identity: args.identity, ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION });
+  const requestId = args.requestId?.trim() || randomUUID2();
+  const idempotencyKey = `main-gmail-proxy:${createHash2("sha256").update(args.identity.toLowerCase()).update("\0").update(connection.id).update("\0").update(args.method).update("\0").update(args.path).update("\0").update(requestId).digest("hex")}`;
+  const started = performance.now();
+  let result;
+  let providerError;
+  try {
+    result = await nangoRequest(`/proxy${args.path}`, {
+      method: args.method,
+      query: args.query,
+      body: args.body,
+      headers: {
+        "connection-id": connection.upstreamConnectionId,
+        "provider-config-key": "google-mail",
+        "base-url-override": "https://gmail.googleapis.com"
+      }
+    });
+  } catch (error) {
+    providerError = error;
+  }
+  await settleConnectedUsage({
+    identity: args.identity,
+    idempotencyKey,
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    connectionId: connection.id,
+    providerConfigKey: connection.providerConfigKey,
+    functionRuns: 0,
+    proxyRequests: 1,
+    computeMilliseconds: Math.max(0, Math.round(performance.now() - started)),
+    sourceSurface: "main_mcp",
+    metadata: {
+      operationKind: isAction ? "action" : "read",
+      outcome: providerError ? "error" : "success",
+      requestId: requestId.length <= 200 ? requestId : createHash2("sha256").update(requestId).digest("hex")
+    }
+  });
+  if (providerError) throw normalizeNangoClientError(providerError);
+  return result;
+}
+async function googleProviderAccountIdentity(args) {
+  const request = (path, query, baseUrlOverride) => providerProxyJson({ ...args, path, query, baseUrlOverride });
+  try {
+    if (args.providerConfigKey === "google-mail") {
+      const payload = asRecord(await request("/gmail/v1/users/me/profile", void 0, "https://gmail.googleapis.com"));
+      const email = providerEmail(payload?.emailAddress);
+      return compactProviderIdentity({ id: email, email, name: null });
+    }
+    if (args.providerConfigKey === "google-drive") {
+      const payload = asRecord(await request("/drive/v3/about", { fields: "user(permissionId,displayName,emailAddress)" }, "https://www.googleapis.com"));
+      const user = asRecord(payload?.user);
+      return compactProviderIdentity({
+        id: text(user?.permissionId),
+        email: providerEmail(user?.emailAddress),
+        name: text(user?.displayName)
+      });
+    }
+    if (args.providerConfigKey === "google-calendar") {
+      const payload = asRecord(await request("/calendar/v3/calendars/primary", void 0, "https://www.googleapis.com"));
+      const id = text(payload?.id);
+      return compactProviderIdentity({ id, email: providerEmail(id), name: text(payload?.summary) });
+    }
+    if (args.providerConfigKey === "youtube") {
+      const payload = asRecord(await request("/youtube/v3/channels", { part: "snippet", mine: "true", maxResults: 1 }, "https://www.googleapis.com"));
+      const first = Array.isArray(payload?.items) ? asRecord(payload.items[0]) : null;
+      return compactProviderIdentity({ id: text(first?.id), email: null, name: text(asRecord(first?.snippet)?.title) });
+    }
+  } catch {
+  }
+  try {
+    const payload = asRecord(await request("/v1/userinfo", void 0, "https://openidconnect.googleapis.com"));
+    return compactProviderIdentity({
+      id: text(payload?.sub),
+      email: payload?.email_verified === false ? null : providerEmail(payload?.email),
+      name: text(payload?.name)
+    });
+  } catch {
+    return null;
+  }
+}
+async function getNangoProviderAccountIdentity(args) {
+  if (!IDENTITY_SUPPORTED_PROVIDERS.has(args.providerConfigKey)) return null;
+  if (args.providerConfigKey.startsWith("google-") || args.providerConfigKey === "youtube") {
+    return googleProviderAccountIdentity(args);
+  }
+  try {
+    if (args.providerConfigKey === "github-getting-started") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/user" }));
+      return compactProviderIdentity({ id: scalarId(payload?.id), email: providerEmail(payload?.email), name: text(payload?.name) ?? text(payload?.login) });
+    }
+    if (args.providerConfigKey === "slack") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/api/auth.test" }));
+      return compactProviderIdentity({ id: text(payload?.user_id), email: null, name: [text(payload?.user), text(payload?.team)].filter(Boolean).join(" \xB7 ") || null });
+    }
+    if (args.providerConfigKey === "zoom") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/v2/users/me" }));
+      const fullName = [text(payload?.first_name), text(payload?.last_name)].filter(Boolean).join(" ");
+      return compactProviderIdentity({ id: text(payload?.id), email: providerEmail(payload?.email), name: text(payload?.display_name) ?? (fullName || null) });
+    }
+    if (args.providerConfigKey === "linkedin") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/v2/userinfo" }));
+      return compactProviderIdentity({ id: text(payload?.sub), email: payload?.email_verified === false ? null : providerEmail(payload?.email), name: text(payload?.name) });
+    }
+    if (args.providerConfigKey === "meta-marketing-api" || args.providerConfigKey === "facebook") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/me", query: { fields: "id,name,email" } }));
+      return compactProviderIdentity({ id: text(payload?.id), email: providerEmail(payload?.email), name: text(payload?.name) });
+    }
+    if (args.providerConfigKey === "twitter-v2") {
+      const payload = asRecord(await providerProxyJson({ ...args, path: "/2/users/me", query: { "user.fields": "id,name,username" } }));
+      const data = asRecord(payload?.data);
+      return compactProviderIdentity({ id: text(data?.id), email: null, name: text(data?.username) ?? text(data?.name) });
+    }
+    if (args.providerConfigKey === "xero") {
+      const payload = await providerProxyJson({ ...args, path: "/connections" });
+      const first = Array.isArray(payload) ? asRecord(payload[0]) : null;
+      return compactProviderIdentity({ id: text(first?.tenantId), email: null, name: text(first?.tenantName) });
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function discoverOwnedNangoConnections(identity, options = {}) {
+  const rows = [];
+  for (let page = 0; page < NANGO_CONNECTION_MAX_PAGES; page += 1) {
+    const payload = await nangoRequest("/connections", {
+      query: { limit: NANGO_CONNECTION_PAGE_SIZE, page }
+    });
+    const pageRows = arrayAt(payload, "connections");
+    rows.push(...pageRows);
+    if (pageRows.length < NANGO_CONNECTION_PAGE_SIZE) break;
+  }
+  const discovered = rows.filter((row) => connectionIdentityMatches(row, identity)).map(discoveredConnection).filter((connection) => connection !== null);
+  const reconciled = await reconcileDiscoveredNangoConnections(identity, discovered);
+  if (options.resolveProviderIdentity === false) return reconciled;
+  const remoteByKey = new Map(discovered.map((connection) => [
+    `${connection.providerConfigKey}\0${connection.upstreamConnectionId}`,
+    connection
+  ]));
+  await Promise.all(reconciled.map(async (connection) => {
+    if (connection.lifecycleStatus !== "connected" || !connection.upstreamConnectionId) return;
+    const remote = remoteByKey.get(`${connection.providerConfigKey}\0${connection.upstreamConnectionId}`);
+    if (!remote) return;
+    const sourceUpdatedAt = remote.updatedAt ?? remote.createdAt ?? connection.lifecycleStatus;
+    const hasProviderIdentity = Boolean(
+      connection.providerAccountId || connection.providerAccountEmail || connection.providerAccountName
+    );
+    const checkedAt = connection.providerIdentityCheckedAt ? Date.parse(`${connection.providerIdentityCheckedAt.replace(" ", "T")}Z`) : Number.NaN;
+    const unavailableIdentityIsFresh = !hasProviderIdentity && Number.isFinite(checkedAt) && Date.now() - checkedAt < PROVIDER_IDENTITY_RETRY_MS;
+    if (connection.providerIdentitySourceUpdatedAt === sourceUpdatedAt && (hasProviderIdentity || unavailableIdentityIsFresh)) return;
+    const providerIdentity = await getNangoProviderAccountIdentity({
+      upstreamConnectionId: connection.upstreamConnectionId,
+      providerConfigKey: connection.providerConfigKey
+    });
+    await setServiceConnectionProviderIdentity({
+      connectionId: connection.id,
+      providerAccountId: providerIdentity?.id,
+      providerAccountEmail: providerIdentity?.email,
+      providerAccountName: providerIdentity?.name,
+      sourceUpdatedAt
+    });
+  }));
+  return reconcileDiscoveredNangoConnections(identity, discovered);
+}
+async function listNangoCatalogDirect() {
+  const [integrationsPayload, providersPayload] = await Promise.all([
+    nangoRequest("/integrations"),
+    nangoRequest("/providers")
+  ]);
+  const providers = /* @__PURE__ */ new Map();
+  for (const value of arrayAt(providersPayload, "providers")) {
+    const row = asRecord(value);
+    const name = text(row?.name);
+    if (row && name) providers.set(name, row);
+  }
+  return arrayAt(integrationsPayload, "integrations").flatMap((value) => {
+    const row = asRecord(value);
+    const id = text(row?.unique_key) ?? text(row?.id);
+    const provider = text(row?.provider);
+    if (!id || !provider) return [];
+    const definition = providers.get(provider);
+    return [{
+      id,
+      provider,
+      displayName: text(row?.display_name) ?? text(definition?.display_name) ?? id,
+      authMode: text(definition?.auth_mode),
+      categories: Array.isArray(definition?.categories) ? definition.categories : [],
+      docsUrl: text(definition?.docs),
+      logoUrl: text(row?.logo),
+      safeDefaultAllowedTools: [],
+      actionTools: [],
+      setupStatus: "ready"
+    }];
+  });
+}
+function connectDefaults(providerConfigKey) {
+  const scopes = {
+    linkedin: "openid profile email w_member_social",
+    "github-getting-started": "repo workflow read:org read:user user:email",
+    "google-drive": "openid profile email https://www.googleapis.com/auth/drive",
+    "google-search-console": "openid profile email https://www.googleapis.com/auth/webmasters.readonly https://www.googleapis.com/auth/webmasters"
+  };
+  const scope = scopes[providerConfigKey];
+  return scope ? { [providerConfigKey]: { connection_config: { oauth_scopes_override: scope } } } : void 0;
+}
+function sessionPayload(value) {
+  const root = asRecord(value);
+  const data = asRecord(root?.data) ?? root;
+  const connectLink = text(data?.connect_link);
+  if (!connectLink) throw new MainNangoTransportError("Nango did not return a connect link.", 502, "nango_missing_connect_link");
+  return { connectLink, expiresAt: text(data?.expires_at) };
+}
+async function createNangoSessionDirect(identity, providerConfigKey) {
+  const defaults = connectDefaults(providerConfigKey);
+  return sessionPayload(await nangoRequest("/connect/sessions", {
+    method: "POST",
+    body: {
+      tags: { end_user_id: identity, end_user_email: identity },
+      allowed_integrations: [providerConfigKey],
+      ...defaults ? { integrations_config_defaults: defaults } : {}
+    }
+  }));
+}
+async function createNangoReconnectSessionDirect(identity, connectionId) {
+  const connection = await requireOwnedActiveConnection(identity, connectionId, true);
+  const defaults = connectDefaults(connection.providerConfigKey);
+  return sessionPayload(await nangoRequest("/connect/sessions/reconnect", {
+    method: "POST",
+    body: {
+      connection_id: connection.upstreamConnectionId,
+      integration_id: connection.providerConfigKey,
+      tags: { end_user_id: identity, end_user_email: identity },
+      ...defaults ? { integrations_config_defaults: defaults } : {}
+    }
+  }));
+}
+async function deleteNangoConnectionDirect(identity, connectionId) {
+  const connection = await requireOwnedActiveConnection(identity, connectionId, true);
+  try {
+    await nangoRequest(`/connections/${encodeURIComponent(connection.upstreamConnectionId)}`, {
+      method: "DELETE",
+      query: { provider_config_key: connection.providerConfigKey }
+    });
+  } catch (error) {
+    if (!(error instanceof MainNangoTransportError) || error.status !== 404) throw error;
+  }
+}
+async function requireOwnedActiveConnection(identity, connectionId, allowNeedsReauth = false) {
+  const connection = await getOwnedServiceConnection(identity, connectionId);
+  if (!connection || connection.transport !== "nango" || !connection.upstreamConnectionId) {
+    throw new MainNangoTransportError("Service connection not found.", 404, "connection_not_found", false);
+  }
+  if (connection.lifecycleStatus !== "connected" && !(allowNeedsReauth && connection.lifecycleStatus === "needs_reauth")) {
+    throw new MainNangoTransportError("Service connection requires reconnection.", 409, "connection_inactive", false);
+  }
+  return connection;
+}
+async function withNangoClient(connection, run) {
+  const transport = new StreamableHTTPClientTransport(nangoMcpUrl(), {
+    requestInit: {
+      headers: {
+        Authorization: `Bearer ${nangoSecret()}`,
+        "connection-id": connection.upstreamConnectionId,
+        "provider-config-key": connection.providerConfigKey
+      }
+    }
+  });
+  const client = new Client({ name: "mcp-scraper-integrations", version: "1.0.0" }, { capabilities: {} });
+  try {
+    await client.connect(transport);
+    const value = await run(client);
+    await recordServiceConnectionHealth({
+      connectionId: connection.id,
+      operationalStatus: "available",
+      evidenceSource: "nango_mcp"
+    });
+    return value;
+  } catch (error) {
+    const normalized = normalizeNangoClientError(error);
+    await recordServiceConnectionHealth({
+      connectionId: connection.id,
+      operationalStatus: normalized.code === "connection_transport_unavailable" ? "unavailable" : "degraded",
+      failureCode: normalized.code,
+      retryable: normalized.retryable,
+      evidenceSource: "nango_mcp"
+    }).catch(() => void 0);
+    throw normalized;
+  } finally {
+    await client.close().catch(() => void 0);
+  }
+}
+async function probeNangoConnectionDirect(identity, connectionId) {
+  const connection = await requireOwnedActiveConnection(identity, connectionId);
+  const providerKey = connection.provider ?? connection.providerConfigKey;
+  if (providerKey !== "google-search-console") return;
+  await withNangoClient(connection, async (client) => {
+    const listed = await client.listTools();
+    if (!listed.tools.some((tool) => tool.name === "list-sites")) {
+      throw new MainNangoTransportError("The Search Console health-check tool is unavailable.", 404, "live_tool_missing", false);
+    }
+    await client.callTool({ name: "list-sites", arguments: {} });
+  });
+}
+async function listNangoToolsDirect(identity, connectionId) {
+  const connection = await requireOwnedActiveConnection(identity, connectionId);
+  const listed = await withNangoClient(connection, (client) => client.listTools());
+  const tools = listed.tools.flatMap((raw) => {
+    const inputSchema = asRecord(raw.inputSchema);
+    if (!raw.name || !inputSchema) return [];
+    return [{
+      name: raw.name,
+      ...raw.title ? { title: raw.title } : {},
+      ...raw.description ? { description: raw.description } : {},
+      inputSchema,
+      ...asRecord(raw.outputSchema) ? { outputSchema: asRecord(raw.outputSchema) } : {},
+      ...asRecord(raw.annotations) ? { annotations: asRecord(raw.annotations) } : {}
+    }];
+  });
+  const policies = buildConnectedToolPolicyRegistry({
+    tools,
+    connectionActive: connection.lifecycleStatus === "connected",
+    actionsEnabled: connection.actionsEnabled
+  });
+  const readTools = [...policies.values()].filter((policy) => policy.classification === "read").map((policy) => policy.name);
+  const actionTools = [...policies.values()].filter((policy) => policy.classification === "action").map((policy) => policy.name);
+  const revision = createHash2("sha256").update(JSON.stringify(tools.map((tool) => ({ name: tool.name, inputSchema: tool.inputSchema })))).digest("hex");
+  await updateServiceConnectionTools(connection.id, readTools, actionTools, revision);
+  const refreshed = await getOwnedServiceConnection(identity, connection.id);
+  return { connection: refreshed ?? { ...connection, readTools, actionTools, toolRevision: revision }, tools };
+}
+async function callNangoToolDirect(args) {
+  const { connection, tools } = await listNangoToolsDirect(args.identity, args.connectionId);
+  const selected = tools.find((tool) => tool.name === args.tool);
+  if (!selected) throw new MainNangoTransportError("The requested provider tool is unavailable.", 404, "live_tool_missing", false);
+  const policy = connectedToolPolicyOrThrow(buildConnectedToolPolicyRegistry({
+    tools,
+    connectionActive: connection.lifecycleStatus === "connected",
+    actionsEnabled: connection.actionsEnabled
+  }), selected.name);
+  if (policy.classification !== args.classification) {
+    throw new MainNangoTransportError("The provider tool classification does not match this operation.", 403, "tool_not_allowed", false);
+  }
+  if (!policy.available && policy.blockedReason === "actions_disabled") {
+    throw new MainNangoTransportError("Actions are disabled for this service connection.", 403, "actions_disabled", false);
+  }
+  if (!policy.available) {
+    throw new MainNangoTransportError("The provider tool is not authorized for this connection.", 403, "tool_not_allowed", false);
+  }
+  await preflightConnectedUsage({
+    identity: args.identity,
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION
+  });
+  const requestId = args.requestId?.trim() || randomUUID2();
+  const idempotencyKey = `main-nango:${createHash2("sha256").update(args.identity.toLowerCase()).update("\0").update(connection.id).update("\0").update(args.tool).update("\0").update(requestId).digest("hex")}`;
+  const startedAt = /* @__PURE__ */ new Date();
+  const started = performance.now();
+  let result;
+  let providerError;
+  try {
+    result = await withNangoClient(connection, (client) => callNangoToolWithBudget(client, args.tool, args.input));
+  } catch (error) {
+    providerError = error;
+  }
+  const completedAt = /* @__PURE__ */ new Date();
+  await settleConnectedUsage({
+    identity: args.identity,
+    idempotencyKey,
+    ratePolicyVersion: CONNECTED_USAGE_RATE_POLICY_VERSION,
+    connectionId: connection.id,
+    providerConfigKey: connection.providerConfigKey,
+    functionRuns: 1,
+    proxyRequests: 0,
+    computeMilliseconds: Math.max(0, Math.round(performance.now() - started)),
+    sourceSurface: "main_mcp",
+    metadata: {
+      toolName: args.tool,
+      operationKind: args.operationKind ?? args.classification,
+      outcome: providerError ? "error" : "partial",
+      requestId: requestId.length <= 200 ? requestId : createHash2("sha256").update(requestId).digest("hex"),
+      startedAt: startedAt.toISOString(),
+      completedAt: completedAt.toISOString()
+    }
+  });
+  if (providerError) throw providerError;
+  return result;
+}
+async function describeNangoToolDirect(identity, connectionId, toolName) {
+  const { connection, tools } = await listNangoToolsDirect(identity, connectionId);
+  const tool = tools.find((candidate) => candidate.name === toolName);
+  if (!tool) throw new MainNangoTransportError("The requested provider tool is unavailable.", 404, "live_tool_missing", false);
+  const policy = connectedToolPolicyOrThrow(buildConnectedToolPolicyRegistry({
+    tools,
+    connectionActive: connection.lifecycleStatus === "connected",
+    actionsEnabled: connection.actionsEnabled
+  }), tool.name);
+  const classification = classifyConnectedTool(tool);
+  const callable = policy.available;
+  const projected = {
+    name: tool.name,
+    ...tool.title ? { title: tool.title } : {},
+    ...tool.description ? { description: tool.description } : {},
+    inputSchema: tool.inputSchema,
+    ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {},
+    ...tool.annotations ? { annotations: tool.annotations } : {}
+  };
+  return {
+    ...projected,
+    classification,
+    callable,
+    blockedReason: policy.blockedReason,
+    requiredPermissions: policy.requiredPermissions,
+    missingPermissions: policy.missingPermissions,
+    requiredFeatures: policy.requiredFeatures,
+    missingFeatures: policy.missingFeatures,
+    transport: "nango",
+    providerConfigKey: connection.providerConfigKey,
+    providerContractVersion: MAIN_INTEGRATION_CONTRACT_VERSION,
+    providerContractHash: MAIN_INTEGRATION_CONTRACT_HASH,
+    protocolVersion: null,
+    schemaSource: "live_tools_list",
+    schemaHash: createHash2("sha256").update(JSON.stringify(projected)).digest("hex"),
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/api/gmail-selection-repository.ts
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
+var GMAIL_SELECTION_TTL_MS = 24 * 60 * 60 * 1e3;
+var GMAIL_SELECTION_MAX_MESSAGES = 5e3;
+var GmailSelectionError = class extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "GmailSelectionError";
+  }
+  code;
+  status;
+};
+var schemaReady = null;
+var schemaDb = null;
+function stableGmailJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableGmailJson).join(",")}]`;
+  return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableGmailJson(item)}`).join(",")}}`;
+}
+function gmailFingerprint(value) {
+  return createHash3("sha256").update(stableGmailJson(value)).digest("hex");
+}
+async function ensureGmailSelectionSchema() {
+  const db = getDb();
+  if (schemaReady && schemaDb === db) return schemaReady;
+  schemaDb = db;
+  schemaReady = (async () => {
+    await db.execute(`
+      CREATE TABLE IF NOT EXISTS gmail_selections (
+        selection_id TEXT PRIMARY KEY,
+        owner_identity TEXT NOT NULL,
+        connection_id TEXT NOT NULL,
+        purpose TEXT NOT NULL,
+        source_json TEXT NOT NULL,
+        message_ids_json TEXT NOT NULL,
+        message_count INTEGER NOT NULL,
+        selection_sha256 TEXT NOT NULL,
+        provider_snapshot_json TEXT,
+        created_at TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        UNIQUE(owner_identity, connection_id, purpose, selection_sha256)
+      )
+    `);
+    await db.execute(`CREATE INDEX IF NOT EXISTS gmail_selections_owner_expiry ON gmail_selections(owner_identity, expires_at)`);
+    await db.execute(`
+      CREATE TABLE IF NOT EXISTS gmail_action_executions (
+        action_id TEXT PRIMARY KEY,
+        owner_identity TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        status TEXT NOT NULL,
+        result_json TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE(owner_identity, idempotency_key)
+      )
+    `);
+    await db.execute(`CREATE INDEX IF NOT EXISTS gmail_actions_owner_updated ON gmail_action_executions(owner_identity, updated_at)`);
+    await db.execute(`CREATE TABLE IF NOT EXISTS gmail_action_chunks (
+      action_id TEXT NOT NULL, chunk_key TEXT NOT NULL, status TEXT NOT NULL,
+      result_json TEXT, updated_at TEXT NOT NULL,
+      PRIMARY KEY(action_id, chunk_key)
+    )`);
+    await db.execute(`CREATE TABLE IF NOT EXISTS gmail_selection_exports (
+      selection_id TEXT PRIMARY KEY, owner_identity TEXT NOT NULL, fingerprint TEXT NOT NULL,
+      status TEXT NOT NULL, result_json TEXT, updated_at TEXT NOT NULL
+    )`);
+  })().catch((error) => {
+    schemaReady = null;
+    schemaDb = null;
+    throw error;
+  });
+  return schemaReady;
+}
+function normalizeMessageIds(values) {
+  const ids = [...new Set(values.map((value) => value.trim()).filter((value) => /^[A-Za-z0-9_-]+$/.test(value)))];
+  ids.sort();
+  return ids;
+}
+function rowToSelection(row) {
+  return {
+    selectionId: String(row.selection_id),
+    ownerId: String(row.owner_identity),
+    connectionId: String(row.connection_id),
+    purpose: String(row.purpose),
+    source: JSON.parse(String(row.source_json)),
+    messageIds: JSON.parse(String(row.message_ids_json)),
+    count: Number(row.message_count),
+    selectionSha256: String(row.selection_sha256),
+    createdAt: String(row.created_at),
+    expiresAt: String(row.expires_at),
+    providerSnapshot: typeof row.provider_snapshot_json === "string" ? JSON.parse(row.provider_snapshot_json) : null
+  };
+}
+async function createOrGetGmailSelection(args) {
+  await ensureGmailSelectionSchema();
+  const messageIds = normalizeMessageIds(args.resolvedMessageIds);
+  if (messageIds.length === 0) throw new GmailSelectionError("selection_empty", "No Gmail messages matched the selection.");
+  if (messageIds.length > GMAIL_SELECTION_MAX_MESSAGES) {
+    throw new GmailSelectionError("selection_too_large", `Narrow the Gmail selection to at most ${GMAIL_SELECTION_MAX_MESSAGES} messages.`);
+  }
+  const normalizedSource = args.source.kind === "query" ? { kind: "query", query: args.source.query.trim().replace(/\s+/g, " ") } : { kind: "message_ids", messageIds: normalizeMessageIds(args.source.messageIds) };
+  const selectionSha256 = gmailFingerprint({ connectionId: args.connectionId, purpose: args.purpose, source: normalizedSource, messageIds });
+  const existing = await getDb().execute({
+    sql: `SELECT * FROM gmail_selections WHERE owner_identity = ? AND connection_id = ? AND purpose = ? AND selection_sha256 = ? AND expires_at > ? LIMIT 1`,
+    args: [args.ownerId, args.connectionId, args.purpose, selectionSha256, (args.now ?? /* @__PURE__ */ new Date()).toISOString()]
+  });
+  if (existing.rows[0]) return rowToSelection(existing.rows[0]);
+  const createdAt = args.now ?? /* @__PURE__ */ new Date();
+  const record2 = {
+    selectionId: `gsel_${randomUUID3().replace(/-/g, "")}`,
+    ownerId: args.ownerId,
+    connectionId: args.connectionId,
+    purpose: args.purpose,
+    source: normalizedSource,
+    messageIds,
+    count: messageIds.length,
+    selectionSha256,
+    createdAt: createdAt.toISOString(),
+    expiresAt: new Date(createdAt.getTime() + GMAIL_SELECTION_TTL_MS).toISOString(),
+    providerSnapshot: args.providerSnapshot ?? null
+  };
+  await getDb().execute({
+    sql: `INSERT INTO gmail_selections (selection_id, owner_identity, connection_id, purpose, source_json, message_ids_json, message_count, selection_sha256, provider_snapshot_json, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [record2.selectionId, record2.ownerId, record2.connectionId, record2.purpose, JSON.stringify(record2.source), JSON.stringify(record2.messageIds), record2.count, record2.selectionSha256, record2.providerSnapshot ? JSON.stringify(record2.providerSnapshot) : null, record2.createdAt, record2.expiresAt]
+  });
+  return record2;
+}
+async function getOwnedGmailSelection(args) {
+  await ensureGmailSelectionSchema();
+  const result = await getDb().execute({
+    sql: `SELECT * FROM gmail_selections WHERE selection_id = ? AND owner_identity = ? AND connection_id = ? AND expires_at > ? LIMIT 1`,
+    args: [args.selectionId, args.ownerId, args.connectionId, (args.now ?? /* @__PURE__ */ new Date()).toISOString()]
+  });
+  const row = result.rows[0];
+  if (!row) throw new GmailSelectionError("selection_not_found", "Gmail selection not found.", 404);
+  return rowToSelection(row);
+}
+function assertGmailSelectionReceipt(selection, expectedCount, selectionSha256) {
+  if (expectedCount !== selection.count || selectionSha256 !== selection.selectionSha256) {
+    throw new GmailSelectionError("selection_changed", "The Gmail selection receipt does not match the immutable selection.", 409);
+  }
+}
+function rowToAction(row) {
+  return {
+    actionId: String(row.action_id),
+    ownerId: String(row.owner_identity),
+    idempotencyKey: String(row.idempotency_key),
+    fingerprint: String(row.fingerprint),
+    status: String(row.status),
+    result: typeof row.result_json === "string" ? JSON.parse(row.result_json) : null,
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at)
+  };
+}
+async function beginGmailAction(args) {
+  await ensureGmailSelectionSchema();
+  const key = args.idempotencyKey.trim();
+  if (key.length < 8 || key.length > 200) throw new GmailSelectionError("idempotency_key_invalid", "Idempotency-Key must be 8-200 characters.");
+  const existing = await getDb().execute({
+    sql: `SELECT * FROM gmail_action_executions WHERE owner_identity = ? AND idempotency_key = ? LIMIT 1`,
+    args: [args.ownerId, key]
+  });
+  if (existing.rows[0]) {
+    const execution2 = rowToAction(existing.rows[0]);
+    if (execution2.fingerprint !== args.fingerprint) {
+      throw new GmailSelectionError("idempotency_conflict", "This Idempotency-Key is already bound to a different Gmail action.", 409);
+    }
+    if (execution2.status === "running" && !execution2.result && Date.now() - Date.parse(execution2.updatedAt) > 6e4) {
+      const now2 = (/* @__PURE__ */ new Date()).toISOString();
+      const claimed = await getDb().execute({ sql: `UPDATE gmail_action_executions SET updated_at = ? WHERE action_id = ? AND updated_at = ?`, args: [now2, execution2.actionId, execution2.updatedAt] });
+      if (Number(claimed.rowsAffected ?? 0) === 1) return { execution: { ...execution2, updatedAt: now2 }, replay: false };
+    }
+    return { execution: execution2, replay: true };
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const execution = {
+    actionId: `gact_${randomUUID3().replace(/-/g, "")}`,
+    ownerId: args.ownerId,
+    idempotencyKey: key,
+    fingerprint: args.fingerprint,
+    status: "running",
+    result: null,
+    createdAt: now,
+    updatedAt: now
+  };
+  try {
+    await getDb().execute({
+      sql: `INSERT INTO gmail_action_executions (action_id, owner_identity, idempotency_key, fingerprint, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'running', ?, ?)`,
+      args: [execution.actionId, execution.ownerId, execution.idempotencyKey, execution.fingerprint, now, now]
+    });
+  } catch {
+    const raced = await getDb().execute({ sql: `SELECT * FROM gmail_action_executions WHERE owner_identity = ? AND idempotency_key = ? LIMIT 1`, args: [args.ownerId, key] });
+    if (!raced.rows[0]) throw new GmailSelectionError("action_claim_failed", "The Gmail action could not be claimed.", 409);
+    const existingExecution = rowToAction(raced.rows[0]);
+    if (existingExecution.fingerprint !== args.fingerprint) throw new GmailSelectionError("idempotency_conflict", "This Idempotency-Key is already bound to a different Gmail action.", 409);
+    return { execution: existingExecution, replay: true };
+  }
+  return { execution, replay: false };
+}
+async function touchGmailAction(actionId) {
+  await ensureGmailSelectionSchema();
+  await getDb().execute({ sql: `UPDATE gmail_action_executions SET updated_at = ? WHERE action_id = ? AND status = 'running'`, args: [(/* @__PURE__ */ new Date()).toISOString(), actionId] });
+}
+function rowToChunk(row) {
+  return { actionId: String(row.action_id), chunkKey: String(row.chunk_key), status: String(row.status), result: typeof row.result_json === "string" ? JSON.parse(row.result_json) : null, updatedAt: String(row.updated_at) };
+}
+async function claimGmailActionChunk(actionId, chunkKey) {
+  await ensureGmailSelectionSchema();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    await getDb().execute({ sql: `INSERT INTO gmail_action_chunks (action_id, chunk_key, status, updated_at) VALUES (?, ?, 'running', ?)`, args: [actionId, chunkKey, now] });
+    return { receipt: { actionId, chunkKey, status: "running", result: null, updatedAt: now }, claimed: true };
+  } catch {
+    const row = await getDb().execute({ sql: `SELECT * FROM gmail_action_chunks WHERE action_id = ? AND chunk_key = ? LIMIT 1`, args: [actionId, chunkKey] });
+    if (!row.rows[0]) throw new GmailSelectionError("action_chunk_claim_failed", "The Gmail action chunk could not be claimed.", 409);
+    return { receipt: rowToChunk(row.rows[0]), claimed: false };
+  }
+}
+async function finishGmailActionChunk(actionId, chunkKey, status, result) {
+  await ensureGmailSelectionSchema();
+  await getDb().execute({ sql: `UPDATE gmail_action_chunks SET status = ?, result_json = ?, updated_at = ? WHERE action_id = ? AND chunk_key = ?`, args: [status, JSON.stringify(result), (/* @__PURE__ */ new Date()).toISOString(), actionId, chunkKey] });
+}
+async function beginGmailSelectionExport(args) {
+  await ensureGmailSelectionSchema();
+  const existing = await getDb().execute({ sql: `SELECT * FROM gmail_selection_exports WHERE selection_id = ? AND owner_identity = ? LIMIT 1`, args: [args.selectionId, args.ownerId] });
+  if (existing.rows[0]) {
+    const row = existing.rows[0];
+    if (String(row.fingerprint) !== args.fingerprint) throw new GmailSelectionError("export_conflict", "This Gmail selection export receipt conflicts with the stored export.", 409);
+    const replay = typeof row.result_json === "string" ? JSON.parse(row.result_json) : null;
+    if (replay) return { replay, claimed: false };
+    if (Date.now() - Date.parse(String(row.updated_at)) > 5 * 6e4) {
+      const updated = await getDb().execute({ sql: `UPDATE gmail_selection_exports SET updated_at = ? WHERE selection_id = ? AND owner_identity = ? AND updated_at = ?`, args: [(/* @__PURE__ */ new Date()).toISOString(), args.selectionId, args.ownerId, String(row.updated_at)] });
+      if (Number(updated.rowsAffected ?? 0) === 1) return { replay: null, claimed: true };
+    }
+    return { replay: null, claimed: false };
+  }
+  try {
+    await getDb().execute({ sql: `INSERT INTO gmail_selection_exports (selection_id, owner_identity, fingerprint, status, updated_at) VALUES (?, ?, ?, 'running', ?)`, args: [args.selectionId, args.ownerId, args.fingerprint, (/* @__PURE__ */ new Date()).toISOString()] });
+    return { replay: null, claimed: true };
+  } catch {
+    const raced = await getDb().execute({ sql: `SELECT * FROM gmail_selection_exports WHERE selection_id = ? AND owner_identity = ? LIMIT 1`, args: [args.selectionId, args.ownerId] });
+    if (!raced.rows[0]) throw new GmailSelectionError("export_claim_failed", "The Gmail export could not be claimed.", 409);
+    const row = raced.rows[0];
+    if (String(row.fingerprint) !== args.fingerprint) throw new GmailSelectionError("export_conflict", "This Gmail selection export receipt conflicts with the stored export.", 409);
+    return { replay: typeof row.result_json === "string" ? JSON.parse(row.result_json) : null, claimed: false };
+  }
+}
+async function finishGmailSelectionExport(ownerId, selectionId, result) {
+  await ensureGmailSelectionSchema();
+  await getDb().execute({ sql: `UPDATE gmail_selection_exports SET status = 'complete', result_json = ?, updated_at = ? WHERE selection_id = ? AND owner_identity = ?`, args: [JSON.stringify(result), (/* @__PURE__ */ new Date()).toISOString(), selectionId, ownerId] });
+}
+async function finishGmailAction(actionId, status, result) {
+  await ensureGmailSelectionSchema();
+  const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await getDb().execute({
+    sql: `UPDATE gmail_action_executions SET status = ?, result_json = ?, updated_at = ? WHERE action_id = ?`,
+    args: [status, JSON.stringify(result), updatedAt, actionId]
+  });
+  const row = await getDb().execute({ sql: `SELECT * FROM gmail_action_executions WHERE action_id = ? LIMIT 1`, args: [actionId] });
+  if (!row.rows[0]) throw new GmailSelectionError("action_not_found", "Gmail action not found.", 404);
+  return rowToAction(row.rows[0]);
+}
+
+// src/api/gmail-service.ts
+var GMAIL_MAIN_CONTRACT_VERSION = "2026-08-27.1";
+var GMAIL_MAIN_CONTRACT_HASH = "9c82b270bb70e7795814cac408a41786ec70d4d7a4bb0f4a11bcc1b7fd02088b";
+var GMAIL_INLINE_BODY_BYTES = 2e4;
+var GMAIL_ATTACHMENT_REF_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var GmailServiceError = class extends Error {
+  constructor(code, message, status = 400, retryable = status === 429 || status >= 500, retryAfterMs = null) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "GmailServiceError";
+  }
+  code;
+  status;
+  retryable;
+  retryAfterMs;
+};
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function base64urlDecode(value) {
+  if (!/^[A-Za-z0-9_-]*={0,2}$/.test(value)) throw new GmailServiceError("gmail_invalid_base64", "Gmail returned invalid encoded content.", 502);
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="), "base64");
+}
+function decodeQuotedPrintable(buffer) {
+  const source = buffer.toString("latin1").replace(/=\r?\n/g, "");
+  const bytes = [];
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "=" && /^[0-9A-Fa-f]{2}$/.test(source.slice(index + 1, index + 3))) {
+      bytes.push(Number.parseInt(source.slice(index + 1, index + 3), 16));
+      index += 2;
+    } else bytes.push(source.charCodeAt(index) & 255);
+  }
+  return Buffer.from(bytes);
+}
+function decodeEncodedWords(value) {
+  return value.replace(/=\?([^?]+)\?([bq])\?([^?]+)\?=/gi, (_match, charset, encoding, body) => {
+    try {
+      const bytes = encoding.toLowerCase() === "b" ? Buffer.from(body, "base64") : decodeQuotedPrintable(Buffer.from(body.replace(/_/g, " "), "latin1"));
+      return /^(?:utf-8|us-ascii)$/i.test(charset) ? bytes.toString("utf8") : bytes.toString("latin1");
+    } catch {
+      return body;
+    }
+  });
+}
+function normalizeHeaders(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    const row = record(item);
+    const name = stringValue(row?.name);
+    const raw = stringValue(row?.value);
+    if (!name || raw === null) return [];
+    return [{ name, value: decodeEncodedWords(raw.replace(/\r?\n[ \t]+/g, " ")) }];
+  });
+}
+function header(headers, name) {
+  return headers.find((item) => item.name.toLowerCase() === name.toLowerCase())?.value ?? null;
+}
+function parseGmailAddresses(value) {
+  if (!value) return [];
+  const tokens = value.match(/(?:"(?:[^"\\]|\\.)*"|[^,])+/g) ?? [];
+  return tokens.flatMap((token) => {
+    const trimmed = token.trim();
+    const angled = trimmed.match(/^(.*?)\s*<([^<>\s]+@[^<>\s]+)>$/);
+    const email = (angled?.[2] ?? trimmed).replace(/^mailto:/i, "").trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return [];
+    const name = angled?.[1]?.trim().replace(/^"|"$/g, "") || null;
+    return [{ name: name ? decodeEncodedWords(name) : null, email }];
+  });
+}
+function transferDecoded(data, headers) {
+  const decoded = base64urlDecode(data);
+  const transfer = header(headers, "content-transfer-encoding")?.toLowerCase();
+  if (transfer === "quoted-printable") return decodeQuotedPrintable(decoded);
+  if (transfer === "base64") {
+    const text2 = decoded.toString("ascii").replace(/\s/g, "");
+    return /^[A-Za-z0-9+/]*={0,2}$/.test(text2) ? Buffer.from(text2, "base64") : decoded;
+  }
+  return decoded;
+}
+function sanitizeHtml(value) {
+  const textOnly = value.replace(/<!--[\s\S]*?-->/g, "").replace(/<!doctype\b[^>]*>/gi, "").replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<(?:iframe|object|embed|svg|math)\b[^>]*>[\s\S]*?<\/(?:iframe|object|embed|svg|math)>/gi, "").replace(/<\/?(?:script|style|iframe|object|embed|svg|math|form|input|button|textarea|select|option|meta|link|base|img|audio|video|source|track)\b[^>]*>/gi, "").replace(/\son\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "").replace(/\s(?:href|src|srcset|action|formaction|poster|background|xlink:href)\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, "").replace(/<[^>]*>/g, " ");
+  return textOnly.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\s+/g, " ").trim();
+}
+function refSecret() {
+  return createHash4("sha256").update(getSessionSecret()).update("\0gmail-ref-v1").digest();
+}
+function signOpaque(payload) {
+  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const signature = createHmac("sha256", refSecret()).update(encoded).digest("base64url");
+  return `gref1.${encoded}.${signature}`;
+}
+function verifyOpaque(value, ownerId, kind) {
+  const [version, encoded, signature] = value.split(".");
+  if (version !== "gref1" || !encoded || !signature) throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+  const expected = createHmac("sha256", refSecret()).update(encoded).digest();
+  let supplied;
+  try {
+    supplied = Buffer.from(signature, "base64url");
+  } catch {
+    throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+  }
+  if (expected.length !== supplied.length || !timingSafeEqual(expected, supplied)) throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+  }
+  if (payload.ownerId !== ownerId || payload.kind !== kind || typeof payload.expiresAt !== "number" || payload.expiresAt <= Date.now()) {
+    throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+  }
+  return payload;
+}
+function attachmentRef(args) {
+  return signOpaque({ kind: "attachment", ...args, expiresAt: Date.now() + GMAIL_ATTACHMENT_REF_TTL_MS });
+}
+function canonicalPart(args) {
+  const headers = normalizeHeaders(args.part.headers);
+  const body = record(args.part.body);
+  const mimeType = stringValue(args.part.mimeType)?.toLowerCase() ?? "application/octet-stream";
+  const filename = decodeEncodedWords(stringValue(args.part.filename) ?? "");
+  const partId = stringValue(args.part.partId) ?? args.path;
+  const data = stringValue(body?.data);
+  const attachmentId = stringValue(body?.attachmentId);
+  const contentId = header(headers, "content-id")?.replace(/^<|>$/g, "") ?? null;
+  const inline = /^inline\b/i.test(header(headers, "content-disposition") ?? "") || !!contentId;
+  const isText = mimeType.startsWith("text/");
+  let text2 = null;
+  let contentComplete = true;
+  if (isText && data) {
+    const decoded = transferDecoded(data, headers);
+    text2 = decoded.toString("utf8");
+  } else if (isText && attachmentId) contentComplete = false;
+  const isAttachment = !!filename || !!attachmentId || inline && !!data && !isText;
+  let opaqueRef = null;
+  const decodedSize = numberValue(body?.size) ?? (data ? base64urlDecode(data).byteLength : 0);
+  if (isAttachment) {
+    const attachmentSize = decodedSize;
+    opaqueRef = attachmentRef({ ownerId: args.ownerId, connectionId: args.connectionId, messageId: args.messageId, partId, attachmentId, filename: filename || `gmail-${args.messageId}-${partId}`, mimeType, size: attachmentSize });
+    args.attachments.push({ filename: filename || `gmail-${args.messageId}-${partId}`, declaredMime: mimeType, size: attachmentSize, inline, contentId, partId, attachmentRef: opaqueRef });
+  }
+  const parts = Array.isArray(args.part.parts) ? args.part.parts.map((child, index) => canonicalPart({ ...args, part: record(child) ?? {}, path: `${args.path}.${index + 1}` })) : [];
+  return { partId, mimeType, filename, headers, size: decodedSize, inline, contentId, contentComplete, text: text2, attachmentRef: opaqueRef, parts };
+}
+function collectText(part, mime) {
+  const own = part.mimeType === mime && part.text !== null ? [part.text] : [];
+  return [...own, ...part.parts.flatMap((child) => collectText(child, mime))];
+}
+function normalizeGmailMessage(args) {
+  const source = record(args.payload);
+  const messageId = stringValue(source?.id);
+  const root = record(source?.payload);
+  if (!messageId || !root) throw new GmailServiceError("gmail_invalid_message", "Gmail returned an invalid message.", 502);
+  const attachments = [];
+  const mime = canonicalPart({ part: root, ownerId: args.ownerId, connectionId: args.connectionId, messageId, path: "0", attachments });
+  const headers = mime.headers;
+  const plain = collectText(mime, "text/plain").join("\n").trim() || null;
+  const htmlRaw = collectText(mime, "text/html").join("\n").trim() || null;
+  return {
+    messageId,
+    threadId: stringValue(source?.threadId),
+    messageIdHeader: header(headers, "message-id"),
+    internalDate: stringValue(source?.internalDate) ? new Date(Number(source.internalDate)).toISOString() : null,
+    headers,
+    from: parseGmailAddresses(header(headers, "from")),
+    to: parseGmailAddresses(header(headers, "to")),
+    cc: parseGmailAddresses(header(headers, "cc")),
+    bcc: parseGmailAddresses(header(headers, "bcc")),
+    replyTo: parseGmailAddresses(header(headers, "reply-to")),
+    subject: header(headers, "subject"),
+    labels: Array.isArray(source?.labelIds) ? source.labelIds.filter((item) => typeof item === "string") : [],
+    snippet: stringValue(source?.snippet),
+    plainText: plain,
+    sanitizedHtml: htmlRaw ? sanitizeHtml(htmlRaw) : null,
+    contentComplete: allPartsComplete(mime),
+    providerSizeEstimate: numberValue(source?.sizeEstimate),
+    mime,
+    attachments,
+    provenance: { provider: "gmail", connectionId: args.connectionId, fetchedAt: (args.fetchedAt ?? /* @__PURE__ */ new Date()).toISOString(), format: "full" }
+  };
+}
+function allPartsComplete(part) {
+  return part.contentComplete && part.parts.every(allPartsComplete);
+}
+var GmailService = class {
+  providerCall;
+  createArtifact;
+  createJsonlArtifact;
+  constructor(dependencies = {}) {
+    this.providerCall = dependencies.providerCall ?? callGmailProviderProxyDirect;
+    this.createArtifact = dependencies.createArtifact ?? createConnectedDataBinaryArtifact;
+    this.createJsonlArtifact = dependencies.createJsonlArtifact ?? createConnectedDataArtifact;
+  }
+  async searchMessages(args) {
+    const query = args.query.trim();
+    if (!query || query.length > 2e3) throw new GmailServiceError("invalid_request", "A Gmail query of at most 2,000 characters is required.");
+    const requestedLimit = args.limit ?? 25;
+    if (!Number.isInteger(requestedLimit) || requestedLimit < 1 || requestedLimit > 500) throw new GmailServiceError("invalid_request", "Gmail search limit must be an integer from 1 to 500.");
+    const limit = requestedLimit;
+    let pageToken;
+    if (args.cursor) {
+      const cursor = verifyOpaque(args.cursor, args.ownerId, "search_cursor");
+      if (cursor.connectionId !== args.connectionId || cursor.query !== query) throw new GmailServiceError("cursor_not_found", "Gmail cursor not found.", 404, false);
+      pageToken = stringValue(cursor.pageToken) ?? void 0;
+    }
+    const payload = record(await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "GET", path: "/gmail/v1/users/me/messages", query: { q: query, maxResults: limit, pageToken } }));
+    const messages = Array.isArray(payload?.messages) ? payload.messages.flatMap((item) => {
+      const row = record(item);
+      const id = stringValue(row?.id);
+      return id ? [{ messageId: id, threadId: stringValue(row?.threadId) }] : [];
+    }) : [];
+    const nextToken = stringValue(payload?.nextPageToken);
+    return {
+      messages,
+      estimatedMatches: numberValue(payload?.resultSizeEstimate),
+      complete: !nextToken,
+      truncated: !!nextToken,
+      nextCursor: nextToken ? signOpaque({ kind: "search_cursor", ownerId: args.ownerId, connectionId: args.connectionId, query, pageToken: nextToken, expiresAt: Date.now() + 24 * 60 * 60 * 1e3 }) : null
+    };
+  }
+  async getMessage(args) {
+    const complete = await this.getCompleteMessage(args);
+    const needsArtifact = !!complete.canonicalArtifact;
+    const inlinePlain = complete.plainText && Buffer.byteLength(complete.plainText) > GMAIL_INLINE_BODY_BYTES ? `${Buffer.from(complete.plainText).subarray(0, GMAIL_INLINE_BODY_BYTES).toString("utf8")}\u2026` : complete.plainText;
+    return { ...complete, plainText: inlinePlain, contentComplete: complete.contentComplete && !needsArtifact };
+  }
+  async getCompleteMessage(args) {
+    if (!/^[A-Za-z0-9_-]+$/.test(args.messageId)) throw new GmailServiceError("invalid_request", "A valid Gmail message ID is required.");
+    const encodedId = encodeURIComponent(args.messageId);
+    const identity = args.providerIdentity ?? args.ownerId;
+    const full = await this.providerCall({ identity, connectionId: args.connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodedId}`, query: { format: "full" } });
+    const normalized = normalizeGmailMessage({ ownerId: args.ownerId, connectionId: args.connectionId, payload: full });
+    let rawArtifact = null;
+    if (args.includeRawArtifact !== false) {
+      const rawPayload = record(await this.providerCall({ identity, connectionId: args.connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodedId}`, query: { format: "raw" } }));
+      const raw = stringValue(rawPayload?.raw);
+      if (!raw) throw new GmailServiceError("gmail_raw_unavailable", "Gmail did not return the raw message.", 502);
+      rawArtifact = await this.createArtifact({ ownerId: args.ownerId, exportId: `gmail-raw-${args.messageId}`, filename: `${args.messageId}.eml`, content: base64urlDecode(raw), contentType: "message/rfc822" });
+    }
+    const serialized = JSON.stringify(normalized);
+    const needsArtifact = Buffer.byteLength(serialized) > GMAIL_INLINE_BODY_BYTES || !normalized.contentComplete;
+    const canonicalArtifact = needsArtifact ? await this.createArtifact({ ownerId: args.ownerId, exportId: `gmail-message-${args.messageId}`, filename: `${args.messageId}.json`, content: serialized, contentType: "application/json" }) : null;
+    return { ...normalized, rawArtifact, canonicalArtifact };
+  }
+  async getAttachment(args) {
+    const ref = verifyOpaque(args.attachmentRef, args.ownerId, "attachment");
+    const connectionId = stringValue(ref.connectionId);
+    const messageId = stringValue(ref.messageId);
+    if (!connectionId || !messageId) throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+    let bytes;
+    const attachmentId = stringValue(ref.attachmentId);
+    if (attachmentId) {
+      const payload = record(await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}` }));
+      const data = stringValue(payload?.data);
+      if (!data) throw new GmailServiceError("gmail_attachment_unavailable", "Gmail did not return attachment bytes.", 502);
+      bytes = base64urlDecode(data);
+      const providerSize = numberValue(payload?.size);
+      if (providerSize !== null && providerSize !== bytes.byteLength) throw new GmailServiceError("gmail_attachment_size_mismatch", "Gmail attachment bytes did not match the declared size.", 502);
+    } else {
+      const full = record(await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}`, query: { format: "full" } }));
+      const data = findPartData(record(full?.payload), stringValue(ref.partId) ?? "");
+      if (!data) throw new GmailServiceError("reference_not_found", "Gmail reference not found.", 404, false);
+      bytes = base64urlDecode(data);
+    }
+    const declaredMime = stringValue(ref.mimeType) ?? "application/octet-stream";
+    const signedSize = numberValue(ref.size);
+    if (signedSize !== null && signedSize > 0 && signedSize !== bytes.byteLength) throw new GmailServiceError("gmail_attachment_size_mismatch", "Gmail attachment bytes did not match the reviewed MIME part size.", 502);
+    const observedMime = sniffMime(bytes, declaredMime);
+    const filename = stringValue(ref.filename) ?? `gmail-${messageId}.bin`;
+    const artifact = await this.createArtifact({ ownerId: args.ownerId, exportId: `gmail-attachment-${messageId}`, filename, content: bytes, contentType: observedMime });
+    const text2 = observedMime.startsWith("text/") || observedMime === "application/json" ? bytes.subarray(0, GMAIL_INLINE_BODY_BYTES).toString("utf8") : null;
+    return { filename, declaredMime, observedMime, bytes: bytes.byteLength, sha256: createHash4("sha256").update(bytes).digest("hex"), contentComplete: text2 !== null ? bytes.byteLength <= GMAIL_INLINE_BODY_BYTES : true, text: text2, artifact };
+  }
+  async prepareSelection(args) {
+    let ids;
+    let providerSnapshot = null;
+    if (args.source.kind === "message_ids") {
+      if (!args.source.messageIds.length || args.source.messageIds.some((id) => typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id.trim()))) throw new GmailServiceError("invalid_request", "Every explicit Gmail message ID must be valid.");
+      ids = [...new Set(args.source.messageIds.map((id) => id.trim()))];
+      for (const messageId of ids) {
+        try {
+          await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}`, query: { format: "metadata" } });
+        } catch {
+          throw new GmailServiceError("selection_message_not_found", "One or more explicit Gmail message IDs do not exist in this connection.", 404, false);
+        }
+      }
+    } else {
+      ids = [];
+      let pageToken;
+      let estimated = null;
+      do {
+        const payload = record(await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "GET", path: "/gmail/v1/users/me/messages", query: { q: args.source.query.trim(), maxResults: 500, pageToken } }));
+        if (estimated === null) estimated = numberValue(payload?.resultSizeEstimate);
+        for (const item of Array.isArray(payload?.messages) ? payload.messages : []) {
+          const id = stringValue(record(item)?.id);
+          if (id) ids.push(id);
+        }
+        if (new Set(ids).size > 5e3) throw new GmailServiceError("selection_too_large", "Narrow the Gmail selection to at most 5,000 messages.");
+        pageToken = stringValue(payload?.nextPageToken) ?? void 0;
+      } while (pageToken);
+      if (args.exactRange) {
+        const fromMs = Date.parse(args.exactRange.from);
+        const toMs = Date.parse(args.exactRange.to);
+        if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || fromMs >= toMs) throw new GmailServiceError("invalid_request", "exactRange.from must be before exactRange.to.");
+        const exactIds = [];
+        for (const messageId of ids) {
+          const full = await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "GET", path: `/gmail/v1/users/me/messages/${encodeURIComponent(messageId)}`, query: { format: "full" } });
+          const normalized = normalizeGmailMessage({ ownerId: args.ownerId, connectionId: args.connectionId, payload: full });
+          const internalMs = normalized.internalDate ? Date.parse(normalized.internalDate) : Number.NaN;
+          if (Number.isFinite(internalMs) && internalMs >= fromMs && internalMs < toMs) exactIds.push(messageId);
+        }
+        ids = exactIds;
+      }
+      providerSnapshot = { estimatedMatches: estimated, pagesComplete: true, ...args.exactRange ? { exactRange: args.exactRange } : {} };
+    }
+    return createOrGetGmailSelection({ ownerId: args.ownerId, connectionId: args.connectionId, source: args.source, purpose: args.purpose, resolvedMessageIds: ids, providerSnapshot });
+  }
+  async exportSelection(args) {
+    const selection = await getOwnedGmailSelection(args);
+    if (selection.purpose !== "export" && selection.purpose !== "scheduled_export") throw new GmailServiceError("selection_purpose_mismatch", "This Gmail selection was not prepared for export.", 409, false);
+    assertGmailSelectionReceipt(selection, args.expectedCount, args.selectionSha256);
+    const exportFingerprint = gmailFingerprint({ selectionId: selection.selectionId, selectionSha256: selection.selectionSha256, expectedCount: selection.count });
+    const exportClaim = await beginGmailSelectionExport({ ownerId: args.ownerId, selectionId: selection.selectionId, fingerprint: exportFingerprint });
+    if (exportClaim.replay) return { ...exportClaim.replay, replay: true };
+    if (!exportClaim.claimed) throw new GmailServiceError("export_in_progress", "This Gmail selection export is already running; retry shortly with the same receipt.", 409, true);
+    const messages = [];
+    for (const messageId of selection.messageIds) messages.push(await this.getCompleteMessage({ ownerId: args.ownerId, providerIdentity: args.providerIdentity, connectionId: args.connectionId, messageId }));
+    const exportId = `gexp_${selection.selectionSha256.slice(0, 32)}`;
+    const manifest = { version: GMAIL_MAIN_CONTRACT_VERSION, selectionId: selection.selectionId, selectionSha256: selection.selectionSha256, count: messages.length };
+    const content = [JSON.stringify({ type: "manifest", ...manifest }), ...messages.map((message) => JSON.stringify({ type: "message", message }))].join("\n") + "\n";
+    const artifact = await this.createJsonlArtifact({ ownerId: args.ownerId, exportId, filename: `gmail-${selection.selectionId}.jsonl`, content, stableCreatedAt: selection.createdAt, stableKey: exportFingerprint.slice(0, 32) });
+    const result = { exportId, selectionId: selection.selectionId, selectionSha256: selection.selectionSha256, count: messages.length, status: "complete", artifact, sampleMessages: messages.slice(0, 5).map(messagePreview) };
+    await finishGmailSelectionExport(args.ownerId, selection.selectionId, result);
+    return result;
+  }
+  async bulkManageSelection(args) {
+    const selection = await getOwnedGmailSelection(args);
+    if (selection.purpose !== "mailbox_action") throw new GmailServiceError("selection_purpose_mismatch", "This Gmail selection was not prepared for mailbox actions.", 409, false);
+    assertGmailSelectionReceipt(selection, args.expectedCount, args.selectionSha256);
+    const fingerprint = gmailFingerprint({ selectionSha256: selection.selectionSha256, operation: args.operation });
+    const begun = await beginGmailAction({ ownerId: args.ownerId, idempotencyKey: args.idempotencyKey, fingerprint });
+    if (begun.replay && begun.execution.result) return begun.execution.result;
+    if (begun.replay) return { actionId: begun.execution.actionId, selectionId: selection.selectionId, status: "running", changedCount: 0, failedCount: 0, failedChunks: [], retryable: true };
+    const failures = [];
+    let changed = 0;
+    const operation = manageLabels(args.operation);
+    if (operation.mode === "batch") {
+      if (operation.validateIds.length) await this.validateLabels(args.providerIdentity ?? args.ownerId, args.connectionId, operation.validateIds);
+      const chunks = chunk(selection.messageIds, 1e3);
+      for (let index = 0; index < chunks.length; index++) {
+        await touchGmailAction(begun.execution.actionId);
+        const chunkKey = `batch:${index}`;
+        const claim = await claimGmailActionChunk(begun.execution.actionId, chunkKey);
+        if (!claim.claimed) {
+          if (claim.receipt.status === "complete") changed += Number(claim.receipt.result?.changedCount ?? chunks[index].length);
+          else failures.push({ chunk: index, code: claim.receipt.status === "failed" ? String(claim.receipt.result?.code ?? "provider_error") : "outcome_unknown" });
+          continue;
+        }
+        try {
+          await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "POST", path: "/gmail/v1/users/me/messages/batchModify", body: { ids: chunks[index], addLabelIds: operation.addLabelIds, removeLabelIds: operation.removeLabelIds }, requestId: `${args.idempotencyKey}:${index}` });
+          changed += chunks[index].length;
+          await finishGmailActionChunk(begun.execution.actionId, chunkKey, "complete", { changedCount: chunks[index].length });
+        } catch (error) {
+          const code = serviceErrorCode(error);
+          failures.push({ chunk: index, code });
+          await finishGmailActionChunk(begun.execution.actionId, chunkKey, "failed", { code });
+        }
+      }
+    } else {
+      for (let index = 0; index < selection.messageIds.length; index++) {
+        await touchGmailAction(begun.execution.actionId);
+        const chunkKey = `single:${index}`;
+        const claim = await claimGmailActionChunk(begun.execution.actionId, chunkKey);
+        if (!claim.claimed) {
+          if (claim.receipt.status === "complete") changed += 1;
+          else if (failures.length < 20) failures.push({ chunk: index, code: claim.receipt.status === "failed" ? String(claim.receipt.result?.code ?? "provider_error") : "outcome_unknown" });
+          continue;
+        }
+        try {
+          await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "POST", path: `/gmail/v1/users/me/messages/${encodeURIComponent(selection.messageIds[index])}/${operation.path}`, body: {}, requestId: `${args.idempotencyKey}:${index}` });
+          changed += 1;
+          await finishGmailActionChunk(begun.execution.actionId, chunkKey, "complete", { changedCount: 1 });
+        } catch (error) {
+          const code = serviceErrorCode(error);
+          if (failures.length < 20) failures.push({ chunk: index, code });
+          await finishGmailActionChunk(begun.execution.actionId, chunkKey, "failed", { code });
+        }
+      }
+    }
+    const result = { actionId: begun.execution.actionId, selectionId: selection.selectionId, status: failures.length ? "partial" : "complete", changedCount: changed, failedCount: selection.count - changed, failedChunks: failures.slice(0, 20) };
+    await finishGmailAction(begun.execution.actionId, failures.length ? "partial" : "complete", result);
+    return result;
+  }
+  async permanentlyDeleteSelection(args) {
+    if (args.confirmPermanentDelete !== true) throw new GmailServiceError("permanent_delete_confirmation_required", "Set confirmPermanentDelete to true after explicit user confirmation.");
+    const selection = await getOwnedGmailSelection(args);
+    assertGmailSelectionReceipt(selection, args.expectedCount, args.selectionSha256);
+    if (selection.purpose !== "mailbox_action") throw new GmailServiceError("selection_purpose_mismatch", "This Gmail selection was not prepared for mailbox actions.", 409, false);
+    const fingerprint = gmailFingerprint({ selectionSha256: selection.selectionSha256, operation: "permanent_delete" });
+    const begun = await beginGmailAction({ ownerId: args.ownerId, idempotencyKey: args.idempotencyKey, fingerprint });
+    if (begun.replay && begun.execution.result) return begun.execution.result;
+    if (begun.replay) return { actionId: begun.execution.actionId, selectionId: selection.selectionId, status: "running", submittedCount: 0, failedCount: 0, failedChunks: [], retryable: true, providerGuarantee: "The original permanent-delete attempt is still being finalized; no provider chunk was replayed." };
+    const failures = [];
+    let submitted = 0;
+    const chunks = chunk(selection.messageIds, 1e3);
+    for (let index = 0; index < chunks.length; index++) {
+      await touchGmailAction(begun.execution.actionId);
+      const chunkKey = `delete:${index}`;
+      const claim = await claimGmailActionChunk(begun.execution.actionId, chunkKey);
+      if (!claim.claimed) {
+        if (claim.receipt.status === "complete") submitted += Number(claim.receipt.result?.submittedCount ?? chunks[index].length);
+        else failures.push({ chunk: index, code: claim.receipt.status === "failed" ? String(claim.receipt.result?.code ?? "provider_error") : "outcome_unknown" });
+        continue;
+      }
+      try {
+        await this.providerCall({ identity: args.providerIdentity ?? args.ownerId, connectionId: args.connectionId, method: "POST", path: "/gmail/v1/users/me/messages/batchDelete", body: { ids: chunks[index] }, requestId: `${args.idempotencyKey}:${index}` });
+        submitted += chunks[index].length;
+        await finishGmailActionChunk(begun.execution.actionId, chunkKey, "complete", { submittedCount: chunks[index].length });
+      } catch (error) {
+        const code = serviceErrorCode(error);
+        failures.push({ chunk: index, code });
+        await finishGmailActionChunk(begun.execution.actionId, chunkKey, "failed", { code });
+      }
+    }
+    const result = { actionId: begun.execution.actionId, selectionId: selection.selectionId, status: failures.length ? "partial" : "complete", submittedCount: submitted, failedCount: selection.count - submitted, failedChunks: failures.slice(0, 20), providerGuarantee: "Gmail accepts batch deletion but does not report whether every supplied message previously existed." };
+    await finishGmailAction(begun.execution.actionId, failures.length ? "partial" : "complete", result);
+    return result;
+  }
+  async validateLabels(ownerId, connectionId, requested) {
+    const payload = record(await this.providerCall({ identity: ownerId, connectionId, method: "GET", path: "/gmail/v1/users/me/labels" }));
+    const available = new Set((Array.isArray(payload?.labels) ? payload.labels : []).map((item) => stringValue(record(item)?.id)).filter((item) => !!item));
+    const unknown = requested.filter((id) => !available.has(id));
+    if (unknown.length) throw new GmailServiceError("gmail_label_not_found", "One or more Gmail label IDs were not found.", 404, false);
+  }
+};
+function manageLabels(operation) {
+  if (operation.kind === "trash") return { mode: "single", path: "trash" };
+  if (operation.kind === "restore") return { mode: "single", path: "untrash" };
+  if (operation.kind === "labels") {
+    const addLabelIds = [...new Set(operation.addLabelIds ?? [])];
+    const removeLabelIds = [...new Set(operation.removeLabelIds ?? [])];
+    if (!addLabelIds.length && !removeLabelIds.length) throw new GmailServiceError("invalid_request", "At least one label must be added or removed.");
+    if (addLabelIds.some((id) => removeLabelIds.includes(id))) throw new GmailServiceError("invalid_request", "The same label cannot be added and removed.");
+    return { mode: "batch", addLabelIds, removeLabelIds, validateIds: [...addLabelIds, ...removeLabelIds] };
+  }
+  const mappings = {
+    mark_read: { addLabelIds: [], removeLabelIds: ["UNREAD"] },
+    mark_unread: { addLabelIds: ["UNREAD"], removeLabelIds: [] },
+    archive: { addLabelIds: [], removeLabelIds: ["INBOX"] },
+    move_to_inbox: { addLabelIds: ["INBOX"], removeLabelIds: [] }
+  };
+  return { mode: "batch", ...mappings[operation.kind], validateIds: [] };
+}
+function chunk(values, size) {
+  const result = [];
+  for (let index = 0; index < values.length; index += size) result.push(values.slice(index, index + size));
+  return result;
+}
+function serviceErrorCode(error) {
+  return error && typeof error === "object" && typeof error.code === "string" ? String(error.code) : "provider_error";
+}
+function messagePreview(message) {
+  return { messageId: message.messageId, threadId: message.threadId, internalDate: message.internalDate, from: message.from, to: message.to, subject: message.subject, snippet: message.snippet, labels: message.labels, attachmentCount: message.attachments.length };
+}
+function findPartData(part, partId) {
+  if (!part) return null;
+  if (stringValue(part.partId) === partId) return stringValue(record(part.body)?.data);
+  for (const child of Array.isArray(part.parts) ? part.parts : []) {
+    const found = findPartData(record(child), partId);
+    if (found !== null) return found;
+  }
+  return null;
+}
+function sniffMime(bytes, declared) {
+  if (bytes.subarray(0, 5).toString("ascii") === "%PDF-") return "application/pdf";
+  if (bytes.subarray(0, 4).equals(Buffer.from([80, 75, 3, 4]))) return "application/zip";
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return "image/png";
+  if (bytes.subarray(0, 3).equals(Buffer.from([255, 216, 255]))) return "image/jpeg";
+  if (declared.startsWith("text/")) {
+    try {
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      return declared;
+    } catch {
+      return "application/octet-stream";
+    }
+  }
+  if (declared === "application/json") {
+    try {
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+      return declared;
+    } catch {
+      return "application/octet-stream";
+    }
+  }
+  return "application/octet-stream";
+}
+
+export {
+  recordNangoConnectionCost,
+  ConnectedUsageSettlementInputSchema,
+  ConnectedUsagePreflightInputSchema,
+  ConnectedUsageBillingError,
+  preflightConnectedUsage,
+  settleConnectedUsage,
+  listConnectedUsageHistory,
+  MainNangoTransportError,
+  discoverOwnedNangoConnections,
+  listNangoCatalogDirect,
+  createNangoSessionDirect,
+  createNangoReconnectSessionDirect,
+  deleteNangoConnectionDirect,
+  probeNangoConnectionDirect,
+  listNangoToolsDirect,
+  callNangoToolDirect,
+  describeNangoToolDirect,
+  GmailSelectionError,
+  gmailFingerprint,
+  getOwnedGmailSelection,
+  assertGmailSelectionReceipt,
+  GMAIL_MAIN_CONTRACT_VERSION,
+  GMAIL_MAIN_CONTRACT_HASH,
+  GMAIL_INLINE_BODY_BYTES,
+  GMAIL_ATTACHMENT_REF_TTL_MS,
+  GmailServiceError,
+  parseGmailAddresses,
+  normalizeGmailMessage,
+  GmailService
+};