@herbertgao/pi-extensions 2026.10.0 → 2026.10.2

package/node_modules/pi-antigravity/src/search/search.ts

@@ -9,34 +9,50 @@ import { antigravityFetch } from "../utils/http.js";
 import { safeError } from "../utils/security.js";
 import { antigravityRequestEnvelope, isRecord } from "../utils/util.js";
 
-/** Default search engine model: fast, natively supports groundings and reasoning. */
-export const DEFAULT_SEARCH_MODEL = "gemini-3-flash";
+/** Default search model: fast grounding model for interactive tool calls. */
+export const DEFAULT_SEARCH_MODEL = "gemini-3.5-flash-lite";
 
-/** Fallback runtime candidates if the primary flash model is undergoing rollout or capacity limits. */
+/** Fallback runtime candidates if the primary model is missing or out of capacity. */
 export const SEARCH_MODEL_FALLBACKS = [
   DEFAULT_SEARCH_MODEL,
-  "gemini-3.6-flash-low",
-  "gemini-2.5-flash",
+  "gemini-3.1-flash-lite",
+  "gemini-3-flash",
 ] as const;
 
-export const SEARCH_SYSTEM_INSTRUCTION = `You are an expert deep-research investigator and technical analyst.
-Your objective is to use Google Search Grounding to unearth rich, high-signal, multi-perspective facts.
+export const SEARCH_SYSTEM_INSTRUCTION = `You are a careful research assistant using Google Search grounding.
+Return a compact evidence brief with exactly these sections:
+## Findings
+## Gaps
+## Next checks
 
-Guidelines:
-1. DO NOT settle for generic marketing summaries, public relations announcements, or shallow overviews.
-2. Formulate multiple distinct, targeted search queries covering technical architecture, specific parameters, benchmark comparisons, developer issues, pitfalls, and community feedback.
-3. Prioritize hard technical details: exact version numbers, hardware requirements, protocol constraints, benchmarks, error codes, and configuration snippets.
-4. Structure your response into clean, logical Markdown sections citing direct sources.`;
+Rules:
+- Verify each claim inside the specific item, function, or section it refers to. Do not copy an attribute from a neighboring entry on the same page.
+- Prefer primary documentation and exact names, versions, and constraints over marketing summaries.
+- If a fact is not supported by a retrieved source, put it under Gaps instead of stating it as a finding.
+- Keep the brief short enough for an interactive agent tool call.`;
 
 export type SearchSource = {
+  /** Original groundingChunks index, including gaps from skipped non-web chunks. */
+  index?: number;
   title: string;
   url: string;
 };
 
+export type SearchSupport = {
+  text: string;
+  startIndex?: number;
+  endIndex?: number;
+  partIndex?: number;
+  sourceIndices: number[];
+};
+
 export type SearchResult = {
   text: string;
   sources: SearchSource[];
   queries: string[];
+  /** Optional so existing callers can still construct results with the original shape. */
+  parts?: Array<{ index: number; text: string }>;
+  supports?: SearchSupport[];
 };
 
 export type ExecuteSearchOptions = {
@@ -127,8 +143,8 @@ export function buildSearchRequest(
     tools.push({ urlContext: {} });
   }
 
-  // Thinking budget: 4096 if explicitly requested, baseline 2048 to trigger multi-step search planning
-  const thinkingBudget = options.thinking ? 4096 : 2048;
+  // Default budget stays at 0 so interactive lookups stay fast. --thinking opts into planning.
+  const thinkingBudget = options.thinking ? 4096 : 0;
   const envelope = antigravityRequestEnvelope(model, false);
 
   return {
@@ -159,25 +175,28 @@ export function buildSearchRequest(
   };
 }
 
-/**
- * Parse candidate text and Grounding metadata from Antigravity API response.
- *
- * @param data - Raw JSON response from Antigravity generateContent API.
- * @returns Structured SearchResult with synthesized text, web queries, and cited source URLs.
- */
+/** Read candidates from either the wrapped Antigravity or direct Gemini response. */
 function candidateList(data: unknown): unknown {
   if (!isRecord(data)) return undefined;
   if (isRecord(data.response)) return data.response.candidates;
   return data.candidates;
 }
 
+/** Return the first array entry without assuming its response shape. */
 function firstUnknownItem(value: unknown): unknown {
   if (!Array.isArray(value)) return undefined;
   return (value as unknown[])[0];
 }
 
+/**
+ * Parse visible candidate text and grounding metadata from an Antigravity response.
+ * Preserve original part and source indices so UTF-8 citation offsets remain usable.
+ *
+ * @param data - Raw JSON response from Antigravity generateContent API.
+ * @returns Synthesized text, web queries, sources, and grounding supports.
+ */
 export function parseSearchResponse(data: unknown): SearchResult {
-  const result: SearchResult = { text: "", sources: [], queries: [] };
+  const result: SearchResult = { text: "", sources: [], queries: [], parts: [], supports: [] };
   if (!isRecord(data)) return result;
 
   const responseObj = isRecord(data.response) ? data.response : data;
@@ -203,11 +222,12 @@ export function parseSearchResponse(data: unknown): SearchResult {
   // Extract synthesized text (ignoring thinking parts)
   const content = isRecord(candidate.content) ? candidate.content : undefined;
   if (Array.isArray(content?.parts)) {
-    result.text = content.parts
-      .filter((p) => isRecord(p) && !p.thought && typeof p.text === "string")
-      .map((p) => (p as { text: string }).text)
-      .filter(Boolean)
-      .join("\n\n");
+    result.parts = content.parts.flatMap((part, index) =>
+      isRecord(part) && !part.thought && typeof part.text === "string" && part.text
+        ? [{ index, text: part.text }]
+        : [],
+    );
+    result.text = result.parts.map((part) => part.text).join("\n\n");
   }
 
   // Extract grounding citations & executed queries
@@ -217,22 +237,97 @@ export function parseSearchResponse(data: unknown): SearchResult {
       result.queries = grounding.webSearchQueries.filter((q): q is string => typeof q === "string");
     }
     if (Array.isArray(grounding.groundingChunks)) {
-      for (const chunk of grounding.groundingChunks) {
+      for (const [index, chunk] of grounding.groundingChunks.entries()) {
         if (!isRecord(chunk)) continue;
         const web = isRecord(chunk.web) ? chunk.web : undefined;
         if (typeof web?.uri === "string") {
           result.sources.push({
+            index,
             title: typeof web.title === "string" && web.title.trim() ? web.title.trim() : web.uri,
             url: web.uri,
           });
         }
       }
     }
+    if (Array.isArray(grounding.groundingSupports)) {
+      const sourceIndices = new Set(result.sources.map((source) => source.index));
+      const textPartIndices = new Set(result.parts?.map((part) => part.index));
+      for (const support of grounding.groundingSupports) {
+        if (!isRecord(support) || !isRecord(support.segment)) continue;
+        if (
+          typeof support.segment.text !== "string" ||
+          !Array.isArray(support.groundingChunkIndices)
+        )
+          continue;
+        const partIndex = support.segment.partIndex ?? 0;
+        if (typeof partIndex !== "number" || !textPartIndices.has(partIndex)) continue;
+        const indices = support.groundingChunkIndices.filter(
+          (index): index is number =>
+            typeof index === "number" && Number.isInteger(index) && sourceIndices.has(index),
+        );
+        if (indices.length === 0) continue;
+        result.supports?.push({
+          text: support.segment.text,
+          startIndex:
+            typeof support.segment.startIndex === "number" ? support.segment.startIndex : undefined,
+          endIndex:
+            typeof support.segment.endIndex === "number" ? support.segment.endIndex : undefined,
+          partIndex:
+            typeof support.segment.partIndex === "number" ? support.segment.partIndex : undefined,
+          sourceIndices: indices,
+        });
+      }
+    }
   }
 
   return result;
 }
 
+/**
+ * Google's offsets are UTF-8 bytes within a content Part, not JS character indices.
+ * Verify each segment before inserting citations; skip unsafe mappings.
+ */
+function citeSearchText(res: SearchResult): string {
+  if (!res.supports?.length) return res.text;
+  const textParts = res.parts ?? [{ index: 0, text: res.text }];
+  // Respect callers editing result.text; original offsets no longer apply.
+  if (textParts.map((part) => part.text).join("\n\n") !== res.text) {
+    return res.text;
+  }
+  const sourceIndices = new Set(res.sources.map((source, index) => source.index ?? index));
+  const parts = textParts.map((part) => {
+    const bytes = Buffer.from(part.text, "utf8");
+    const insertions = new Map<number, Set<number>>();
+    for (const support of res.supports ?? []) {
+      const start = support.startIndex ?? 0;
+      const end = support.endIndex;
+      if (
+        (support.partIndex ?? 0) !== part.index ||
+        !Number.isInteger(start) ||
+        start < 0 ||
+        end === undefined ||
+        !Number.isInteger(end) ||
+        end <= start ||
+        end > bytes.length ||
+        bytes.subarray(start, end).toString("utf8") !== support.text
+      )
+        continue;
+      const indices = insertions.get(end) ?? new Set<number>();
+      for (const index of support.sourceIndices) {
+        if (Number.isInteger(index) && index >= 0 && sourceIndices.has(index)) indices.add(index);
+      }
+      insertions.set(end, indices);
+    }
+    let cited = bytes;
+    for (const [end, indices] of [...insertions].sort(([a], [b]) => b - a)) {
+      const references = [...indices].map((index) => `[${index + 1}]`).join("");
+      cited = Buffer.concat([cited.subarray(0, end), Buffer.from(references), cited.subarray(end)]);
+    }
+    return cited.toString("utf8");
+  });
+  return parts.join("\n\n") || res.text;
+}
+
 /**
  * Formats structured SearchResult into clean Markdown for agent consumption.
  *
@@ -242,12 +337,16 @@ export function parseSearchResponse(data: unknown): SearchResult {
 export function formatSearchResult(res: SearchResult): string {
   const sections: string[] = [];
 
-  if (res.text) {
-    sections.push(res.text);
-  }
+  const cited = citeSearchText(res);
+  if (cited) sections.push(cited);
 
   if (res.sources.length > 0) {
-    const list = res.sources.map((s) => `- [${s.title}](${s.url})`).join("\n");
+    const list = res.sources
+      .map(
+        (s, index) =>
+          `- ${res.supports?.length ? `[${(s.index ?? index) + 1}] ` : ""}[${s.title}](${s.url})`,
+      )
+      .join("\n");
     sections.push(`### Sources\n${list}`);
   }
 

package/node_modules/pi-antigravity/src/stream/stream.ts

@@ -50,7 +50,7 @@ import {
   getThinkingConfig,
   PROVIDER_ID,
 } from "../models/models.js";
-import { redactSecrets, safeError } from "../utils/security.js";
+import { extractValidationUrl, redactSecrets, safeError } from "../utils/security.js";
 import {
   ANTIGRAVITY_API,
   type ActiveBlock,
@@ -957,7 +957,10 @@ export function buildRequest(
       (m) => m.role === "assistant" && m.stopReason !== "error" && m.stopReason !== "aborted",
     ).length ?? 0;
 
-  const { conversationId, trajectoryId } = resolveSessionTrajectory(context, options.sessionId);
+  const { conversationId, trajectoryId, sessionId } = resolveSessionTrajectory(
+    context,
+    options.sessionId,
+  );
 
   const envelope = antigravityRequestEnvelope(runtimeModel, {
     isClaude,
@@ -967,8 +970,9 @@ export function buildRequest(
     requestIndex,
     conversationId,
     trajectoryId,
+    sessionId,
   });
-  request.sessionId = options.sessionId || envelope.sessionId;
+  request.sessionId = envelope.sessionId;
   request.labels = envelope.labels;
 
   return {
@@ -1017,10 +1021,14 @@ export function friendlyAntigravityError(status: number | undefined, text: strin
     return "Antigravity authentication failed. Next: run /login antigravity, then retry.";
   }
   if (status === 403) {
-    if (/permission|forbidden|access/i.test(msg)) {
+    const verifyUrl = extractValidationUrl(text);
+    const verifyHint = verifyUrl
+      ? ` Open this link in a browser signed in to the same Google account to verify: ${verifyUrl}`
+      : "";
+    if (/permission|forbidden|access/i.test(msg) && !verifyUrl) {
       return "Antigravity access was denied for this account or project. Next: try another model, re-login, or use an account with access.";
     }
-    return `Antigravity denied this request. Next: re-login or try another model. Backend said: ${msg}`;
+    return `Antigravity denied this request. Next: re-login or try another model. Backend said: ${msg}${verifyHint}`;
   }
   if (status === 404) {
     if (/Requested entity was not found/i.test(msg)) {
@@ -1257,9 +1265,149 @@ export async function streamResponse(
   let started = false;
   let currentBlock: ActiveBlock | null = null;
   let hasContent = false;
+  let sawFinishReason = false;
+  let stray = "";
   const blocks = output.content;
   const blockIndex = () => blocks.length - 1;
 
+  const consumeStray = (line: string) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith(":")) return;
+    stray = stray ? `${stray}\n${trimmed}` : trimmed;
+    const start = stray.indexOf("{");
+    if (start < 0) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(stray.slice(start));
+    } catch {
+      return;
+    }
+    if (!parsed || typeof parsed !== "object" || !("error" in parsed)) return;
+    const record = parsed as { error?: { code?: unknown; message?: unknown } };
+    const status = typeof record.error?.code === "number" ? record.error.code : undefined;
+    if (status !== undefined) setLastStatus(status);
+    const friendly = friendlyAntigravityError(status, stray.slice(start));
+    throw new Error(status ? `${friendly} (${status})` : friendly);
+  };
+
+  const handleLine = (line: string) => {
+    if (!line.startsWith("data:")) {
+      consumeStray(line);
+      return;
+    }
+    const json = line.slice(5).trim();
+    if (!json || json === "[DONE]") return;
+
+    let chunk: StreamChunk;
+    try {
+      chunk = JSON.parse(json) as StreamChunk;
+    } catch {
+      return;
+    }
+
+    if (chunk.error) {
+      const status = typeof chunk.error.code === "number" ? chunk.error.code : undefined;
+      if (status !== undefined) setLastStatus(status);
+      const friendly = friendlyAntigravityError(status, JSON.stringify({ error: chunk.error }));
+      throw new Error(status ? `${friendly} (${status})` : chunk.error.message || friendly);
+    }
+
+    const responseData = chunk.response || chunk;
+    const candidate = responseData.candidates?.[0];
+
+    for (const part of candidate?.content?.parts || []) {
+      if (part.text !== undefined) {
+        hasContent = true;
+        const isThinking = part.thought === true;
+        const type = isThinking ? "thinking" : "text";
+        if (!currentBlock || currentBlock.type !== type) {
+          finishCurrent();
+          currentBlock = isThinking
+            ? { type: "thinking", thinking: "", thinkingSignature: undefined }
+            : { type: "text", text: "" };
+          blocks.push(currentBlock);
+          ensureStarted();
+          stream.push({
+            type: isThinking ? "thinking_start" : "text_start",
+            contentIndex: blockIndex(),
+            partial: output,
+          });
+        }
+        if (isThinking && currentBlock.type === "thinking") {
+          currentBlock.thinking += part.text;
+          if (part.thoughtSignature) currentBlock.thinkingSignature = part.thoughtSignature;
+          stream.push({
+            type: "thinking_delta",
+            contentIndex: blockIndex(),
+            delta: part.text,
+            partial: output,
+          });
+        } else if (!isThinking && currentBlock.type === "text") {
+          currentBlock.text += part.text;
+          if (part.thoughtSignature) currentBlock.textSignature = part.thoughtSignature;
+          stream.push({
+            type: "text_delta",
+            contentIndex: blockIndex(),
+            delta: part.text,
+            partial: output,
+          });
+        }
+      }
+
+      if (part.functionCall) {
+        hasContent = true;
+        finishCurrent();
+        const rawId = part.functionCall.id || "";
+        const toolCall: ToolCall = {
+          type: "toolCall",
+          id: sanitizeToolCallId(rawId, part.functionCall.name),
+          name: part.functionCall.name || "",
+          arguments: asToolCallArguments(part.functionCall.args),
+          ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
+        };
+        blocks.push(toolCall);
+        ensureStarted();
+        stream.push({ type: "toolcall_start", contentIndex: blockIndex(), partial: output });
+        stream.push({
+          type: "toolcall_delta",
+          contentIndex: blockIndex(),
+          delta: JSON.stringify(toolCall.arguments),
+          partial: output,
+        });
+        stream.push({
+          type: "toolcall_end",
+          contentIndex: blockIndex(),
+          toolCall,
+          partial: output,
+        });
+      }
+    }
+
+    if (candidate?.finishReason) {
+      sawFinishReason = true;
+      output.rawStopReason = candidate.finishReason;
+      output.stopReason = blocks.some((b) => b.type === "toolCall")
+        ? StopReason.ToolUse
+        : mapStopReason(candidate.finishReason);
+    }
+
+    if (responseData.usageMetadata) {
+      const prompt = responseData.usageMetadata.promptTokenCount || 0;
+      const cacheRead = responseData.usageMetadata.cachedContentTokenCount || 0;
+      const thoughts = responseData.usageMetadata.thoughtsTokenCount || 0;
+      output.usage.input = prompt - cacheRead;
+      output.usage.output = (responseData.usageMetadata.candidatesTokenCount || 0) + thoughts;
+      output.usage.reasoning = thoughts;
+      output.usage.cacheRead = cacheRead;
+      output.usage.totalTokens = responseData.usageMetadata.totalTokenCount || 0;
+      if (model?.cost) {
+        calculateCost(model, output.usage);
+      } else {
+        output.usage.cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+      }
+    }
+  };
+
   const ensureStarted = () => {
     if (!started) {
       stream.push({ type: "start", partial: output });
@@ -1297,114 +1445,7 @@ export async function streamResponse(
     while ((newlineIdx = buffer.indexOf("\n", scanStart)) !== -1) {
       const line = buffer.slice(scanStart, newlineIdx);
       scanStart = newlineIdx + 1;
-      if (!line.startsWith("data:")) continue;
-      const json = line.slice(5).trim();
-      if (!json || json === "[DONE]") continue;
-
-      let chunk: StreamChunk;
-      try {
-        chunk = JSON.parse(json) as StreamChunk;
-      } catch {
-        continue;
-      }
-
-      if (chunk.error) {
-        throw new Error(chunk.error.message || JSON.stringify(chunk.error));
-      }
-
-      const responseData = chunk.response || chunk;
-      const candidate = responseData.candidates?.[0];
-
-      for (const part of candidate?.content?.parts || []) {
-        if (part.text !== undefined) {
-          hasContent = true;
-          const isThinking = part.thought === true;
-          const type = isThinking ? "thinking" : "text";
-          if (!currentBlock || currentBlock.type !== type) {
-            finishCurrent();
-            currentBlock = isThinking
-              ? { type: "thinking", thinking: "", thinkingSignature: undefined }
-              : { type: "text", text: "" };
-            blocks.push(currentBlock);
-            ensureStarted();
-            stream.push({
-              type: isThinking ? "thinking_start" : "text_start",
-              contentIndex: blockIndex(),
-              partial: output,
-            });
-          }
-          if (isThinking && currentBlock.type === "thinking") {
-            currentBlock.thinking += part.text;
-            if (part.thoughtSignature) currentBlock.thinkingSignature = part.thoughtSignature;
-            stream.push({
-              type: "thinking_delta",
-              contentIndex: blockIndex(),
-              delta: part.text,
-              partial: output,
-            });
-          } else if (!isThinking && currentBlock.type === "text") {
-            currentBlock.text += part.text;
-            if (part.thoughtSignature) currentBlock.textSignature = part.thoughtSignature;
-            stream.push({
-              type: "text_delta",
-              contentIndex: blockIndex(),
-              delta: part.text,
-              partial: output,
-            });
-          }
-        }
-
-        if (part.functionCall) {
-          hasContent = true;
-          finishCurrent();
-          const rawId = part.functionCall.id || "";
-          const toolCall: ToolCall = {
-            type: "toolCall",
-            id: sanitizeToolCallId(rawId, part.functionCall.name),
-            name: part.functionCall.name || "",
-            arguments: asToolCallArguments(part.functionCall.args),
-            ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
-          };
-          blocks.push(toolCall);
-          ensureStarted();
-          stream.push({ type: "toolcall_start", contentIndex: blockIndex(), partial: output });
-          stream.push({
-            type: "toolcall_delta",
-            contentIndex: blockIndex(),
-            delta: JSON.stringify(toolCall.arguments),
-            partial: output,
-          });
-          stream.push({
-            type: "toolcall_end",
-            contentIndex: blockIndex(),
-            toolCall,
-            partial: output,
-          });
-        }
-      }
-
-      if (candidate?.finishReason) {
-        output.rawStopReason = candidate.finishReason;
-        output.stopReason = blocks.some((b) => b.type === "toolCall")
-          ? StopReason.ToolUse
-          : mapStopReason(candidate.finishReason);
-      }
-
-      if (responseData.usageMetadata) {
-        const prompt = responseData.usageMetadata.promptTokenCount || 0;
-        const cacheRead = responseData.usageMetadata.cachedContentTokenCount || 0;
-        const thoughts = responseData.usageMetadata.thoughtsTokenCount || 0;
-        output.usage.input = prompt - cacheRead;
-        output.usage.output = (responseData.usageMetadata.candidatesTokenCount || 0) + thoughts;
-        output.usage.reasoning = thoughts;
-        output.usage.cacheRead = cacheRead;
-        output.usage.totalTokens = responseData.usageMetadata.totalTokenCount || 0;
-        if (model?.cost) {
-          calculateCost(model, output.usage);
-        } else {
-          output.usage.cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
-        }
-      }
+      handleLine(line.replace(/\r$/, ""));
     }
 
     if (scanStart > 0) {
@@ -1413,6 +1454,14 @@ export async function streamResponse(
     }
   }
 
+  buffer += decoder.decode();
+  if (buffer.length > 0) handleLine(buffer.replace(/\r$/, ""));
+  if (!sawFinishReason) {
+    throw new Error(
+      "Antigravity stream ended without a finish reason; the response was terminated before completion.",
+    );
+  }
+
   finishCurrent();
   return hasContent;
 }

package/node_modules/pi-antigravity/src/types/enums.ts

@@ -33,6 +33,7 @@ export type GeminiRole = (typeof GeminiRole)[keyof typeof GeminiRole];
 
 export const AntigravityRequestType = {
   Agent: "agent",
+  ImageGen: "image_gen",
 } as const;
 export type AntigravityRequestType =
   (typeof AntigravityRequestType)[keyof typeof AntigravityRequestType];

package/node_modules/pi-antigravity/src/types/types.ts

@@ -158,7 +158,7 @@ export type StreamResponseData = {
 };
 
 export type StreamChunk = StreamResponseData & {
-  error?: { message?: string };
+  error?: { message?: string; code?: number };
   response?: StreamResponseData;
 };
 

package/node_modules/pi-antigravity/src/utils/security.ts

@@ -1,4 +1,4 @@
-import { antigravityEnv } from "./util.js";
+import { antigravityEnv, isRecord } from "./util.js";
 
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const ALLOWED_API_HOST_SUFFIXES = [".googleapis.com", ".sandbox.googleapis.com"];
@@ -56,6 +56,52 @@ export function redactSecrets(text: string): string {
     );
 }
 
+const VALIDATION_URL_HOST = "accounts.google.com";
+
+/** Accept only the Google account-verification host, never an arbitrary redirect. */
+export function safeValidationUrl(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048 || /\s/.test(value))
+    return undefined;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "https:" || url.username || url.password) return undefined;
+  if (url.hostname !== VALIDATION_URL_HOST) return undefined;
+  return url.toString();
+}
+
+/** Pull `validation_url` from a 403 body before message slicing can drop it. */
+export function extractValidationUrl(text: string): string | undefined {
+  try {
+    const parsed = JSON.parse(text) as { error?: { details?: unknown } };
+    const details = parsed.error?.details;
+    if (Array.isArray(details)) {
+      for (const detail of details) {
+        if (!isRecord(detail) || !isRecord(detail.metadata)) continue;
+        const safe = safeValidationUrl(detail.metadata.validation_url);
+        if (safe) return safe;
+      }
+    }
+  } catch {
+    // not JSON
+  }
+  const match = text.match(/https:\/\/accounts\.google\.com\/[^\s"'<>\\]+/);
+  return match ? safeValidationUrl(match[0].replace(/[),.;]+$/, "")) : undefined;
+}
+
+/** Keep session-bearing verification links out of doctor output and stored diagnostics. */
+export function stripValidationUrls(text: string): string {
+  return text
+    .replace(/https:\/\/accounts\.google\.com\/[^\s"'<>\\]+/g, "[redacted-validation-url]")
+    .replace(
+      / Open this link in a browser signed in to the same Google account to verify: \[redacted-validation-url\]/g,
+      "",
+    );
+}
+
 export function maskEmail(email: string | undefined): string | undefined {
   if (!email || typeof email !== "string") return undefined;
   const parts = email.split("@");