@wenathlan/devthink 2.0.15 → 2.0.20

package/search.ts

@@ -1,1760 +0,0 @@
-/**
- * @file search.ts
- * @module provider/search
- * @description
- *  Third-person observer: the library watches how Antigravity Manager and
- *  Gemini CLI perform grounding via googleSearch + urlContext and reproduces
- *  the contract without relying on localhost v1 proxy. The observer calls
- *  cloudcode-pa.googleapis.com directly, cascades endpoints on 403/404/5xx,
- *  injects native Gemini tools, and parses groundingMetadata rigorously.
- *
- *  Layout: library-first, root-first — file lives beside its siblings
- *  Runtime: only node:* builtins + global fetch (Node >=18). Zero external deps.
- *  Date governance: 25/08/2026 — Canto do Buriti, PI, BR — version awareness 2.0.0
- *
- *  Contract:
- *  - Endpoint: https://cloudcode-pa.googleapis.com/v1internal:generateContent (primary)
- *    cascade: daily-cloudcode-pa.googleapis.com, sandbox fallback
- *  - No localhost v1 base-url proxy, direct cloudcode-pa (security + user choice)
- *  - Native tools: googleSearch + urlContext — both injected when enabled
- *  - Model: SEARCH_MODEL gemini-3-flash with preview fallback chain
- *  - Thinking: thinkingLevel → thinkingBudget mapping (8192/16384/32768) clamped 32k
- *  - Grounding parse: groundingMetadata.webSearchQueries, groundingChunks[].web.uri/title,
- *    groundingSupports, searchEntryPoint.renderedContent
- *  - Proxy support: env HTTPS_PROXY/HTTP_PROXY/NO_PROXY + options.proxyUrl
- *    manual CONNECT tunneling via node:net + node:tls — no external deps
- *  - Bypass metadata: mimics antigravity/{ver} {os}/{arch} UA, strips x-goog-user-project,
- *    jitter 0-80ms, FNV-1a deterministic session_id note (not needed here but coherent)
- *
- *  EN: Antigravity bypass relies on mimicking antigravity/{ver} {os}/{arch} UA
- *      and bypassing x-goog-user-project stripping, endpoint cascade 403/404/5xx.
- *  PT-BR: Bypass Antigravity depende de imitar UA antigravity/{ver} {os}/{arch}
- *      e remover x-goog-user-project, cascata de endpoints em 403/404/5xx.
- *
- *  Production-ready: JSDoc, exhaustive error handling, timeout, abort, proxy,
- *  endpoint cascade, thinking budget, grounding parsing, no placeholder.
- *
- * @author devthink
- * @license MIT
- * @version 2.0.0
- */
-
-import * as os from "node:os";
-import { platform as osPlatform, arch as osArch, release as osRelease } from "node:os";
-import * as net from "node:net";
-import * as tls from "node:tls";
-import * as http from "node:http";
-import * as https from "node:https";
-import { createHash } from "node:crypto";
-import { join as pathJoin } from "node:path";
-import { mkdirSync, writeFileSync } from "node:fs";
-
-// ---------------------------------------------------------------------------
-// Frozen-owner imports — identical values owned by constants.ts / core.ts /
-// models.ts, re-exported below so the module surface stays unchanged.
-// ---------------------------------------------------------------------------
-
-import {
-  ANTIGRAVITY_USER_AGENT_FALLBACK,
-  ANTIGRAVITY_VERSION_FALLBACK,
-  DEFAULT_TIMEOUT_MS,
-  GENERATE_CONTENT_ENDPOINT,
-  JITTER_MAX_MS,
-  JITTER_MIN_MS,
-  PLUGIN_VERSION,
-  STREAM_GENERATE_ENDPOINT,
-  FETCH_TIMEOUT_MS,
-} from "./constants.js";
-import { fnv1a32, getJitter, isRetryableStatus } from "./core.js";
-import {
-  buildAntagravityHeaders,
-  getDynamicUserAgent,
-  getXGoogApiClient,
-  normalizeArch,
-  normalizePlatform,
-} from "./fingerprint.js";
-// v2.1.15 Phase A: model-identification families (search/default model ids,
-// thinking tables, image-gen helpers) are imported from models.ts — THE
-// single owner — instead of the former constants.js re-exports.
-import {
-  CODE_ASSIST_ENDPOINTS,
-  SEARCH_MODEL,
-  SEARCH_MODEL_FALLBACKS,
-  SEARCH_MODEL_PREVIEW,
-  THINKING_BUDGET_MAP,
-  THINKING_BUDGET_MAX_CLAUDE,
-  THINKING_BUDGET_MAX_GEMINI,
-  THINKING_LEVELS,
-  buildImageGenConfig,
-  isImageGenModel,
-} from "./models.js";
-import type { ThinkingLevel } from "./models.js";
-// v2.1.15 Phase A: parseGrounding moved from core.ts — web-citation
-// extraction is search-grounding domain logic.
-function parseGrounding(meta: any): { uri: string; title?: string }[] {
-  const chunks = meta?.groundingChunks || meta?.grounding_chunks || [];
-  return chunks.map((c: any) => (c.web ? { uri: c.web.uri, title: c.web.title } : null)).filter(Boolean);
-}
-
-export {
-  ANTIGRAVITY_USER_AGENT_FALLBACK,
-  ANTIGRAVITY_VERSION_FALLBACK,
-  CODE_ASSIST_ENDPOINTS,
-  DEFAULT_TIMEOUT_MS,
-  GENERATE_CONTENT_ENDPOINT,
-  JITTER_MAX_MS,
-  JITTER_MIN_MS,
-  SEARCH_MODEL,
-  SEARCH_MODEL_FALLBACKS,
-  SEARCH_MODEL_PREVIEW,
-  STREAM_GENERATE_ENDPOINT,
-  THINKING_BUDGET_MAP,
-  THINKING_BUDGET_MAX_CLAUDE,
-  THINKING_BUDGET_MAX_GEMINI,
-  THINKING_LEVELS,
-  buildImageGenConfig,
-  getDynamicUserAgent,
-  getJitter,
-  isImageGenModel,
-};
-export type { ThinkingLevel };
-export { parseGrounding };
-
-// ---------------------------------------------------------------------------
-// Constants — observer notes prod is authoritative
-// ---------------------------------------------------------------------------
-
-/** Endpoint cascade — observer watches traffic: PROD first, then DAILY, SANDBOX */
-export const DEFAULT_ENDPOINT_ORDER: readonly string[] = [
-  CODE_ASSIST_ENDPOINTS.PROD,
-  CODE_ASSIST_ENDPOINTS.DAILY,
-  CODE_ASSIST_ENDPOINTS.SANDBOX,
-] as const;
-
-/** Timeouts — observer notes 10s per control call, 60s for content */
-export const SEARCH_TIMEOUT_MS = 60_000 as const;
-// local variant: diverges from models (models.FETCH_TIMEOUT_MS is the 10s control-plane timeout; this file pins it to the 60s content timeout)
-
-// ---------------------------------------------------------------------------
-// Types — grounding contract from Gemini API
-// ---------------------------------------------------------------------------
-
-/**
- * Web chunk returned by groundingMetadata.
- * Observer documents: each chunk points to a source URL used for grounding.
- */
-export interface WebGroundingChunk {
-  /** source uri, e.g. https://developer.mozilla.org/... */
-  uri: string;
-  /** title returned by search */
-  title: string;
-  /** derived domain — convenience */
-  domain?: string | undefined;
-}
-
-/** Raw web object inside groundingChunks */
-export interface GroundingChunkWeb {
-  uri?: string;
-  title?: string;
-  domain?: string;
-}
-
-export interface GroundingChunk {
-  web?: GroundingChunkWeb;
-  /** alternative shapes: retrievedContext etc. — kept for resilience */
-  retrievedContext?: { uri?: string; title?: string; text?: string };
-  [k: string]: unknown;
-}
-
-export interface GroundingSupportSegment {
-  startIndex?: number;
-  endIndex?: number;
-  text?: string;
-}
-
-export interface GroundingSupport {
-  segment?: GroundingSupportSegment;
-  groundingChunkIndices?: number[];
-  confidenceScores?: number[];
-}
-
-export interface SearchEntryPoint {
-  renderedContent?: string;
-  [k: string]: unknown;
-}
-
-export interface GroundingMetadata {
-  webSearchQueries?: string[];
-  groundingChunks?: GroundingChunk[];
-  groundingSupports?: GroundingSupport[];
-  searchEntryPoint?: SearchEntryPoint;
-  retrievalQueries?: string[];
-  [k: string]: unknown;
-}
-
-/** Request shape */
-export interface ExecuteSearchInput {
-  /** user query to ground with googleSearch/urlContext */
-  query: string;
-  /** optional system instruction — helps guide grounded answer */
-  systemPrompt?: string | undefined;
-  /** optional additional context appended to user query for better grounding */
-  additionalContext?: string | undefined;
-}
-
-export interface ExecuteSearchAuth {
-  /** OAuth access_token Bearer — required */
-  accessToken: string;
-  /** project id resolved via loadCodeAssist/onboardUser — optional but improves success */
-  projectId?: string;
-  /** optional custom user agent — fallback uses dynamic UA */
-  userAgent?: string;
-  /** optional antigravity version for UA — defaults to 1.19.2 */
-  version?: string;
-  /** optional client metadata override */
-  clientMetadata?: string;
-}
-
-export interface ExecuteSearchOptions {
-  /** model — defaults to SEARCH_MODEL gemini-3-flash */
-  model?: string;
-  /** thinking level mapping to budget */
-  thinkingLevel?: ThinkingLevel;
-  /** direct budget override — clamped 0-32768 */
-  thinkingBudget?: number;
-  /** include groundingMetadata in result — default true */
-  includeGrounding?: boolean;
-  /** inject url_context companion tool — default true per spec */
-  useUrlContext?: boolean;
-  /** inject google_search tool — default true */
-  useGoogleSearch?: boolean;
-  /** proxy url e.g. http://127.0.0.1:8080 — null disables env proxy */
-  proxyUrl?: string | null;
-  /** timeout per fetch — default 60s */
-  timeoutMs?: number;
-  /** custom endpoint list for cascade — default PROD/DAILY/SANDBOX */
-  endpoints?: string[];
-  /** include rendered search entry point? */
-  includeSearchEntryPoint?: boolean;
-  /** temperature for grounded answer — default 0.2 */
-  temperature?: number;
-  /** max output tokens — default 8192 */
-  maxOutputTokens?: number;
-  /** debug logging */
-  debug?: boolean;
-  /** jitter between endpoint retries — default true */
-  jitter?: boolean;
-  /** max retries across endpoints — internal */
-  maxRetries?: number;
-}
-
-/** Final grounded result */
-export interface SearchResult {
-  /** synthesized answer text */
-  text: string;
-  /** original query */
-  query: string;
-  /** model used */
-  model: string;
-  /** true if grounding sources returned */
-  grounded: boolean;
-  /** queries Gemini issued to Google Search */
-  webSearchQueries: string[];
-  /** parsed web sources — uri/title */
-  groundingChunks: WebGroundingChunk[];
-  /** raw supports — segment attribution */
-  groundingSupports?: GroundingSupport[] | undefined;
-  /** rendered search entry point HTML if present */
-  searchEntryPoint?: SearchEntryPoint | undefined;
-  /** raw groundingMetadata as returned */
-  groundingMetadata?: GroundingMetadata | undefined;
-  /** raw candidate response for debugging */
-  raw?: unknown | undefined;
-  /** endpoint that succeeded */
-  endpointUsed?: string | undefined;
-  /** thinking budget used */
-  thinkingBudgetUsed?: number | undefined;
-  /** was fallback project used? */
-  isFallbackProject?: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Error — production-ready with status context
-// ---------------------------------------------------------------------------
-
-export class SearchError extends Error {
-  public readonly status?: number | undefined;
-  public readonly endpoint?: string | undefined;
-  public readonly retryable: boolean;
-  public readonly code?: string | undefined;
-
-  constructor(
-    message: string,
-    opts: { status?: number; endpoint?: string; retryable?: boolean; code?: string; cause?: unknown } = {},
-  ) {
-    super(message);
-    this.name = "SearchError";
-    this.status = opts.status;
-    this.endpoint = opts.endpoint;
-    this.retryable = opts.retryable ?? false;
-    this.code = opts.code;
-    if (opts.cause) (this as any).cause = opts.cause;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Observer helpers — third-person, coherent with fingerprint.ts / project.ts
-// ---------------------------------------------------------------------------
-
-// v2.1.16: the local normalizePlatform/normalizeArch copies were deleted —
-// byte-identical (every branch) to the fingerprint.ts exports, which are now
-// imported above (search is L4, fingerprint is L2 — downward import, allowed).
-
-// getDynamicUserAgent is imported from constants.js (identical signature and
-// outputs; the owner's trim placement differs but the fallback constant carries
-// no whitespace, so results match for every input) and re-exported above.
-
-// v2.1.16: the stale hardcoded pluginVersion literal (2.1.14) was replaced
-// by the constants.js PLUGIN_VERSION import — the version-envelope owner — so
-// the Client-Metadata header stops drifting behind the release version. The
-// ANTIGRAVITY ideType/ideVersion/osVersion/arch fields stay local (the
-// fingerprint.ts owner builder derives them differently).
-function buildClientMetadata(version?: string): string {
-  const ver = version ?? ANTIGRAVITY_VERSION_FALLBACK;
-  const plat = normalizePlatform(osPlatform()).toUpperCase();
-  const archUpper = normalizeArch(osArch()).toUpperCase();
-  const parts = [
-    `ideType=ANTIGRAVITY`,
-    `platform=${plat}`,
-    `ideVersion=${ver}`,
-    `pluginVersion=${PLUGIN_VERSION}`,
-    `osVersion=${osRelease()}`,
-    `arch=${archUpper}`,
-  ];
-  return parts.join(",");
-}
-
-// getXGoogApiClient is imported from constants.js (byte-identical body:
-// `antigravity/{ver} gl-node/{node} gax/4.9.0 grpc/1.14.0`).
-
-// local variant: diverges from models (models.buildAntagravityHeaders takes an optional UA, omits X-Goog-Api-Client/Client-Metadata and strips FORBIDDEN_HEADERS; this variant requires the UA, emits both bypass headers and strips only x-goog-user-project)
-
-/**
- * Builds Antigravity header map for cloudcode-pa.
- * Observer notes: AM only sends User-Agent on content requests, not X-Goog-Api-Client
- * for onboardUser/loadCodeAssist, but for generateContent it sends both.
- * Also strips x-goog-user-project to avoid 403 IAM (requirement).
- *
- * @param accessToken - bearer
- * @param userAgent - UA string
- * @param extra - extra headers
- */
-
-/**
- * FNV-1a 32-bit — deterministic hashing for logs, not secrets.
- */
-// local variant: diverges from core (uses plain multiplication `(hash * 0x01000193) >>> 0` instead of Math.imul; floats lose low bits so results differ from core/models for most inputs)
-
-function hashToken(token: string): string {
-  try {
-    return createHash("sha256").update(token).digest("hex").slice(0, 16);
-  } catch {
-    return fnv1a32(token).toString(16);
-  }
-}
-
-/**
- * Jitter 0-80ms anti-rate-limit — observed in AM.
- * Identical to constants.getJitter — imported from the frozen owner and
- * re-exported above.
- */
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
-/**
- * Checks if HTTP status is retryable for endpoint cascade.
- * Observer: 403 project IAM mismatch, 404 rollout, 5xx instability → try next endpoint.
- */
-// local variant: diverges from models (models.isRetryableStatus also treats 408 as retryable; this cascade variant does not)
-
-// ---------------------------------------------------------------------------
-// Proxy support — only node:* builtins + fetch
-// ---------------------------------------------------------------------------
-
-export interface ProxyResolution {
-  /** final proxy url to use, null if disabled */
-  proxyUrl: string | null;
-  /** reason / source for debugging */
-  source: "option" | "env_https_proxy" | "env_http_proxy" | "env_all_proxy" | "disabled" | "none" | "no_proxy_bypass";
-}
-
-/**
- * Parses NO_PROXY env — comma separated list of host suffixes, IPs, CIDRs (simplified).
- */
-export function isNoProxyMatch(targetHost: string, noProxyRaw: string | undefined): boolean {
-  if (!noProxyRaw) return false;
-  const list = noProxyRaw
-    .split(",")
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean);
-  if (list.length === 0) return false;
-  const host = targetHost.toLowerCase();
-  for (const pattern of list) {
-    if (pattern === "*" || pattern === "*.*") return true;
-    if (pattern === host) return true;
-    if (pattern.startsWith(".")) {
-      // .example.com matches foo.example.com
-      if (host.endsWith(pattern)) return true;
-    }
-    if (host.endsWith(`.${pattern}`)) return true;
-    if (pattern.startsWith("*.")) {
-      const suffix = pattern.slice(2);
-      if (host === suffix || host.endsWith(`.${suffix}`)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Resolves proxy URL respecting options.proxyUrl, env vars, and NO_PROXY.
- * Observer scans env case-insensitively as per curl conventions.
- *
- * @param optionsProxy - explicit option, string or null (null disables)
- * @param targetUrl - target to check NO_PROXY against
- */
-export function resolveProxyUrl(optionsProxy: string | null | undefined, targetUrl?: string): ProxyResolution {
-  // explicit null disables proxy even if env present
-  if (optionsProxy === null) {
-    return { proxyUrl: null, source: "disabled" };
-  }
-  if (typeof optionsProxy === "string" && optionsProxy.trim().length > 0) {
-    return { proxyUrl: optionsProxy.trim(), source: "option" };
-  }
-
-  // env var resolution — order HTTPS_PROXY > HTTP_PROXY > ALL_PROXY
-  const envHttps = process.env.HTTPS_PROXY || process.env.https_proxy;
-  const envHttp = process.env.HTTP_PROXY || process.env.http_proxy;
-  const envAll = process.env.ALL_PROXY || process.env.all_proxy;
-  const noProxyRaw = process.env.NO_PROXY || process.env.no_proxy;
-
-  if (targetUrl) {
-    try {
-      const u = new URL(targetUrl);
-      if (isNoProxyMatch(u.hostname, noProxyRaw)) {
-        return { proxyUrl: null, source: "no_proxy_bypass" };
-      }
-    } catch {
-      // ignore malformed target
-    }
-  }
-
-  if (envHttps && envHttps.trim()) {
-    return { proxyUrl: envHttps.trim(), source: "env_https_proxy" };
-  }
-  if (envHttp && envHttp.trim()) {
-    return { proxyUrl: envHttp.trim(), source: "env_http_proxy" };
-  }
-  if (envAll && envAll.trim()) {
-    return { proxyUrl: envAll.trim(), source: "env_all_proxy" };
-  }
-  return { proxyUrl: null, source: "none" };
-}
-
-/**
- * Builds Proxy-Authorization header if proxy URL contains credentials.
- */
-function getProxyAuthHeader(proxyUrl: URL): string | null {
-  if (proxyUrl.username) {
-    try {
-      const user = decodeURIComponent(proxyUrl.username);
-      const pass = decodeURIComponent(proxyUrl.password);
-      const token = Buffer.from(`${user}:${pass}`).toString("base64");
-      return `Basic ${token}`;
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-/**
- * Decodes chunked transfer-encoding.
- * Observer implements minimal but spec-compliant decoder for proxy HTTPS path.
- */
-function decodeChunked(body: string): string {
-  let out = "";
-  let i = 0;
-  const len = body.length;
-  while (i < len) {
-    const crlf = body.indexOf("\r\n", i);
-    if (crlf === -1) break;
-    const line = body.slice(i, crlf).trim();
-    if (!line) {
-      i = crlf + 2;
-      continue;
-    }
-    // chunk size may have extension ; — ignore
-    const semi = line.indexOf(";");
-    const sizeHex = semi === -1 ? line : line.slice(0, semi);
-    const size = parseInt(sizeHex, 16);
-    if (Number.isNaN(size)) break;
-    if (size === 0) break; // last chunk
-    i = crlf + 2;
-    if (i + size > len) {
-      // incomplete — take what we have
-      out += body.slice(i);
-      break;
-    }
-    out += body.slice(i, i + size);
-    i += size;
-    // skip trailing CRLF after chunk
-    if (body.slice(i, i + 2) === "\r\n") i += 2;
-  }
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// Low-level proxy fetch implementations — only node:net/tls/http/https
-// ---------------------------------------------------------------------------
-
-interface RawProxyResult {
-  status: number;
-  statusText: string;
-  headers: Record<string, string>;
-  bodyText: string;
-}
-
-interface ProxyFetchResponse {
-  ok: boolean;
-  status: number;
-  statusText: string;
-  headers: { get: (name: string) => string | null; [k: string]: any };
-  text: () => Promise<string>;
-  json: () => Promise<any>;
-  arrayBuffer?: () => Promise<ArrayBuffer>;
-}
-
-/**
- * Creates a fetch-like Response wrapper from raw proxy result.
- */
-function wrapRawResult(raw: RawProxyResult): ProxyFetchResponse {
-  const lowerHeaders: Record<string, string> = {};
-  for (const [k, v] of Object.entries(raw.headers)) lowerHeaders[k.toLowerCase()] = v;
-
-  return {
-    ok: raw.status >= 200 && raw.status < 300,
-    status: raw.status,
-    statusText: raw.statusText,
-    headers: {
-      get: (name: string) => {
-        const v = lowerHeaders[name.toLowerCase()];
-        return v ?? null;
-      },
-      ...raw.headers,
-    },
-    text: async () => raw.bodyText,
-    json: async () => {
-      try {
-        return JSON.parse(raw.bodyText);
-      } catch (e: any) {
-        throw new SearchError(
-          `proxy response not JSON: ${e?.message ?? String(e)} — body: ${raw.bodyText.slice(0, 500)}`,
-          {
-            status: raw.status,
-          },
-        );
-      }
-    },
-  };
-}
-
-/**
- * HTTP target via HTTP proxy — absolute URL in request line.
- * Observer uses node:http.request which already handles chunked.
- *
- * @param targetUrl - full target url
- * @param proxyUrl - proxy url object
- * @param init - fetch init
- * @param timeoutMs - timeout
- * @param signal - abort signal
- */
-function httpRequestViaHttpProxy(
-  targetUrl: URL,
-  proxyUrl: URL,
-  init: RequestInit,
-  timeoutMs: number,
-  signal?: AbortSignal,
-): Promise<RawProxyResult> {
-  return new Promise<RawProxyResult>((resolve, reject) => {
-    const method = init.method ?? "POST";
-    const bodyStr = typeof init.body === "string" ? init.body : init.body ? (init.body as any).toString() : undefined;
-
-    const proxyAuth = getProxyAuthHeader(proxyUrl);
-    const headers: Record<string, string> = { ...(init.headers as Record<string, string> | undefined) };
-
-    // Ensure proxy-required headers
-    if (!headers["Host"]) headers["Host"] = targetUrl.host;
-    if (proxyAuth) headers["Proxy-Authorization"] = proxyAuth;
-    if (!headers["Connection"]) headers["Connection"] = "close";
-
-    const reqOpts: http.RequestOptions = {
-      host: proxyUrl.hostname,
-      port: proxyUrl.port ? parseInt(proxyUrl.port, 10) : 80,
-      method,
-      path: targetUrl.toString(), // absolute URI for HTTP proxy
-      headers,
-    };
-
-    let finished = false;
-    const cleanup = () => {
-      finished = true;
-    };
-
-    const req = http.request(reqOpts, (res) => {
-      const chunks: Buffer[] = [];
-      res.on("data", (c: Buffer) => chunks.push(c));
-      res.on("end", () => {
-        if (finished) return;
-        cleanup();
-        const bodyBuf = Buffer.concat(chunks);
-        const bodyText = bodyBuf.toString("utf8");
-        const hdrs: Record<string, string> = {};
-        for (const [k, v] of Object.entries(res.headers)) {
-          if (Array.isArray(v)) hdrs[k.toLowerCase()] = v.join(", ");
-          else if (v) hdrs[k.toLowerCase()] = String(v);
-        }
-        resolve({
-          status: res.statusCode ?? 0,
-          statusText: res.statusMessage ?? "",
-          headers: hdrs,
-          bodyText,
-        });
-      });
-    });
-
-    req.on("error", (err) => {
-      if (finished) return;
-      cleanup();
-      reject(err);
-    });
-
-    if (timeoutMs) {
-      req.setTimeout(timeoutMs, () => {
-        req.destroy(new Error(`proxy http request timeout after ${timeoutMs}ms to ${targetUrl.hostname}`));
-      });
-    }
-
-    if (signal) {
-      if (signal.aborted) {
-        req.destroy(new Error("aborted"));
-        return;
-      }
-      const onAbort = () => {
-        req.destroy(new Error("aborted by signal"));
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-      req.on("close", () => signal.removeEventListener("abort", onAbort));
-    }
-
-    if (bodyStr) req.write(bodyStr);
-    req.end();
-  });
-}
-
-/**
- * HTTPS target via HTTP proxy using CONNECT tunneling + TLS.
- * Only node:net + node:tls builtins — observer builds tunnel manually.
- *
- * Flow:
- * 1. TCP connect to proxy
- * 2. Send CONNECT host:443
- * 3. Wait for 200
- * 4. TLS over socket
- * 5. Send HTTPS request manually
- *
- * @param targetUrl - https url
- * @param proxyUrl - http proxy url
- * @param init - fetch init
- * @param timeoutMs - timeout
- * @param signal - abort signal
- */
-function httpsRequestViaHttpProxyConnect(
-  targetUrl: URL,
-  proxyUrl: URL,
-  init: RequestInit,
-  timeoutMs: number,
-  signal?: AbortSignal,
-): Promise<RawProxyResult> {
-  return new Promise<RawProxyResult>((resolve, reject) => {
-    const targetHost = targetUrl.hostname;
-    const targetPort = targetUrl.port ? parseInt(targetUrl.port, 10) : 443;
-    const proxyHost = proxyUrl.hostname;
-    const proxyPort = proxyUrl.port ? parseInt(proxyUrl.port, 10) : 8080;
-
-    let settled = false;
-    const doReject = (err: any) => {
-      if (settled) return;
-      settled = true;
-      reject(err);
-    };
-    const doResolve = (v: RawProxyResult) => {
-      if (settled) return;
-      settled = true;
-      resolve(v);
-    };
-
-    const socket = net.createConnection({ host: proxyHost, port: proxyPort });
-
-    if (signal?.aborted) {
-      socket.destroy(new Error("aborted before connect"));
-      return;
-    }
-
-    const abortHandler = () => {
-      socket.destroy(new Error("aborted by signal"));
-    };
-    signal?.addEventListener("abort", abortHandler, { once: true });
-
-    let timeoutId: NodeJS.Timeout | null = null;
-    if (timeoutMs) {
-      timeoutId = setTimeout(() => {
-        socket.destroy(new Error(`proxy CONNECT timeout ${timeoutMs}ms`));
-      }, timeoutMs);
-    }
-
-    socket.on("error", (err) => {
-      if (timeoutId) clearTimeout(timeoutId);
-      signal?.removeEventListener("abort", abortHandler);
-      doReject(err);
-    });
-
-    socket.on("connect", () => {
-      const proxyAuth = getProxyAuthHeader(proxyUrl);
-      const authLine = proxyAuth ? `Proxy-Authorization: ${proxyAuth}\r\n` : "";
-      const connectReq =
-        `CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\n` +
-        `Host: ${targetHost}:${targetPort}\r\n` +
-        `${authLine}` +
-        `Proxy-Connection: Keep-Alive\r\n` +
-        `Connection: Keep-Alive\r\n\r\n`;
-      socket.write(connectReq);
-    });
-
-    let connectBuf = "";
-    const onConnectData = (chunk: Buffer) => {
-      connectBuf += chunk.toString("utf8");
-      if (!connectBuf.includes("\r\n\r\n")) return; // wait full header
-
-      socket.off("data", onConnectData);
-
-      const headerEnd = connectBuf.indexOf("\r\n\r\n");
-      const headerPart = connectBuf.slice(0, headerEnd);
-      const lines = headerPart.split("\r\n");
-      const statusLine = lines[0] ?? "";
-      const m = statusLine.match(/HTTP\/\d\.\d\s+(\d+)/);
-      const status = m ? parseInt(m[1]!, 10) : 0;
-
-      if (status !== 200) {
-        if (timeoutId) clearTimeout(timeoutId);
-        signal?.removeEventListener("abort", abortHandler);
-        socket.destroy();
-        doReject(new SearchError(`proxy CONNECT failed: ${statusLine}`, { status, retryable: status >= 500 }));
-        return;
-      }
-
-      // Tunnel established — leftover after \r\n\r\n may be start of TLS handshake? Actually not, it should be empty.
-      // Now TLS over socket
-      const tlsSocket = tls.connect({
-        socket: socket as any,
-        servername: targetHost,
-        ALPNProtocols: ["http/1.1"],
-      } as any);
-
-      tlsSocket.on("error", (err) => {
-        if (timeoutId) clearTimeout(timeoutId);
-        signal?.removeEventListener("abort", abortHandler);
-        doReject(err);
-      });
-
-      if (timeoutMs) {
-        tlsSocket.setTimeout(timeoutMs, () => {
-          tlsSocket.destroy(new Error(`TLS request timeout ${timeoutMs}ms`));
-        });
-      }
-
-      tlsSocket.on("secureConnect", () => {
-        const method = init.method ?? "POST";
-        const path = `${targetUrl.pathname}${targetUrl.search}`;
-        const initHeaders = (init.headers as Record<string, string>) ?? {};
-        const headers: Record<string, string> = { ...initHeaders };
-
-        if (!headers["Host"]) headers["Host"] = targetUrl.host;
-        if (!headers["Connection"]) headers["Connection"] = "close";
-
-        const bodyStr =
-          typeof init.body === "string"
-            ? init.body
-            : init.body
-              ? Buffer.isBuffer(init.body)
-                ? (init.body as Buffer).toString("utf8")
-                : String(init.body)
-              : "";
-
-        if (bodyStr && !headers["Content-Length"]) {
-          headers["Content-Length"] = Buffer.byteLength(bodyStr).toString();
-        }
-
-        let reqStr = `${method} ${path} HTTP/1.1\r\n`;
-        for (const [k, v] of Object.entries(headers)) {
-          reqStr += `${k}: ${v}\r\n`;
-        }
-        reqStr += `\r\n`;
-        if (bodyStr) reqStr += bodyStr;
-
-        tlsSocket.write(reqStr);
-      });
-
-      let respBuf = Buffer.alloc(0);
-      tlsSocket.on("data", (d: Buffer) => {
-        respBuf = Buffer.concat([respBuf, d]);
-      });
-
-      tlsSocket.on("end", () => {
-        if (timeoutId) clearTimeout(timeoutId);
-        signal?.removeEventListener("abort", abortHandler);
-        try {
-          const respStr = respBuf.toString("utf8");
-          const hdrEnd = respStr.indexOf("\r\n\r\n");
-          if (hdrEnd === -1) {
-            doReject(new SearchError(`invalid HTTPS response via proxy tunnel from ${targetHost}`));
-            return;
-          }
-          const hdrPart = respStr.slice(0, hdrEnd);
-          let bodyPart = respStr.slice(hdrEnd + 4);
-          const hdrLines = hdrPart.split("\r\n");
-          const statusLine = hdrLines[0] ?? "";
-          const sm = statusLine.match(/HTTP\/\d\.\d\s+(\d+)\s*(.*)/);
-          const statusCode = sm ? parseInt(sm[1]!, 10) : 0;
-          const statusText = sm ? (sm[2] ?? "") : "";
-
-          const hdrs: Record<string, string> = {};
-          for (let i = 1; i < hdrLines.length; i++) {
-            const line = hdrLines[i]!;
-            const idx = line.indexOf(":");
-            if (idx === -1) continue;
-            const k = line.slice(0, idx).trim().toLowerCase();
-            const v = line.slice(idx + 1).trim();
-            hdrs[k] = v;
-          }
-
-          // Handle chunked
-          if (hdrs["transfer-encoding"]?.toLowerCase() === "chunked") {
-            bodyPart = decodeChunked(bodyPart);
-          }
-
-          doResolve({
-            status: statusCode,
-            statusText,
-            headers: hdrs,
-            bodyText: bodyPart,
-          });
-        } catch (e: any) {
-          doReject(new SearchError(`failed parsing HTTPS proxy response: ${e?.message ?? String(e)}`, { cause: e }));
-        } finally {
-          try {
-            tlsSocket.destroy();
-          } catch {
-            /* the guarded best-effort operation falls through: the outer flow owns the failure */
-          }
-        }
-      });
-    };
-
-    socket.on("data", onConnectData);
-  });
-}
-
-/**
- * Generic proxy-aware fetch — observer tries native fetch if no proxy,
- * otherwise manual CONNECT for https or absolute-URL for http.
- *
- * @param url - target
- * @param init - fetch init
- * @param proxyUrlStr - resolved proxy url string or null
- * @param timeoutMs - timeout
- */
-async function fetchWithProxy(
-  url: string,
-  init: RequestInit,
-  proxyUrlStr: string | null,
-  timeoutMs: number,
-): Promise<{
-  ok: boolean;
-  status: number;
-  statusText?: string;
-  headers: any;
-  text: () => Promise<string>;
-  json: () => Promise<any>;
-}> {
-  if (!proxyUrlStr) {
-    // native path — with timeout + signal merge
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error(`timeout ${timeoutMs}ms ${url}`)), timeoutMs);
-
-    // merge external signal if present
-    const externalSignal = init.signal as AbortSignal | undefined;
-    let onExternalAbort: (() => void) | null = null;
-    if (externalSignal) {
-      if (externalSignal.aborted) {
-        clearTimeout(timer);
-        controller.abort(externalSignal.reason);
-      } else {
-        onExternalAbort = () => controller.abort(externalSignal.reason);
-        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
-      }
-    }
-
-    try {
-      const res = await fetch(url, { ...init, signal: controller.signal });
-      return res as any;
-    } finally {
-      clearTimeout(timer);
-      if (onExternalAbort && externalSignal) {
-        externalSignal.removeEventListener("abort", onExternalAbort);
-      }
-    }
-  }
-
-  // proxy path
-  let proxyUrl: URL;
-  let targetUrl: URL;
-  try {
-    proxyUrl = new URL(proxyUrlStr);
-  } catch {
-    throw new SearchError(`invalid proxyUrl: ${proxyUrlStr}`);
-  }
-  try {
-    targetUrl = new URL(url);
-  } catch {
-    throw new SearchError(`invalid target url: ${url}`);
-  }
-
-  const method = init.method ?? "POST";
-
-  const proxyResult =
-    targetUrl.protocol === "https:"
-      ? await httpsRequestViaHttpProxyConnect(
-          targetUrl,
-          proxyUrl,
-          { ...init, method },
-          timeoutMs,
-          init.signal as AbortSignal | undefined,
-        )
-      : await httpRequestViaHttpProxy(
-          targetUrl,
-          proxyUrl,
-          { ...init, method },
-          timeoutMs,
-          init.signal as AbortSignal | undefined,
-        );
-
-  return wrapRawResult(proxyResult) as any;
-}
-
-// ---------------------------------------------------------------------------
-// Fetch with timeout helper — mirrors project.ts fetchWithTimeout
-// ---------------------------------------------------------------------------
-
-/**
- * Fetch with timeout using AbortController.
- * Observer pattern: never leaks abort timer.
- *
- * @param url - url
- * @param init - init
- * @param timeoutMs - timeout
- * @param proxyUrl - optional proxy
- */
-// local variant: diverges from models (models.fetchWithTimeout takes `init.timeoutMs` and aborts a plain fetch; this variant takes an explicit timeoutMs plus proxyUrl and routes through fetchWithProxy)
-export async function fetchWithProxyTimeout(
-  url: string,
-  init: RequestInit,
-  timeoutMs: number = FETCH_TIMEOUT_MS,
-  proxyUrl: string | null = null,
-): Promise<any> {
-  return fetchWithProxy(url, init, proxyUrl, timeoutMs);
-}
-
-// ---------------------------------------------------------------------------
-// Thinking budget resolver — per RESEARCH.md 100+ terms
-// ---------------------------------------------------------------------------
-
-/**
- * Resolves thinking budget from level or direct number.
- * Observer clamps to Gemini max 32768.
- *
- * @param level - thinkingLevel minimal/low/medium/high
- * @param directBudget - optional direct thinkingBudget
- * @returns clamped budget number
- */
-export function resolveThinkingBudget(level?: ThinkingLevel, directBudget?: number): number {
-  if (typeof directBudget === "number" && Number.isFinite(directBudget)) {
-    const clamped = Math.max(0, Math.min(directBudget, THINKING_BUDGET_MAX_GEMINI));
-    return Math.floor(clamped);
-  }
-  if (level && (THINKING_LEVELS as readonly string[]).includes(level)) {
-    return THINKING_BUDGET_MAP[level] ?? THINKING_BUDGET_MAP.medium;
-  }
-  // default medium per governance
-  return THINKING_BUDGET_MAP.medium;
-}
-
-// ---------------------------------------------------------------------------
-// Model helpers — 2026 awareness
-// ---------------------------------------------------------------------------
-
-/**
- * Normalizes model name — strips models/ prefix for body, keeps original for logging.
- * Observer notes cloudcode-pa accepts both gemini-3-flash and models/gemini-3-flash.
- *
- * @param raw - model id
- */
-export function normalizeModelName(raw: string): { bare: string; withPrefix: string; original: string } {
-  const original = String(raw ?? "").trim();
-  const bare = original.replace(/^models\//i, "").trim();
-  const withPrefix = `models/${bare}`;
-  return { bare, withPrefix, original };
-}
-
-/**
- * Builds request body for cloudcode-pa v1internal:generateContent.
- * Observer has seen two shapes in the wild; prefers wrapped shape when projectId present.
- *
- * Shape A (Antigravity internal with project):
- * { model, project, request: { contents, tools, generationConfig, systemInstruction } }
- *
- * Shape B (flat Gemini SA):
- * { model, contents, tools, generationConfig, systemInstruction }
- *
- * @param model - bare model
- * @param projectId - optional project
- * @param contents - Gemini contents array
- * @param tools - googleSearch + urlContext tools
- * @param generationConfig - thinking + temp
- * @param systemInstruction - optional system instruction
- */
-function buildGenerateContentBody(opts: {
-  model: string;
-  projectId?: string | undefined;
-  contents: any[];
-  tools: any[];
-  generationConfig: any;
-  systemInstruction?: any | undefined;
-}): any {
-  const { model, projectId, contents, tools, generationConfig, systemInstruction } = opts;
-
-  if (projectId) {
-    // wrapped — observed in AM content traffic
-    return {
-      model,
-      project: projectId,
-      request: {
-        contents,
-        tools,
-        generationConfig,
-        ...(systemInstruction ? { systemInstruction } : {}),
-      },
-    };
-  }
-  // flat
-  return {
-    model,
-    contents,
-    tools,
-    generationConfig,
-    ...(systemInstruction ? { systemInstruction } : {}),
-  };
-}
-
-/**
- * Builds alternative body with models/ prefix if primary fails with 404/400.
- * Fallback chain: bare → withPrefix → wrapped with other model variant.
- */
-function buildAlternativeBodies(
-  primaryBody: any,
-  normalized: ReturnType<typeof normalizeModelName>,
-  projectId?: string,
-): any[] {
-  const bodies: any[] = [];
-  const { bare, withPrefix } = normalized;
-
-  // 1. try bare flat if primary was wrapped
-  if (primaryBody.project) {
-    bodies.push({
-      model: bare,
-      contents: primaryBody.request.contents,
-      tools: primaryBody.request.tools,
-      generationConfig: primaryBody.request.generationConfig,
-      ...(primaryBody.request.systemInstruction ? { systemInstruction: primaryBody.request.systemInstruction } : {}),
-    });
-  }
-  // 2. try withPrefix
-  bodies.push({
-    ...primaryBody,
-    model: withPrefix,
-  });
-  if (primaryBody.request) {
-    bodies.push({
-      model: withPrefix,
-      project: projectId,
-      request: { ...primaryBody.request },
-    });
-    bodies.push({
-      model: withPrefix,
-      contents: primaryBody.request.contents,
-      tools: primaryBody.request.tools,
-      generationConfig: primaryBody.request.generationConfig,
-      ...(primaryBody.request.systemInstruction ? { systemInstruction: primaryBody.request.systemInstruction } : {}),
-    });
-  } else {
-    bodies.push({
-      model: withPrefix,
-      contents: primaryBody.contents,
-      tools: primaryBody.tools,
-      generationConfig: primaryBody.generationConfig,
-      ...(primaryBody.systemInstruction ? { systemInstruction: primaryBody.systemInstruction } : {}),
-    });
-  }
-  // 3. try fallback models from SEARCH_MODEL_FALLBACKS
-  for (const fallbackModel of SEARCH_MODEL_FALLBACKS) {
-    if (fallbackModel === bare || fallbackModel === withPrefix) continue;
-    bodies.push({
-      model: fallbackModel,
-      project: projectId,
-      request: primaryBody.request ?? {
-        contents: primaryBody.contents,
-        tools: primaryBody.tools,
-        generationConfig: primaryBody.generationConfig,
-      },
-    });
-    if (bodies.length > 8) break;
-  }
-  return bodies;
-}
-
-// ---------------------------------------------------------------------------
-// Grounding parse — rigorous, handles heterogenous server shapes
-// ---------------------------------------------------------------------------
-
-/**
- * Extracts text from Gemini candidate content parts.
- * Observer notes parts may be [{text}, {thought}, {inlineData}] — only text counted.
- *
- * @param candidate - candidate object
- */
-function extractTextFromCandidate(candidate: any): string {
-  if (!candidate) return "";
-  // direct text field (some internal shapes)
-  if (typeof candidate.text === "string") return candidate.text;
-  if (candidate.content?.parts && Array.isArray(candidate.content.parts)) {
-    const texts: string[] = [];
-    for (const part of candidate.content.parts) {
-      if (part && typeof part.text === "string" && part.text.length > 0) {
-        // thought parts are flagged think? but per spec includeThoughts=false we get only answer
-        if (part.thought === true) continue;
-        texts.push(part.text);
-      }
-    }
-    if (texts.length > 0) return texts.join("\n");
-  }
-  // alternative: candidates[0].content.parts aggregation handled outside
-  return "";
-}
-
-/**
- * Parses groundingMetadata from various response shapes.
- * Observer is resilient: checks candidate.groundingMetadata, response.groundingMetadata,
- * and alternative field grounding_metadata.
- *
- * @param response - full JSON response
- * @param candidate - first candidate
- */
-function parseGroundingMetadataFromResponse(response: any, candidate: any): GroundingMetadata | undefined {
-  if (candidate?.groundingMetadata) return candidate.groundingMetadata as GroundingMetadata;
-  if (candidate?.grounding_metadata) return candidate.grounding_metadata as GroundingMetadata;
-  if (response?.groundingMetadata) return response.groundingMetadata as GroundingMetadata;
-  if (response?.grounding_metadata) return response.grounding_metadata as GroundingMetadata;
-  // sometimes in candidates[0].citationMetadata.grounding? not
-  if (response?.candidates && Array.isArray(response.candidates) && response.candidates[0]?.groundingMetadata) {
-    return response.candidates[0].groundingMetadata as GroundingMetadata;
-  }
-  return undefined;
-}
-
-/**
- * Normalizes groundingChunks into WebGroundingChunk[] with uri/title/domain.
- * Observer filters out chunks without uri, dedupes by uri preservation order.
- *
- * @param meta - groundingMetadata
- */
-function normalizeGroundingChunks(meta: GroundingMetadata | undefined): WebGroundingChunk[] {
-  if (!meta?.groundingChunks || !Array.isArray(meta.groundingChunks)) return [];
-  const seen = new Set<string>();
-  const out: WebGroundingChunk[] = [];
-  for (const ch of meta.groundingChunks) {
-    const web = (ch as any).web ?? (ch as any).retrievedContext ?? {};
-    const rawUri = web.uri ?? (ch as any).uri ?? "";
-    const rawTitle = web.title ?? (ch as any).title ?? "";
-    if (!rawUri || typeof rawUri !== "string") continue;
-    // normalize uri
-    let uri: string;
-    try {
-      // basic validation — must be http(s)
-      const u = new URL(rawUri);
-      if (!u.protocol.startsWith("http")) continue;
-      uri = u.toString();
-    } catch {
-      continue;
-    }
-    if (seen.has(uri)) continue;
-    seen.add(uri);
-    let domain: string | undefined;
-    try {
-      domain = new URL(uri).hostname;
-    } catch {
-      domain = undefined;
-    }
-    out.push({
-      uri,
-      title: String(rawTitle || domain || uri).slice(0, 500),
-      domain,
-    });
-  }
-  return out;
-}
-
-/**
- * Extracts webSearchQueries from groundingMetadata.
- */
-function extractWebSearchQueries(meta: GroundingMetadata | undefined): string[] {
-  if (!meta) return [];
-  const queries = meta.webSearchQueries ?? meta.retrievalQueries ?? [];
-  if (!Array.isArray(queries)) return [];
-  return queries
-    .filter((q) => typeof q === "string" && (q as string).trim().length > 0)
-    .map((q) => String(q).trim())
-    .slice(0, 20); // cap 20 queries per spec sanity
-}
-
-// ---------------------------------------------------------------------------
-// Core — executeSearch
-// ---------------------------------------------------------------------------
-
-/**
- * Executes grounded search using Gemini native googleSearch + urlContext tools.
- * Third-person observer pattern: imitates Antigravity's google_search tool wrapper
- * but calls cloudcode-pa.googleapis.com directly, no localhost proxy.
- *
- * The observer:
- * 1. Validates query + accessToken.
- * 2. Resolves proxy (env + option) with NO_PROXY bypass.
- * 3. Resolves thinking budget from level or direct number, clamped 32k.
- * 4. Builds contents + tools [{googleSearch:{}},{urlContext:{}}] + generationConfig.
- * 5. Builds Antigravity headers (Bearer, UA dynamic, Client-Metadata, Api-Client)
- *    stripping x-goog-user-project per bypass spec.
- * 6. Cascades endpoints PROD → DAILY → SANDBOX on 403/404/5xx with jitter 0-80ms.
- * 7. Parses groundingMetadata.groundingChunks[].web.uri/title and webSearchQueries.
- *
- * @param input - query + optional systemPrompt
- * @param auth - OAuth access token + projectId + UA override
- * @param opts - model, thinking, proxy, timeout, endpoints, etc.
- * @returns grounded SearchResult with parsed chunks
- *
- * @throws SearchError on validation, timeout, 401, exhausted cascade, or invalid JSON.
- *
- * @example
- * ```ts
- * const result = await executeSearch(
- *   { query: "latest Gemini 3 flash grounding changes 2026" },
- *   { accessToken: "...", projectId: "rising-fact-p41fc" },
- *   { thinkingLevel: "medium", useUrlContext: true }
- * );
- * console.log(result.text);
- * console.log(result.groundingChunks.map(c=>c.uri));
- * ```
- */
-export async function executeSearch(
-  input: ExecuteSearchInput,
-  auth: ExecuteSearchAuth,
-  opts: ExecuteSearchOptions = {},
-): Promise<SearchResult> {
-  // -----------------------------------------------------------------------
-  // Validation — production ready, no placeholder
-  // -----------------------------------------------------------------------
-  if (!input || typeof input.query !== "string" || input.query.trim().length === 0) {
-    throw new SearchError("query must be a non-empty string", { code: "INVALID_QUERY" });
-  }
-  const query = input.query.trim();
-  if (query.length > 20000) {
-    throw new SearchError(`query too long (${query.length} > 20000 chars)`, { code: "QUERY_TOO_LONG" });
-  }
-  if (!auth || typeof auth.accessToken !== "string" || auth.accessToken.trim().length === 0) {
-    throw new SearchError("accessToken required — missing auth.accessToken Bearer", { code: "MISSING_TOKEN" });
-  }
-  const accessToken = auth.accessToken.trim();
-  // basic Bearer format check — JWT-ish or ya29.
-  if (accessToken.length < 20) {
-    throw new SearchError("accessToken appears too short to be valid", { code: "INVALID_TOKEN" });
-  }
-
-  // -----------------------------------------------------------------------
-  // Resolve model — SEARCH_MODEL gemini-3-flash per spec
-  // -----------------------------------------------------------------------
-  const rawModel = (opts.model ?? SEARCH_MODEL).trim() || SEARCH_MODEL;
-  const normalizedModel = normalizeModelName(rawModel);
-  const modelBare = normalizedModel.bare || SEARCH_MODEL;
-
-  // -----------------------------------------------------------------------
-  // Thinking budget — level → budget map, clamped
-  // -----------------------------------------------------------------------
-  const thinkingBudget = resolveThinkingBudget(opts.thinkingLevel, opts.thinkingBudget);
-
-  // -----------------------------------------------------------------------
-  // Tools — native googleSearch + urlContext per requirement
-  // -----------------------------------------------------------------------
-  const useGoogleSearch = opts.useGoogleSearch !== false; // default true
-  const useUrlContext = opts.useUrlContext !== false; // default true
-  const tools: any[] = [];
-  if (useGoogleSearch) tools.push({ googleSearch: {} });
-  if (useUrlContext) tools.push({ urlContext: {} });
-  // fallback — at least one grounding tool required
-  if (tools.length === 0) tools.push({ googleSearch: {} });
-
-  // -----------------------------------------------------------------------
-  // Contents + system instruction
-  // -----------------------------------------------------------------------
-  const contents: any[] = [
-    {
-      role: "user",
-      parts: [
-        {
-          text: input.additionalContext ? `${query}\n\nContext: ${input.additionalContext}` : query,
-        },
-      ],
-    },
-  ];
-
-  const systemInstruction = input.systemPrompt
-    ? { parts: [{ text: String(input.systemPrompt).slice(0, 8000) }] }
-    : undefined;
-
-  const generationConfig: any = {
-    // Thinking — Gemini 3 supports thinkingConfig
-    thinkingConfig: {
-      thinkingBudget,
-      includeThoughts: false,
-    },
-    temperature: typeof opts.temperature === "number" ? opts.temperature : 0.2,
-    maxOutputTokens: typeof opts.maxOutputTokens === "number" ? opts.maxOutputTokens : 8192,
-  };
-
-  const primaryBody = buildGenerateContentBody({
-    model: modelBare,
-    projectId: auth.projectId,
-    contents,
-    tools,
-    generationConfig,
-    systemInstruction,
-  });
-
-  // -----------------------------------------------------------------------
-  // Proxy resolution — supports HTTP_PROXY/HTTPS_PROXY/NO_PROXY
-  // -----------------------------------------------------------------------
-  // Use first endpoint as NO_PROXY check target — if endpoint in NO_PROXY list, bypass
-  const firstEndpointForProxyCheck = (opts.endpoints?.[0] ?? DEFAULT_ENDPOINT_ORDER[0]) + GENERATE_CONTENT_ENDPOINT;
-  const proxyResolution = resolveProxyUrl(opts.proxyUrl, firstEndpointForProxyCheck);
-  const proxyUrlStr = proxyResolution.proxyUrl;
-
-  // -----------------------------------------------------------------------
-  // UA + headers — observer builds dynamic UA antigravity/{ver} {os}/{arch}
-  // -----------------------------------------------------------------------
-  const version = auth.version ?? ANTIGRAVITY_VERSION_FALLBACK;
-  const userAgent = auth.userAgent ?? getDynamicUserAgent(version);
-  const extraHeaders: Record<string, string> = {};
-  // allow projectId as header? No — strip per bypass. Project sent in body only.
-
-  const baseHeaders = buildAntagravityHeaders(accessToken, { userAgent, extra: extraHeaders });
-
-  // -----------------------------------------------------------------------
-  // Endpoint cascade
-  // -----------------------------------------------------------------------
-  const endpoints = opts.endpoints && opts.endpoints.length > 0 ? opts.endpoints : [...DEFAULT_ENDPOINT_ORDER];
-  const timeoutMs = typeof opts.timeoutMs === "number" && opts.timeoutMs > 0 ? opts.timeoutMs : SEARCH_TIMEOUT_MS;
-  const jitterEnabled = opts.jitter !== false;
-
-  let lastError: SearchError | Error | null = null;
-  let attemptedBodiesTried = 0;
-
-  // For debugging
-  if (opts.debug) {
-    // eslint-disable-next-line no-console
-    console.debug(
-      `[search] observer start queryLen=${query.length} model=${modelBare} budget=${thinkingBudget} proxy=${proxyResolution.source} tokenHash=${hashToken(accessToken)} endpoints=${endpoints.join(",")}`,
-    );
-  }
-
-  // Try each endpoint, with body fallback strategy
-  for (let epIdx = 0; epIdx < endpoints.length; epIdx++) {
-    const base = endpoints[epIdx]!.replace(/\/$/, "");
-    const url = `${base}${GENERATE_CONTENT_ENDPOINT}`;
-
-    // Try primary body + alternative bodies if 400/404
-    const bodiesToTry = [primaryBody, ...buildAlternativeBodies(primaryBody, normalizedModel, auth.projectId)];
-    // deduplicate by JSON stringify quickly via model name (small optimization)
-    const seenModels = new Set<string>();
-    const dedupedBodies: any[] = [];
-    for (const b of bodiesToTry) {
-      const key = `${b.model}|${b.project ?? ""}|${b.request ? "wrapped" : "flat"}`;
-      if (seenModels.has(key)) continue;
-      seenModels.add(key);
-      dedupedBodies.push(b);
-    }
-
-    for (let bodyIdx = 0; bodyIdx < dedupedBodies.length; bodyIdx++) {
-      const body = dedupedBodies[bodyIdx];
-      attemptedBodiesTried++;
-
-      // To avoid infinite loops, limit total attempts
-      if (opts.maxRetries && attemptedBodiesTried > (opts.maxRetries ?? 8) * endpoints.length) break;
-
-      const fetchHeaders = { ...baseHeaders };
-
-      const fetchInit: RequestInit = {
-        method: "POST",
-        headers: fetchHeaders as any,
-        body: JSON.stringify(body),
-      };
-
-      if (opts.debug) {
-        // eslint-disable-next-line no-console
-        console.debug(
-          `[search] attempt ep=${base} bodyModel=${body.model} wrapped=${!!body.request} attempt=${attemptedBodiesTried}`,
-        );
-      }
-
-      let res: any;
-      try {
-        res = await fetchWithProxyTimeout(url, fetchInit, timeoutMs, proxyUrlStr);
-      } catch (networkErr: any) {
-        // network failure — retryable
-        const err = new SearchError(`network failure to ${base}: ${networkErr?.message ?? String(networkErr)}`, {
-          endpoint: base,
-          retryable: true,
-          code: "NETWORK_ERROR",
-          cause: networkErr,
-        });
-        lastError = err;
-        if (opts.debug) console.debug(`[search] network error ${err.message}`);
-        // jitter before next endpoint/body
-        if (jitterEnabled) await sleep(getJitter());
-        continue; // next body / endpoint
-      }
-
-      // HTTP status handling
-      const status: number = res.status ?? 0;
-      if (!res.ok) {
-        let bodyText = "";
-        try {
-          bodyText = await res.text();
-        } catch {
-          bodyText = "";
-        }
-
-        // Parse error for log trimming
-        const truncated = bodyText.slice(0, 2000);
-
-        const retryable = isRetryableStatus(status);
-        const code =
-          status === 401
-            ? "UNAUTHORIZED"
-            : status === 403
-              ? "FORBIDDEN"
-              : status === 429
-                ? "RATE_LIMITED"
-                : status >= 500
-                  ? "SERVER_ERROR"
-                  : "HTTP_ERROR";
-
-        const err = new SearchError(`search failed ${status} at ${base}: ${truncated}`, {
-          status,
-          endpoint: base,
-          retryable,
-          code,
-        });
-
-        lastError = err;
-
-        if (opts.debug) {
-          // eslint-disable-next-line no-console
-          console.debug(`[search] http ${status} retryable=${retryable} body=${truncated.slice(0, 500)}`);
-        }
-
-        // 401 Unauthorized — no point retrying other endpoints with same token
-        if (status === 401) {
-          throw err;
-        }
-
-        // 403/404/429/5xx — try next endpoint (cascade) or next body variant if 400
-        if (status === 400 && bodyIdx === 0) {
-          // bad request maybe due to model naming — try next body variant without switching endpoint
-          if (jitterEnabled) await sleep(getJitter());
-          continue;
-        }
-
-        if (retryable) {
-          if (jitterEnabled) await sleep(getJitter());
-          // break inner body loop to try next endpoint
-          break;
-        }
-
-        // non-retryable 400 etc. — if first body, try alternative bodies
-        if (status === 400 && bodyIdx < dedupedBodies.length - 1) {
-          if (jitterEnabled) await sleep(getJitter());
-          continue;
-        }
-
-        // otherwise keep as lastError and try next endpoint
-        if (jitterEnabled) await sleep(getJitter());
-        break;
-      }
-
-      // -----------------------------------------------------------------
-      // Success path — parse JSON
-      // -----------------------------------------------------------------
-      let json: any;
-      try {
-        json = await res.json();
-      } catch (parseErr: any) {
-        let txt = "";
-        try {
-          txt = await res.text();
-        } catch {
-          /* the guarded best-effort operation falls through: the outer flow owns the failure */
-        }
-        throw new SearchError(
-          `failed parsing search JSON from ${base}: ${parseErr?.message ?? String(parseErr)} — text: ${txt.slice(0, 1000)}`,
-          {
-            status,
-            endpoint: base,
-            code: "INVALID_JSON",
-            cause: parseErr,
-          },
-        );
-      }
-
-      // Response shape may be array? Some internal endpoints wrap in []?
-      // Normalize: if json is array, take first
-      const responseObj = Array.isArray(json) ? json[0] : json;
-
-      // Candidates extraction — heterogenous shapes
-      const candidates = responseObj?.candidates ?? responseObj?.response?.candidates ?? [];
-      const firstCandidate = Array.isArray(candidates) && candidates.length > 0 ? candidates[0] : responseObj;
-
-      const text =
-        extractTextFromCandidate(firstCandidate) ||
-        (typeof responseObj?.text === "string" ? responseObj.text : "") ||
-        (typeof responseObj?.output === "string" ? responseObj.output : "");
-
-      if (!text || text.trim().length === 0) {
-        // Sometimes grounding only returns metadata without text when query is just URLs? Treat as empty but still return grounding
-        if (opts.debug)
-          console.debug(`[search] empty text but status ok, json keys=${Object.keys(responseObj).join(",")}`);
-      }
-
-      const groundingMeta = parseGroundingMetadataFromResponse(responseObj, firstCandidate);
-      const groundingChunks = normalizeGroundingChunks(groundingMeta);
-      const webSearchQueries = extractWebSearchQueries(groundingMeta);
-
-      const result: SearchResult = {
-        text: text ?? "",
-        query,
-        model: body.model ?? modelBare,
-        grounded: groundingChunks.length > 0 || webSearchQueries.length > 0,
-        webSearchQueries,
-        groundingChunks,
-        groundingSupports: groundingMeta?.groundingSupports,
-        searchEntryPoint: groundingMeta?.searchEntryPoint,
-        groundingMetadata: opts.includeGrounding !== false ? groundingMeta : undefined,
-        raw: responseObj,
-        endpointUsed: base,
-        thinkingBudgetUsed: thinkingBudget,
-        isFallbackProject: auth.projectId === "rising-fact-p41fc" || body.project === "rising-fact-p41fc",
-      };
-
-      if (opts.debug) {
-        // eslint-disable-next-line no-console
-        console.debug(
-          `[search] success endpoint=${base} grounded=${result.grounded} chunks=${result.groundingChunks.length} queries=${result.webSearchQueries.length} textLen=${result.text.length}`,
-        );
-      }
-
-      return result;
-    } // end bodies loop
-
-    // after body loop for this endpoint, if we exhausted bodies and have retryable error, continue to next endpoint
-    // jitter already applied
-  } // end endpoints loop
-
-  // -----------------------------------------------------------------------
-  // All endpoints failed — throw last error with context
-  // -----------------------------------------------------------------------
-  if (lastError) {
-    if (lastError instanceof SearchError) throw lastError;
-    throw new SearchError(
-      `all search endpoints failed: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
-      {
-        code: "ALL_ENDPOINTS_FAILED",
-        cause: lastError,
-      },
-    );
-  }
-  throw new SearchError(
-    `all search endpoints failed without specific error — attempted ${endpoints.length} endpoints, ${attemptedBodiesTried} bodies`,
-    {
-      code: "ALL_ENDPOINTS_FAILED",
-    },
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Convenience wrappers — library-first root-first exports
-// ---------------------------------------------------------------------------
-
-/**
- * Convenience: execute search with project fallback rising-fact-p41fc.
- * Observer notes this fallback works for Antigravity but 403 for Gemini CLI models.
- *
- * @param query - search query
- * @param accessToken - bearer token
- * @param opts - optional search options + projectId override
- */
-export async function searchWithFallback(
-  query: string,
-  accessToken: string,
-  opts: ExecuteSearchOptions & { projectId?: string; systemPrompt?: string } = {},
-): Promise<SearchResult> {
-  const projectId = opts.projectId ?? "rising-fact-p41fc";
-  return executeSearch({ query, systemPrompt: opts.systemPrompt }, { accessToken, projectId }, opts);
-}
-
-/**
- * Extracts only grounding URIs from result — helper for TUI.
- *
- * @param result - SearchResult
- * @returns uri strings
- */
-export function extractGroundingUris(result: SearchResult): string[] {
-  return result.groundingChunks.map((c) => c.uri).filter(Boolean);
-}
-
-/**
- * Extracts grounding titles for UI display.
- */
-export function extractGroundingTitles(result: SearchResult): Array<{ uri: string; title: string }> {
-  return result.groundingChunks.map((c) => ({ uri: c.uri, title: c.title }));
-}
-
-// ---------------------------------------------------------------------------
-// Plugin helpers - search gating, grounding formatting, image generation
-// (ported from search(3).ts lineage)
-// ---------------------------------------------------------------------------
-
-/**
- * Decides whether native googleSearch grounding should be enabled for a model
- * given plugin config (`google_search_enabled`: true | "auto" | falsy).
- */
-export const shouldEnableSearch = (model: string, cfg: any): boolean => {
-  if (cfg?.google_search_enabled === true) return true;
-  if (cfg?.google_search_enabled === "auto") {
-    const l = model.toLowerCase();
-    return l.includes("gemini") && !l.includes("image");
-  }
-  return false;
-};
-
-/** Builds the native grounding tool list: googleSearch + urlContext. */
-export const buildSearchTools = (): any[] => [{ googleSearch: {} }, { urlContext: {} }];
-
-/** Normalizes groundingMetadata chunks into {uri,title} pairs.
- * Identical to core.parseGrounding — imported from the frozen owner and
- * re-exported above. */
-
-/** Formats grounding sources as markdown citation lines. */
-export const extractCitations = (grounding: any[]): string =>
-  grounding.map((g) => `[${g.title || "source"}](${g.uri})`).join("\n");
-
-/**
- * Saves a base64-encoded PNG under ~/.config/opencode/generated-images (or a
- * custom dir) using an timestamped random filename; returns the written path.
- */
-export const saveGeneratedImage = async (b64: string, dir?: string): Promise<string> => {
-  const base = dir || pathJoin(os.homedir(), ".config", "opencode", "generated-images");
-  try {
-    mkdirSync(base, { recursive: true });
-  } catch {
-    /* the guarded best-effort operation falls through: the outer flow owns the failure */
-  }
-  const name = `img-${Date.now()}-${Math.random().toString(16).slice(2)}.png`;
-  const filePath = pathJoin(base, name);
-  const buf = Buffer.from(b64, "base64");
-  writeFileSync(filePath, buf);
-  return filePath;
-};
-
-/** Renders grounding sources as a markdown bullet list. */
-export const groundingToMarkdown = (grounding: any[]): string =>
-  grounding.map((g) => `- [${g.title || g.uri}](${g.uri})`).join("\n");
-
-// ---------------------------------------------------------------------------
-// Barrel default export — library-first
-// ---------------------------------------------------------------------------
-
-export const Search = {
-  SEARCH_MODEL,
-  SEARCH_MODEL_PREVIEW,
-  SEARCH_MODEL_FALLBACKS,
-  CODE_ASSIST_ENDPOINTS,
-  DEFAULT_ENDPOINT_ORDER,
-  GENERATE_CONTENT_ENDPOINT,
-  THINKING_BUDGET_MAP,
-  THINKING_LEVELS,
-  THINKING_BUDGET_MAX_GEMINI,
-  ANTIGRAVITY_VERSION_FALLBACK,
-  ANTIGRAVITY_USER_AGENT_FALLBACK,
-  getDynamicUserAgent,
-  buildAntagravityHeaders,
-  fetchWithProxyTimeout,
-  resolveProxyUrl,
-  isNoProxyMatch,
-  resolveThinkingBudget,
-  normalizeModelName,
-  executeSearch,
-  searchWithFallback,
-  extractGroundingUris,
-  extractGroundingTitles,
-  shouldEnableSearch,
-  buildSearchTools,
-  parseGrounding,
-  extractCitations,
-  isImageGenModel,
-  buildImageGenConfig,
-  saveGeneratedImage,
-  groundingToMarkdown,
-  SearchError,
-  isRetryableStatus,
-  getJitter,
-  fnv1a32,
-};
-
-export default Search;