dsh-lcx-codex 0.4.2 → 0.4.3-pre.13

package/lib/web-search-capability.js

@@ -1,78 +1,93 @@
-import { createHash } from 'node:crypto'
-import { ALPHA_PROBE_VERSION } from './web-search-alpha.js'
-import { JsonStore } from './json-store.js'
-
-const VERSION = 1
-const CLASSIFICATIONS = new Set(['native', 'command-capable', 'emulated-search-only', 'unsupported', 'unknown'])
-const ACTION_STATES = new Set(['supported', 'unsupported', 'unknown'])
-
+import { createHash } from "node:crypto";
+import { ALPHA_ACTIONS, ALPHA_PROBE_VERSION, ALPHA_SEARCH_PARAMETERS } from "./web-search-alpha.js";
+import { JsonStore } from "./json-store.js";
+const VERSION = 1;
+const CLASSIFICATIONS = new Set(["native", "command-capable", "emulated-search-only", "unsupported", "unknown"]);
+const ACTION_STATES = new Set(["supported", "unsupported", "unknown"]);
 function isRecord(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-
+function isClassification(value) { return typeof value === "string" && CLASSIFICATIONS.has(value); }
+function isActionState(value) { return typeof value === "string" && ACTION_STATES.has(value); }
+function isProvenance(value) { return value === "trusted-native" || value === "unavailable"; }
+function isPositiveSafeInteger(value) { return typeof value === "number" && Number.isSafeInteger(value) && value > 0; }
 function validRecord(record) {
-  return isRecord(record) && CLASSIFICATIONS.has(record.classification) &&
-    isRecord(record.actions) && Object.values(record.actions).every((value) => ACTION_STATES.has(value)) &&
-    typeof record.probedAt === 'string' && !Number.isNaN(Date.parse(record.probedAt)) &&
-    typeof record.schemaFingerprint === 'string' && record.schemaFingerprint.length > 0 &&
-    (record.probeVersion === undefined || (Number.isSafeInteger(record.probeVersion) && record.probeVersion > 0)) &&
-    (record.provenance === undefined || ['trusted-native', 'unavailable'].includes(record.provenance)) &&
-    (record.classification !== 'native' || record.provenance === 'trusted-native')
+    if (!isRecord(record) || !isClassification(record.classification) || !isRecord(record.actions) ||
+        !Object.values(record.actions).every(isActionState) || typeof record.probedAt !== "string" ||
+        Number.isNaN(Date.parse(record.probedAt)) || typeof record.schemaFingerprint !== "string" || !record.schemaFingerprint ||
+        (record.probeVersion !== undefined && !isPositiveSafeInteger(record.probeVersion)) ||
+        (record.provenance !== undefined && !isProvenance(record.provenance)))
+        return false;
+    return record.classification !== "native" || record.provenance === "trusted-native";
 }
-
 function validData(data) {
-  return data?.version === VERSION && isRecord(data.capabilities) &&
-    Object.entries(data.capabilities).every(([key, value]) => /^[a-f0-9]{64}$/u.test(key) && validRecord(value))
+    return isRecord(data) && data.version === VERSION && isRecord(data.capabilities) &&
+        Object.entries(data.capabilities).every(([key, value]) => /^[a-f0-9]{64}$/u.test(key) && validRecord(value));
 }
-
 export function alphaCapabilityFingerprint(config) {
-  const rawBaseURL = String(config.baseURL ?? '').replace(/\/+$/u, '')
-  let baseURL = rawBaseURL
-  try {
-    const url = new URL(rawBaseURL)
-    url.hash = ''
-    baseURL = url.toString().replace(/\/+$/u, '')
-  } catch {}
-  const canonical = {
-    baseURL,
-    provider: String(config.provider ?? ''),
-    model: String(config.model ?? ''),
-    profile: String(config.profile ?? ''),
-    group: String(config.group ?? ''),
-    schemaFingerprint: String(config.schemaFingerprint ?? ''),
-  }
-  return createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex')
+    const rawBaseURL = String(config.baseURL ?? "").replace(/\/+$/u, "");
+    let baseURL = rawBaseURL;
+    try {
+        const url = new URL(rawBaseURL);
+        url.hash = "";
+        baseURL = url.toString().replace(/\/+$/u, "");
+    }
+    catch { }
+    return createHash("sha256").update(JSON.stringify({
+        baseURL,
+        provider: String(config.provider ?? ""),
+        model: String(config.model ?? ""),
+        profile: String(config.profile ?? ""),
+        group: String(config.group ?? ""),
+        schemaFingerprint: String(config.schemaFingerprint ?? ""),
+    }), "utf8").digest("hex");
 }
-
 export function alphaCapabilityUsable(record) {
-  return record?.probeVersion === ALPHA_PROBE_VERSION && (record.classification === 'native' || record.classification === 'command-capable')
+    return validRecord(record) && record.probeVersion === ALPHA_PROBE_VERSION &&
+        (record.classification === "native" || record.classification === "command-capable");
+}
+export function alphaActionState(record, action) {
+    if (!validRecord(record) || typeof action !== "string" || !action)
+        return undefined;
+    const state = record.actions[action];
+    return isActionState(state) ? state : undefined;
+}
+export function assertAlphaActionAllowed(record, action) {
+    if (alphaActionState(record, action) === "unsupported") {
+        throw Object.assign(new Error(`Alpha action is unsupported for this verified route: ${String(action)}`), { code: "LCX_ALPHA_ACTION_UNSUPPORTED" });
+    }
+}
+export function alphaAdvertisedActions(record) {
+    if (!validRecord(record))
+        return [...ALPHA_ACTIONS];
+    return ALPHA_ACTIONS.filter((action) => record.actions[action] !== "unsupported");
+}
+export function alphaSearchParametersFor(record) {
+    return {
+        ...ALPHA_SEARCH_PARAMETERS,
+        properties: {
+            ...ALPHA_SEARCH_PARAMETERS.properties,
+            action: { type: "string", enum: alphaAdvertisedActions(record) },
+        },
+    };
 }
-
 export class AlphaCapabilityStore {
-  constructor(file) {
-    this.store = new JsonStore(
-      file,
-      () => ({ version: VERSION, capabilities: {} }),
-      validData,
-      'LCX_ALPHA_CAPABILITY_STORE_CORRUPT',
-    )
-  }
-
-  get(fingerprint) {
-    this.store.refresh()
-    const value = this.store.data.capabilities[fingerprint]
-    return value?.probeVersion === ALPHA_PROBE_VERSION ? structuredClone(value) : undefined
-  }
-
-  put(fingerprint, record) {
-    if (!/^[a-f0-9]{64}$/u.test(String(fingerprint)) || record?.probeVersion !== ALPHA_PROBE_VERSION || !validRecord(record)) {
-      const error = new Error('Invalid Alpha capability record')
-      error.code = 'LCX_ALPHA_CAPABILITY_INVALID'
-      throw error
+    store;
+    constructor(file) {
+        this.store = new JsonStore(file, () => ({ version: VERSION, capabilities: {} }), validData, "LCX_ALPHA_CAPABILITY_STORE_CORRUPT");
+    }
+    get(fingerprint) {
+        this.store.refresh();
+        const value = this.store.data.capabilities[fingerprint];
+        return value?.probeVersion === ALPHA_PROBE_VERSION ? structuredClone(value) : undefined;
+    }
+    put(fingerprint, record) {
+        if (typeof fingerprint !== "string" || !/^[a-f0-9]{64}$/u.test(fingerprint) || !validRecord(record) || record.probeVersion !== ALPHA_PROBE_VERSION) {
+            throw Object.assign(new Error("Invalid Alpha capability record"), { code: "LCX_ALPHA_CAPABILITY_INVALID" });
+        }
+        this.store.update((current) => ({
+            version: VERSION,
+            capabilities: { ...current.capabilities, [fingerprint]: structuredClone(record) },
+        }));
     }
-    this.store.update((current) => ({
-      version: VERSION,
-      capabilities: { ...current.capabilities, [fingerprint]: structuredClone(record) },
-    }))
-  }
 }

package/lib/web-search-hosted.js

@@ -1,33 +1,321 @@
-import { outputDomains, outputLineRange, parseWebRunOutput } from './web-run-output.js'
-
-export const HOSTED_SEARCH_PARAMETERS = {
-  type: 'object',
-  properties: {
-    query: { type: 'string', description: 'Advanced Responses Hosted Web Search query. Use DSH web_search for ordinary searches.' },
-    searchContextSize: { type: 'string', enum: ['low', 'medium', 'high'] },
-    allowedDomains: { type: 'array', items: { type: 'string' } },
-    blockedDomains: { type: 'array', items: { type: 'string' } },
-    userLocation: { type: 'object', properties: { country: { type: 'string' }, city: { type: 'string' }, region: { type: 'string' }, timezone: { type: 'string' } }, additionalProperties: false },
-    externalWebAccess: { type: 'boolean' },
-    returnTokenBudget: { type: 'string', enum: ['default', 'unlimited'] },
-    searchContentTypes: { type: 'array', items: { type: 'string', enum: ['text', 'image'] } },
-    imageSettings: { type: 'object', properties: { maxResults: { type: 'integer' }, caption: { type: 'boolean' } }, additionalProperties: false },
-  },
-  required: ['query'], additionalProperties: false,
-}
-export const HOSTED_SEARCH_OUTPUT = { type: 'object', properties: { mode: { type: 'string', enum: ['hosted'] }, action: { type: 'string' }, emulation: { type: 'string', enum: ['native'] }, content: { type: 'string' }, sources: { type: 'array', items: { type: 'object' } }, citations: { type: 'array', items: { type: 'object' } }, images: { type: 'array', items: { type: 'object' } }, warnings: { type: 'array', items: { type: 'string' } }, outputBlocks: { type: 'array', items: { type: 'object' } }, domains: { type: 'array', items: { type: 'string' } }, lineRange: { type: 'object' }, requestId: { type: 'string' }, responseId: { type: 'string' }, retrievedAt: { type: 'string' }, truncated: { type: 'boolean' } }, required: ['mode','action','emulation','content','sources','citations','images','warnings','requestId','retrievedAt','truncated'], additionalProperties: false }
-function failure(message, code = 'WEB_INVALID_REQUEST') { const e = new Error(message); e.code = code; return e }
-function isRecord(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
-function normalizeDomains(value, field) { if (value === undefined) return undefined; if (!Array.isArray(value) || value.length < 1 || value.length > 100) throw failure(`websearch_gpt_advanced.${field} must contain 1 to 100 domains`); const result = value.map((item) => { if (typeof item !== 'string') throw failure(`websearch_gpt_advanced.${field} contains an invalid domain`); const domain = item.trim().toLowerCase(); if (!domain || domain.length > 253 || domain.includes('/') || domain.includes(':') || domain.endsWith('.') || domain.split('.').length < 2) throw failure(`websearch_gpt_advanced.${field} contains an invalid domain`); return domain }); if (new Set(result).size !== result.length) throw failure(`websearch_gpt_advanced.${field} contains duplicates`); return result }
-function normalizeLocation(value) { if (!isRecord(value)) throw failure('websearch_gpt_advanced.userLocation must be an object'); const result = {}; if (value.country !== undefined) { if (typeof value.country !== 'string' || !/^[a-z]{2}$/iu.test(value.country.trim())) throw failure('userLocation.country must be ISO alpha-2'); result.country = value.country.trim().toUpperCase() } for (const field of ['city','region']) if (value[field] !== undefined) { if (typeof value[field] !== 'string' || !value[field].trim() || value[field].length > 200) throw failure(`userLocation.${field} is invalid`); result[field] = value[field].trim() } if (value.timezone !== undefined) { try { new Intl.DateTimeFormat('en-US', { timeZone: value.timezone }).format() } catch { throw failure('userLocation.timezone must be an IANA timezone') }; result.timezone = value.timezone } if (!Object.keys(result).length) throw failure('userLocation is empty'); return result }
-export function normalizeHostedSearchArgs(args) { if (!isRecord(args) || typeof args.query !== 'string' || !args.query.trim()) throw failure('websearch_gpt_advanced.query must be non-empty'); const query = args.query.trim(); if (query.length > 16_000) throw failure('query is too long'); const result = { query }; if (args.searchContextSize !== undefined) { if (!['low','medium','high'].includes(args.searchContextSize)) throw failure('searchContextSize is invalid'); result.searchContextSize = args.searchContextSize } const allowedDomains = normalizeDomains(args.allowedDomains, 'allowedDomains'); const blockedDomains = normalizeDomains(args.blockedDomains, 'blockedDomains'); if (allowedDomains) result.allowedDomains = allowedDomains; if (blockedDomains) result.blockedDomains = blockedDomains; if (allowedDomains && blockedDomains && allowedDomains.some((d) => new Set(blockedDomains).has(d))) throw failure('domain filters conflict'); if (args.userLocation !== undefined) result.userLocation = normalizeLocation(args.userLocation); if (args.externalWebAccess !== undefined) { if (typeof args.externalWebAccess !== 'boolean') throw failure('externalWebAccess must be boolean'); result.externalWebAccess = args.externalWebAccess } if (args.returnTokenBudget !== undefined) { if (!['default','unlimited'].includes(args.returnTokenBudget)) throw failure('returnTokenBudget is invalid'); result.returnTokenBudget = args.returnTokenBudget } if (args.searchContentTypes !== undefined) { if (!Array.isArray(args.searchContentTypes) || !args.searchContentTypes.length || args.searchContentTypes.length > 2 || args.searchContentTypes.some((v) => !['text','image'].includes(v))) throw failure('searchContentTypes is invalid'); result.searchContentTypes = [...new Set(args.searchContentTypes)] } if (args.imageSettings !== undefined) { if (!result.searchContentTypes?.includes('image') || !isRecord(args.imageSettings)) throw failure('imageSettings requires image search'); result.imageSettings = {}; if (args.imageSettings.maxResults !== undefined) { if (!Number.isInteger(args.imageSettings.maxResults) || args.imageSettings.maxResults < 1 || args.imageSettings.maxResults > 100) throw failure('imageSettings.maxResults is invalid'); result.imageSettings.maxResults = args.imageSettings.maxResults } if (args.imageSettings.caption !== undefined) { if (typeof args.imageSettings.caption !== 'boolean') throw failure('imageSettings.caption must be boolean'); result.imageSettings.caption = args.imageSettings.caption } } return result }
-export function buildHostedSearchBody(args, model, options = {}) { const tool = { type: 'web_search', ...(args.searchContextSize ? { search_context_size: args.searchContextSize } : {}), ...(args.allowedDomains || args.blockedDomains ? { filters: { ...(args.allowedDomains ? { allowed_domains: args.allowedDomains } : {}), ...(args.blockedDomains ? { blocked_domains: args.blockedDomains } : {}) } } : {}), ...(args.userLocation ? { user_location: { type: 'approximate', ...args.userLocation } } : {}), ...(args.externalWebAccess !== undefined ? { external_web_access: args.externalWebAccess } : {}), ...(args.returnTokenBudget ? { return_token_budget: args.returnTokenBudget } : {}), ...(args.searchContentTypes ? { search_content_types: args.searchContentTypes } : {}), ...(args.imageSettings ? { image_settings: { ...(args.imageSettings.maxResults !== undefined ? { max_results: args.imageSettings.maxResults } : {}), ...(args.imageSettings.caption !== undefined ? { caption: args.imageSettings.caption } : {}) } } : {}) }; return { model, input: [{ role: 'user', content: [{ type: 'input_text', text: args.query }] }], tools: [tool], tool_choice: 'required', include: ['web_search_call.action.sources', ...(args.searchContentTypes?.includes('image') ? ['web_search_call.results'] : [])], stream: false, store: false, ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}) } }
-function textFrom(value, seen = new Set()) { if (typeof value === 'string') return value; if (!value || typeof value !== 'object' || seen.has(value)) return ''; seen.add(value); if (Array.isArray(value)) return value.map((item) => textFrom(item, seen)).filter(Boolean).join('\n'); if (typeof value.text === 'string' && ['output_text','text','input_text'].includes(value.type)) return value.text; if (Array.isArray(value.content)) return textFrom(value.content, seen); return '' }
-function httpUrl(value) { try { const url = new URL(value); return ['http:','https:'].includes(url.protocol) ? url : undefined } catch { return undefined } }
-function sourceFrom(value) { if (!isRecord(value) || !httpUrl(value.url)) return undefined; return { url: httpUrl(value.url).toString(), ...(typeof value.title === 'string' && value.title ? { title: value.title } : {}), ...(typeof value.snippet === 'string' && value.snippet ? { snippet: value.snippet } : {}), ...(typeof value.publishedAt === 'string' ? { publishedAt: value.publishedAt } : typeof value.published_at === 'string' ? { publishedAt: value.published_at } : {}), ...(typeof value.ref_id === 'string' ? { refId: value.ref_id } : {}) } }
-function imageFrom(value) { if (!isRecord(value) || value.type !== 'image_result' || !httpUrl(value.image_url)) return undefined; return { imageUrl: httpUrl(value.image_url).toString(), ...(httpUrl(value.thumbnail_url) ? { thumbnailUrl: httpUrl(value.thumbnail_url).toString() } : {}), ...(httpUrl(value.source_website_url) ? { sourceWebsiteUrl: httpUrl(value.source_website_url).toString() } : {}), ...(typeof value.caption === 'string' ? { caption: value.caption } : {}) } }
-function responseArtifacts(response) { const sources = [], citations = [], images = [], actions = []; for (const item of Array.isArray(response?.output) ? response.output : []) { if (item?.type === 'web_search_call') { actions.push(typeof item.action?.type === 'string' ? item.action.type : 'search'); for (const value of item.action?.sources ?? []) { const source = sourceFrom(value); if (source) sources.push(source) } for (const value of item.results ?? []) { const image = imageFrom(value); if (image) images.push(image) } } if (item?.type === 'message') for (const part of item.content ?? []) if (part?.type === 'output_text') for (const annotation of part.annotations ?? []) if (annotation?.type === 'url_citation') { const source = sourceFrom(annotation); if (source) { citations.push(source); sources.push(source) } } } return { sources, citations, images, actions } }
-function canonicalUrl(value) { const url = httpUrl(value); if (!url) return undefined; url.hash = ''; for (const key of [...url.searchParams.keys()]) if (/^(utm_|gclid$|fbclid$)/iu.test(key)) url.searchParams.delete(key); return url.toString() }
-function uniqueByUrl(values) { const result = [], seen = new Set(); for (const value of values) { const key = canonicalUrl(value.url); if (!key || seen.has(key)) continue; seen.add(key); result.push(value) } return result }
-export function parseHostedSearchResponse(response, requestId, maxResults = 8, retrievedAt = new Date().toISOString()) { if (response?.error) throw failure(response.error.message ?? 'Hosted Web Search failed', 'LCX_WEB_PROVIDER_ERROR'); if (response?.status !== 'completed') throw failure(`Hosted Web Search status: ${String(response?.status ?? 'missing')}`, 'WEB_RESPONSE_INCOMPLETE'); const output = typeof response.output_text === 'string' ? response.output_text : textFrom(response?.output ?? response?.content); const outputBlocks = parseWebRunOutput(output); const artifacts = responseArtifacts(response); if (!artifacts.actions.length) throw failure('Hosted Web Search completed without web_search', 'WEB_SEARCH_NOT_EXECUTED'); const allSources = [...artifacts.sources, ...outputBlocks.flatMap((block) => block.url ? [{ url: block.url, ...(block.title ? { title: block.title } : {}) }] : [])]; const sources = uniqueByUrl(allSources); const citations = uniqueByUrl(artifacts.citations); const limited = sources.slice(0, Math.max(1, maxResults)); const images = artifacts.images.slice(0, Math.max(1, maxResults)); if (!output && !limited.length && !images.length) throw failure('Hosted Web Search returned no output', 'WEB_NO_SOURCES'); return { mode: 'hosted', action: artifacts.actions[0], emulation: 'native', content: output, sources: limited, citations, images, warnings: artifacts.actions.length > 1 ? [`Multiple hosted search actions were returned: ${artifacts.actions.join(', ')}`] : [], outputBlocks, domains: outputDomains(outputBlocks), ...(outputLineRange(outputBlocks) ? { lineRange: outputLineRange(outputBlocks) } : {}), requestId, ...(typeof response.id === 'string' ? { responseId: response.id } : {}), retrievedAt, truncated: sources.length > limited.length || artifacts.images.length > images.length } }
-export function renderHostedSearchResult(value) { const parts = []; if (value.content) parts.push(value.content); if (value.sources?.length) parts.push(`来源：\n${value.sources.map((s) => `- [${s.title ?? s.url}](${s.url})${s.snippet ? ` — ${s.snippet}` : ''}`).join('\n')}`); if (value.images?.length) parts.push(`图片：\n${value.images.map((i) => `- [${i.caption ?? i.imageUrl}](${i.imageUrl})`).join('\n')}`); if (value.warnings?.length) parts.push(value.warnings.map((w) => `警告：${w}`).join('\n')); parts.push(`检索时间：${value.retrievedAt}`); return [{ type: 'text', text: parts.filter(Boolean).join('\n\n') }] }
+import { outputDomains, outputLineRange, parseWebRunOutput } from "./web-run-output.js";
+export const HOSTED_SEARCH_PARAMETERS = { type: "object", properties: { query: { type: "string", description: "Advanced Responses Hosted Web Search query. Use DSH web_search for ordinary searches." }, searchContextSize: { type: "string", enum: ["low", "medium", "high"] }, allowedDomains: { type: "array", items: { type: "string" } }, blockedDomains: { type: "array", items: { type: "string" } }, userLocation: { type: "object", properties: { country: { type: "string" }, city: { type: "string" }, region: { type: "string" }, timezone: { type: "string" } }, additionalProperties: false }, externalWebAccess: { type: "boolean" }, returnTokenBudget: { type: "string", enum: ["default", "unlimited"] }, searchContentTypes: { type: "array", items: { type: "string", enum: ["text", "image"] } }, imageSettings: { type: "object", properties: { maxResults: { type: "integer" }, caption: { type: "boolean" } }, additionalProperties: false } }, required: ["query"], additionalProperties: false };
+export const HOSTED_SEARCH_OUTPUT = { type: "object", properties: { mode: { type: "string", enum: ["hosted"] }, action: { type: "string" }, emulation: { type: "string", enum: ["native"] }, content: { type: "string" }, sources: { type: "array", items: { type: "object" } }, citations: { type: "array", items: { type: "object" } }, images: { type: "array", items: { type: "object" } }, warnings: { type: "array", items: { type: "string" } }, outputBlocks: { type: "array", items: { type: "object" } }, domains: { type: "array", items: { type: "string" } }, lineRange: { type: "object" }, requestId: { type: "string" }, responseId: { type: "string" }, retrievedAt: { type: "string" }, truncated: { type: "boolean" }, usage: { type: "object", properties: { inputTokens: { type: "number" }, outputTokens: { type: "number" }, totalTokens: { type: "number" }, cachedInputTokens: { type: "number" }, actionCount: { type: "number" }, serverWebSearchCalls: { type: "number" } }, additionalProperties: false } }, required: ["mode", "action", "emulation", "content", "sources", "citations", "images", "warnings", "requestId", "retrievedAt", "truncated"], additionalProperties: false };
+function failure(message, code = "WEB_INVALID_REQUEST") { return Object.assign(new Error(message), { code }); }
+function isRecord(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function isStringArray(value) { return Array.isArray(value) && value.every((item) => typeof item === "string"); }
+function isInteger(value) { return typeof value === "number" && Number.isInteger(value); }
+function httpUrl(value) { if (typeof value !== "string")
+    return undefined; try {
+    const url = new URL(value);
+    return ["http:", "https:"].includes(url.protocol) ? url : undefined;
+}
+catch {
+    return undefined;
+} }
+function normalizeDomains(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!isStringArray(value) || value.length < 1 || value.length > 100)
+        throw failure(`websearch_gpt_advanced.${field} must contain 1 to 100 domains`);
+    const result = value.map((item) => {
+        const domain = item.trim().toLowerCase();
+        if (!domain || domain.length > 253 || domain.includes("/") || domain.includes(":") || domain.endsWith(".") || domain.split(".").length < 2)
+            throw failure(`websearch_gpt_advanced.${field} contains an invalid domain`);
+        return domain;
+    });
+    if (new Set(result).size !== result.length)
+        throw failure(`websearch_gpt_advanced.${field} contains duplicates`);
+    return result;
+}
+function normalizeLocation(value) {
+    if (!isRecord(value))
+        throw failure("websearch_gpt_advanced.userLocation must be an object");
+    const result = {};
+    if (value.country !== undefined) {
+        if (typeof value.country !== "string" || !/^[a-z]{2}$/iu.test(value.country.trim()))
+            throw failure("userLocation.country must be ISO alpha-2");
+        result.country = value.country.trim().toUpperCase();
+    }
+    for (const field of ["city", "region"])
+        if (value[field] !== undefined) {
+            const text = value[field];
+            if (typeof text !== "string" || !text.trim() || text.length > 200)
+                throw failure(`userLocation.${field} is invalid`);
+            result[field] = text.trim();
+        }
+    if (value.timezone !== undefined) {
+        if (typeof value.timezone !== "string")
+            throw failure("userLocation.timezone must be an IANA timezone");
+        try {
+            new Intl.DateTimeFormat("en-US", { timeZone: value.timezone }).format();
+        }
+        catch {
+            throw failure("userLocation.timezone must be an IANA timezone");
+        }
+        result.timezone = value.timezone;
+    }
+    if (!Object.keys(result).length)
+        throw failure("userLocation is empty");
+    return result;
+}
+export function normalizeHostedSearchArgs(args) {
+    if (!isRecord(args) || typeof args.query !== "string" || !args.query.trim())
+        throw failure("websearch_gpt_advanced.query must be non-empty");
+    const query = args.query.trim();
+    if (query.length > 16_000)
+        throw failure("query is too long");
+    const result = { query };
+    if (args.searchContextSize !== undefined) {
+        if (!["low", "medium", "high"].includes(String(args.searchContextSize)))
+            throw failure("searchContextSize is invalid");
+        result.searchContextSize = args.searchContextSize;
+    }
+    const allowedDomains = normalizeDomains(args.allowedDomains, "allowedDomains");
+    const blockedDomains = normalizeDomains(args.blockedDomains, "blockedDomains");
+    if (allowedDomains)
+        result.allowedDomains = allowedDomains;
+    if (blockedDomains)
+        result.blockedDomains = blockedDomains;
+    if (allowedDomains && blockedDomains && allowedDomains.some((domain) => blockedDomains.includes(domain)))
+        throw failure("domain filters conflict");
+    if (args.userLocation !== undefined)
+        result.userLocation = normalizeLocation(args.userLocation);
+    if (args.externalWebAccess !== undefined) {
+        if (typeof args.externalWebAccess !== "boolean")
+            throw failure("externalWebAccess must be boolean");
+        result.externalWebAccess = args.externalWebAccess;
+    }
+    if (args.returnTokenBudget !== undefined) {
+        if (args.returnTokenBudget !== "default" && args.returnTokenBudget !== "unlimited")
+            throw failure("returnTokenBudget is invalid");
+        result.returnTokenBudget = args.returnTokenBudget;
+    }
+    if (args.searchContentTypes !== undefined) {
+        if (!isStringArray(args.searchContentTypes) || !args.searchContentTypes.length || args.searchContentTypes.length > 2 || args.searchContentTypes.some((value) => value !== "text" && value !== "image"))
+            throw failure("searchContentTypes is invalid");
+        result.searchContentTypes = [...new Set(args.searchContentTypes)];
+    }
+    if (args.imageSettings !== undefined) {
+        if (!result.searchContentTypes?.includes("image") || !isRecord(args.imageSettings))
+            throw failure("imageSettings requires image search");
+        const imageSettings = {};
+        if (args.imageSettings.maxResults !== undefined) {
+            const maxResults = args.imageSettings.maxResults;
+            if (!isInteger(maxResults) || maxResults < 1 || maxResults > 100)
+                throw failure("imageSettings.maxResults is invalid");
+            imageSettings.maxResults = maxResults;
+        }
+        if (args.imageSettings.caption !== undefined) {
+            if (typeof args.imageSettings.caption !== "boolean")
+                throw failure("imageSettings.caption must be boolean");
+            imageSettings.caption = args.imageSettings.caption;
+        }
+        result.imageSettings = imageSettings;
+    }
+    return result;
+}
+export function buildHostedSearchBody(args, model, options = {}) {
+    const tool = { type: "web_search", ...(args.searchContextSize ? { search_context_size: args.searchContextSize } : {}), ...(args.allowedDomains || args.blockedDomains ? { filters: { ...(args.allowedDomains ? { allowed_domains: args.allowedDomains } : {}), ...(args.blockedDomains ? { blocked_domains: args.blockedDomains } : {}) } } : {}), ...(args.userLocation ? { user_location: { type: "approximate", ...args.userLocation } } : {}), ...(args.externalWebAccess !== undefined ? { external_web_access: args.externalWebAccess } : {}), ...(args.returnTokenBudget ? { return_token_budget: args.returnTokenBudget } : {}), ...(args.searchContentTypes ? { search_content_types: args.searchContentTypes } : {}), ...(args.imageSettings ? { image_settings: { ...(args.imageSettings.maxResults !== undefined ? { max_results: args.imageSettings.maxResults } : {}), ...(args.imageSettings.caption !== undefined ? { caption: args.imageSettings.caption } : {}) } } : {}) };
+    return { model, input: [{ role: "user", content: [{ type: "input_text", text: args.query }] }], tools: [tool], tool_choice: "required", include: ["web_search_call.action.sources", ...(args.searchContentTypes?.includes("image") ? ["web_search_call.results"] : [])], stream: false, store: false, ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}) };
+}
+function textFrom(value, seen = new Set()) {
+    if (typeof value === "string")
+        return value;
+    if (!value || typeof value !== "object" || seen.has(value))
+        return "";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => textFrom(item, seen)).filter(Boolean).join("\n");
+    if (!isRecord(value))
+        return "";
+    if (typeof value.text === "string" && ["output_text", "text", "input_text"].includes(value.type))
+        return value.text;
+    return Array.isArray(value.content) ? textFrom(value.content, seen) : "";
+}
+function sourceFrom(value) { if (!isRecord(value))
+    return undefined; const url = httpUrl(value.url); if (!url)
+    return undefined; return { url: url.toString(), ...(typeof value.title === "string" && value.title ? { title: value.title } : {}), ...(typeof value.snippet === "string" && value.snippet ? { snippet: value.snippet } : {}), ...(typeof value.publishedAt === "string" ? { publishedAt: value.publishedAt } : typeof value.published_at === "string" ? { publishedAt: value.published_at } : {}), ...(typeof value.ref_id === "string" ? { refId: value.ref_id } : {}) }; }
+function imageFrom(value) { if (!isRecord(value) || value.type !== "image_result")
+    return undefined; const imageUrl = httpUrl(value.image_url); if (!imageUrl)
+    return undefined; const thumbnailUrl = httpUrl(value.thumbnail_url); const sourceWebsiteUrl = httpUrl(value.source_website_url); return { imageUrl: imageUrl.toString(), ...(thumbnailUrl ? { thumbnailUrl: thumbnailUrl.toString() } : {}), ...(sourceWebsiteUrl ? { sourceWebsiteUrl: sourceWebsiteUrl.toString() } : {}), ...(typeof value.caption === "string" ? { caption: value.caption } : {}) }; }
+function responseArtifacts(response) { const sources = []; const citations = []; const images = []; const actions = []; if (!isRecord(response) || !Array.isArray(response.output))
+    return { sources, citations, images, actions }; for (const item of response.output) {
+    if (!isRecord(item))
+        continue;
+    if (item.type === "web_search_call") {
+        const action = isRecord(item.action) && typeof item.action.type === "string" ? item.action.type : "search";
+        actions.push(action);
+        if (isRecord(item.action) && Array.isArray(item.action.sources))
+            for (const value of item.action.sources) {
+                const source = sourceFrom(value);
+                if (source)
+                    sources.push(source);
+            }
+        if (Array.isArray(item.results))
+            for (const value of item.results) {
+                const image = imageFrom(value);
+                if (image)
+                    images.push(image);
+            }
+    }
+    if (item.type === "message" && Array.isArray(item.content))
+        for (const part of item.content)
+            if (isRecord(part) && part.type === "output_text" && Array.isArray(part.annotations))
+                for (const annotation of part.annotations)
+                    if (isRecord(annotation) && annotation.type === "url_citation") {
+                        const source = sourceFrom(annotation);
+                        if (source) {
+                            citations.push(source);
+                            sources.push(source);
+                        }
+                    }
+} return { sources, citations, images, actions }; }
+function canonicalUrl(value) { const url = httpUrl(value); if (!url)
+    return undefined; url.hash = ""; for (const key of [...url.searchParams.keys()])
+    if (/^(utm_|gclid$|fbclid$)/iu.test(key))
+        url.searchParams.delete(key); return url.toString(); }
+function uniqueByUrl(values) { const result = []; const seen = new Set(); for (const value of values) {
+    const key = canonicalUrl(value.url);
+    if (!key || seen.has(key))
+        continue;
+    seen.add(key);
+    result.push(value);
+} return result; }
+function nonNegativeInt(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function hostedUsageFrom(response, actionCount) {
+    const usage = isRecord(response) && isRecord(response.usage) ? response.usage : undefined;
+    const inputDetails = usage && isRecord(usage.input_tokens_details)
+        ? usage.input_tokens_details
+        : usage && isRecord(usage.prompt_tokens_details)
+            ? usage.prompt_tokens_details
+            : undefined;
+    const serverDetails = usage && isRecord(usage.server_side_tool_usage_details)
+        ? usage.server_side_tool_usage_details
+        : undefined;
+    const result = {};
+    const inputTokens = usage ? nonNegativeInt(usage.input_tokens ?? usage.prompt_tokens) : undefined;
+    const outputTokens = usage ? nonNegativeInt(usage.output_tokens ?? usage.completion_tokens) : undefined;
+    const totalTokens = usage ? nonNegativeInt(usage.total_tokens) : undefined;
+    const cachedInputTokens = inputDetails ? nonNegativeInt(inputDetails.cached_tokens) : undefined;
+    const serverWebSearchCalls = serverDetails ? nonNegativeInt(serverDetails.web_search_calls) : undefined;
+    if (inputTokens !== undefined)
+        result.inputTokens = inputTokens;
+    if (outputTokens !== undefined)
+        result.outputTokens = outputTokens;
+    if (totalTokens !== undefined)
+        result.totalTokens = totalTokens;
+    // cachedInputTokens is a subset of inputTokens (cache hits), not an extra addend.
+    if (cachedInputTokens !== undefined)
+        result.cachedInputTokens = cachedInputTokens;
+    if (actionCount > 0)
+        result.actionCount = actionCount;
+    if (serverWebSearchCalls !== undefined)
+        result.serverWebSearchCalls = serverWebSearchCalls;
+    return Object.keys(result).length ? result : undefined;
+}
+function sourceLine(source) {
+    return `- [${String(source.title ?? source.url ?? "")}](${String(source.url ?? "")})${source.snippet ? ` — ${String(source.snippet)}` : ""}`;
+}
+function usageLine(usage) {
+    const parts = [];
+    if (usage.inputTokens !== undefined)
+        parts.push(`input=${String(usage.inputTokens)}`);
+    if (usage.outputTokens !== undefined)
+        parts.push(`output=${String(usage.outputTokens)}`);
+    if (usage.totalTokens !== undefined)
+        parts.push(`total=${String(usage.totalTokens)}`);
+    if (usage.cachedInputTokens !== undefined)
+        parts.push(`cachedInput=${String(usage.cachedInputTokens)}`);
+    if (usage.actionCount !== undefined)
+        parts.push(`actionCount=${String(usage.actionCount)}`);
+    if (usage.serverWebSearchCalls !== undefined)
+        parts.push(`serverWebSearchCalls=${String(usage.serverWebSearchCalls)}`);
+    return parts.length ? `用量：${parts.join(" ")}` : "";
+}
+export function parseHostedSearchResponse(response, requestId, maxResults = 8, retrievedAt = new Date().toISOString()) {
+    if (!isRecord(response))
+        throw failure("Hosted Web Search returned an invalid response", "WEB_RESPONSE_INCOMPLETE");
+    if (isRecord(response.error))
+        throw failure(typeof response.error.message === "string" ? response.error.message : "Hosted Web Search failed", "LCX_WEB_PROVIDER_ERROR");
+    if (response.status !== "completed")
+        throw failure(`Hosted Web Search status: ${String(response.status ?? "missing")}`, "WEB_RESPONSE_INCOMPLETE");
+    if (Array.isArray(response.output) && response.output.some(item => isRecord(item) && item.type === "web_search_call" && item.status !== undefined && item.status !== "completed"))
+        throw failure("Hosted Web Search did not complete its search action", "LCX_WEB_PROVIDER_ERROR");
+    const output = typeof response.output_text === "string" ? response.output_text : textFrom(response.output ?? response.content);
+    const outputBlocks = parseWebRunOutput(output);
+    const artifacts = responseArtifacts(response);
+    if (!artifacts.actions.length)
+        throw failure("Hosted Web Search completed without web_search", "WEB_SEARCH_NOT_EXECUTED");
+    const citations = uniqueByUrl(artifacts.citations);
+    const discovered = uniqueByUrl([...artifacts.sources, ...outputBlocks.flatMap((block) => block.url ? [{ url: block.url, ...(block.title ? { title: block.title } : {}) }] : [])]);
+    const ranked = uniqueByUrl([...citations, ...discovered]);
+    const limited = ranked.slice(0, Math.max(1, maxResults));
+    const images = artifacts.images.slice(0, Math.max(1, maxResults));
+    const usage = hostedUsageFrom(response, artifacts.actions.length);
+    if (!output && !limited.length && !images.length)
+        throw failure("Hosted Web Search returned no output", "WEB_NO_SOURCES");
+    return { mode: "hosted", action: artifacts.actions[0], emulation: "native", content: output, sources: limited, citations, images, warnings: artifacts.actions.length > 1 ? [`Multiple hosted search actions were returned: ${artifacts.actions.join(", ")}`] : [], outputBlocks, domains: outputDomains(outputBlocks), ...(outputLineRange(outputBlocks) ? { lineRange: outputLineRange(outputBlocks) } : {}), requestId, ...(typeof response.id === "string" ? { responseId: response.id } : {}), retrievedAt, truncated: ranked.length > limited.length || artifacts.images.length > images.length, ...(usage ? { usage } : {}) };
+}
+/** Project Hosted image results into LCX-owned, tool-private, replayable UI metadata. */
+export function hostedMediaPresentationMeta(value, tool, base = {}) {
+    const inherited = base !== null && typeof base === "object" && !Array.isArray(base) ? base : {};
+    if (!isRecord(value) || !Array.isArray(value.images))
+        return inherited;
+    const candidates = value.images.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const imageUrl = httpUrl(entry.imageUrl);
+        if (!imageUrl)
+            return [];
+        const previewUrl = httpUrl(entry.thumbnailUrl);
+        const sourceUrl = httpUrl(entry.sourceWebsiteUrl);
+        return [{
+                kind: "image",
+                url: imageUrl.toString(),
+                ...(previewUrl ? { previewUrl: previewUrl.toString() } : {}),
+                ...(sourceUrl ? { sourceUrl: sourceUrl.toString() } : {}),
+                ...(typeof entry.caption === "string" && entry.caption ? { caption: entry.caption } : {}),
+                structured: true,
+            }];
+    });
+    return candidates.length
+        ? { ...inherited, lcxHostedMedia: { version: 1, tool, candidates } }
+        : inherited;
+}
+export function renderHostedSearchResult(value) {
+    const data = isRecord(value) ? value : {};
+    const parts = [];
+    if (typeof data.content === "string" && data.content)
+        parts.push(data.content);
+    const citations = Array.isArray(data.citations) ? data.citations.filter(isRecord) : [];
+    const citationUrls = new Set(citations.map((source) => String(source.url ?? "")).filter(Boolean));
+    if (citations.length)
+        parts.push(`引用：\n${citations.map(sourceLine).join("\n")}`);
+    const extraSources = Array.isArray(data.sources)
+        ? data.sources.filter(isRecord).filter((source) => !citationUrls.has(String(source.url ?? "")))
+        : [];
+    if (extraSources.length)
+        parts.push(`来源：\n${extraSources.map(sourceLine).join("\n")}`);
+    if (Array.isArray(data.images) && data.images.length) {
+        parts.push(`图片：\n${data.images.filter(isRecord).map((image) => {
+            const caption = String(image.caption ?? image.imageUrl ?? "");
+            const imageUrl = String(image.imageUrl ?? "");
+            const sourcePage = typeof image.sourceWebsiteUrl === "string" && image.sourceWebsiteUrl
+                ? ` 来源页: ${image.sourceWebsiteUrl}`
+                : "";
+            return `- [${caption}](${imageUrl})${sourcePage}`;
+        }).join("\n")}`);
+    }
+    if (Array.isArray(data.warnings) && data.warnings.length)
+        parts.push(data.warnings.map((warning) => `警告：${String(warning)}`).join("\n"));
+    if (isRecord(data.usage)) {
+        const renderedUsage = usageLine(data.usage);
+        if (renderedUsage)
+            parts.push(renderedUsage);
+    }
+    parts.push(`检索时间：${String(data.retrievedAt ?? "")}`);
+    return [{ type: "text", text: parts.filter(Boolean).join("\n\n") }];
+}