Resolve Gemini grounding redirect citation URLs

Co-authored-by: Cursor <cursoragent@cursor.com>

src/cloudcode/message-handler.js

@@ -19,6 +19,7 @@ import {
     isThinkingModel
 } from '../constants.js';
 import { convertGoogleToAnthropic } from '../format/index.js';
+import { resolveGroundingRedirects } from '../format/grounding.js';
 import { isRateLimitError, isAuthError, isAccountForbiddenError, AccountForbiddenError } from '../errors.js';
 import { formatDuration, sleep, isNetworkError, throttledFetch } from '../utils/helpers.js';
 import { logger } from '../utils/logger.js';
@@ -335,7 +336,11 @@ export async function sendMessage(anthropicRequest, accountManager, fallbackEnab
                     // Clear rate limit state on success
                     clearRateLimitState(account.email, model);
                     accountManager.notifySuccess(account, model);
-                    return convertGoogleToAnthropic(data, anthropicRequest.model);
+                    const converted = convertGoogleToAnthropic(data, anthropicRequest.model);
+                    if (converted.grounding) {
+                        converted.grounding = await resolveGroundingRedirects(converted.grounding);
+                    }
+                    return converted;
 
                 } catch (endpointError) {
                     if (isRateLimitError(endpointError)) {

src/cloudcode/sse-parser.js

@@ -6,6 +6,7 @@
  */
 
 import { convertGoogleToAnthropic } from '../format/index.js';
+import { resolveGroundingRedirects } from '../format/grounding.js';
 import { logger } from '../utils/logger.js';
 
 /**
@@ -125,5 +126,9 @@ export async function parseThinkingSSEResponse(response, originalModel) {
         logger.debug('[CloudCode] Thinking signature length:', thinkingPart?.thoughtSignature?.length || 0);
     }
 
-    return convertGoogleToAnthropic(accumulatedResponse, originalModel);
+    const converted = convertGoogleToAnthropic(accumulatedResponse, originalModel);
+    if (converted.grounding) {
+        converted.grounding = await resolveGroundingRedirects(converted.grounding);
+    }
+    return converted;
 }

src/cloudcode/sse-streamer.js

@@ -9,7 +9,7 @@ import crypto from 'crypto';
 import { MIN_SIGNATURE_LENGTH, getModelFamily } from '../constants.js';
 import { EmptyResponseError } from '../errors.js';
 import { cacheSignature, cacheThinkingSignature } from '../format/signature-cache.js';
-import { extractGrounding } from '../format/grounding.js';
+import { extractGrounding, resolveGroundingRedirects } from '../format/grounding.js';
 import { logger } from '../utils/logger.js';
 
 /**
@@ -287,7 +287,7 @@ export async function* streamSSEResponse(response, originalModel) {
     }
 
     // Emit message_delta and message_stop
-    const grounding = extractGrounding(groundingMetadata);
+    const grounding = await resolveGroundingRedirects(extractGrounding(groundingMetadata));
     if (grounding) {
         logger.info(`[CloudCode] grounding captured (stream): ${grounding.sources.length} source(s), ${grounding.annotations.length} citation(s)`);
     }

src/format/grounding.js

@@ -13,6 +13,13 @@
  * OpenAI-compatible clients can consume citations with no special-casing.
  */
 
+const GROUNDING_REDIRECT_HOST = 'vertexaisearch.cloud.google.com';
+const GROUNDING_REDIRECT_TIMEOUT_MS = Number(process.env.GROUNDING_REDIRECT_TIMEOUT_MS || 1500);
+const GROUNDING_REDIRECT_CACHE_TTL_MS = Number(process.env.GROUNDING_REDIRECT_CACHE_TTL_MS || 24 * 60 * 60 * 1000);
+const GROUNDING_REDIRECT_CACHE_MAX = Number(process.env.GROUNDING_REDIRECT_CACHE_MAX || 1000);
+
+const redirectCache = new Map();
+
 function pickUri(chunk) {
     return chunk?.web?.uri || chunk?.retrievedContext?.uri || null;
 }
@@ -21,6 +28,119 @@ function pickTitle(chunk) {
     return chunk?.web?.title || chunk?.retrievedContext?.title || '';
 }
 
+function isVertexGroundingRedirect(rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        return parsed.hostname === GROUNDING_REDIRECT_HOST
+            && parsed.pathname.includes('/grounding-api-redirect/');
+    } catch {
+        return false;
+    }
+}
+
+function getCachedRedirect(rawUrl) {
+    const row = redirectCache.get(rawUrl);
+    if (!row) return null;
+    if (Date.now() > row.expiresAt) {
+        redirectCache.delete(rawUrl);
+        return null;
+    }
+    return row.url;
+}
+
+function setCachedRedirect(rawUrl, resolvedUrl) {
+    if (redirectCache.size >= GROUNDING_REDIRECT_CACHE_MAX) {
+        const firstKey = redirectCache.keys().next().value;
+        if (firstKey) redirectCache.delete(firstKey);
+    }
+    redirectCache.set(rawUrl, {
+        url: resolvedUrl,
+        expiresAt: Date.now() + GROUNDING_REDIRECT_CACHE_TTL_MS
+    });
+}
+
+async function readRedirectLocation(rawUrl, method) {
+    const response = await fetch(rawUrl, {
+        method,
+        redirect: 'manual',
+        signal: AbortSignal.timeout(GROUNDING_REDIRECT_TIMEOUT_MS)
+    });
+
+    const location = response.headers.get('location');
+    if (!location) return null;
+
+    try {
+        return new URL(location, rawUrl).toString();
+    } catch {
+        return location;
+    }
+}
+
+export async function resolveCitationUrl(rawUrl) {
+    if (!rawUrl || !isVertexGroundingRedirect(rawUrl)) return rawUrl;
+
+    const cached = getCachedRedirect(rawUrl);
+    if (cached) return cached;
+
+    let resolvedUrl = rawUrl;
+    try {
+        resolvedUrl = await readRedirectLocation(rawUrl, 'HEAD') || rawUrl;
+    } catch {
+        try {
+            resolvedUrl = await readRedirectLocation(rawUrl, 'GET') || rawUrl;
+        } catch {
+            resolvedUrl = rawUrl;
+        }
+    }
+
+    setCachedRedirect(rawUrl, resolvedUrl);
+    return resolvedUrl;
+}
+
+export async function resolveGroundingRedirects(grounding) {
+    if (!grounding) return grounding;
+
+    const urls = new Set();
+    for (const source of grounding.sources || []) {
+        if (source?.raw_url) urls.add(source.raw_url);
+        if (source?.url) urls.add(source.url);
+    }
+    for (const ann of grounding.annotations || []) {
+        const rawUrl = ann?.url_citation?.raw_url;
+        const url = ann?.url_citation?.url;
+        if (rawUrl) urls.add(rawUrl);
+        if (url) urls.add(url);
+    }
+
+    const pairs = await Promise.all(
+        [...urls].map(async (url) => [url, await resolveCitationUrl(url)])
+    );
+    const resolvedByRawUrl = new Map(pairs);
+
+    return {
+        ...grounding,
+        sources: (grounding.sources || []).map((source) => {
+            const rawUrl = source.raw_url || source.url;
+            return {
+                ...source,
+                raw_url: rawUrl,
+                url: resolvedByRawUrl.get(rawUrl) || resolvedByRawUrl.get(source.url) || source.url
+            };
+        }),
+        annotations: (grounding.annotations || []).map((ann) => {
+            const rawUrl = ann.url_citation.raw_url || ann.url_citation.url;
+            return {
+                ...ann,
+                url_citation: {
+                    ...ann.url_citation,
+                    raw_url: rawUrl,
+                    url: resolvedByRawUrl.get(rawUrl) || resolvedByRawUrl.get(ann.url_citation.url) || ann.url_citation.url
+                }
+            };
+        })
+    };
+}
+
 export function extractGrounding(groundingMetadata) {
     if (!groundingMetadata || typeof groundingMetadata !== 'object') return null;
 

tests/migration/grounding-redirects.test.js

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveGroundingRedirects } from '../../src/format/grounding.js';
+
+test('resolveGroundingRedirects converts Vertex grounding redirect URLs to final URLs', async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (url, options) => {
+        assert.equal(options.redirect, 'manual');
+        assert.ok(['HEAD', 'GET'].includes(options.method));
+        return new Response('', {
+            status: 302,
+            headers: {
+                location: 'https://www.kraken.com/prices/bitcoin'
+            }
+        });
+    };
+
+    try {
+        const rawUrl = 'https://vertexaisearch.cloud.google.com/grounding-api-redirect/abc';
+        const grounding = await resolveGroundingRedirects({
+            queries: ['bitcoin price'],
+            sources: [{ url: rawUrl, title: 'kraken.com' }],
+            annotations: [{
+                type: 'url_citation',
+                url_citation: {
+                    url: rawUrl,
+                    title: 'kraken.com',
+                    start_index: 0,
+                    end_index: 42
+                }
+            }]
+        });
+
+        assert.equal(grounding.sources[0].url, 'https://www.kraken.com/prices/bitcoin');
+        assert.equal(grounding.sources[0].raw_url, rawUrl);
+        assert.equal(grounding.annotations[0].url_citation.url, 'https://www.kraken.com/prices/bitcoin');
+        assert.equal(grounding.annotations[0].url_citation.raw_url, rawUrl);
+    } finally {
+        globalThis.fetch = originalFetch;
+    }
+});
+
+test('resolveGroundingRedirects leaves non-Vertex URLs unchanged', async () => {
+    const url = 'https://example.com/page';
+    const grounding = await resolveGroundingRedirects({
+        queries: [],
+        sources: [{ url, title: 'example.com' }],
+        annotations: [{
+            type: 'url_citation',
+            url_citation: {
+                url,
+                title: 'example.com',
+                start_index: 0,
+                end_index: 10
+            }
+        }]
+    });
+
+    assert.equal(grounding.sources[0].url, url);
+    assert.equal(grounding.annotations[0].url_citation.url, url);
+});