@full-self-developing/fsd 1.0.0

package/extensions/google/src/gemini-web-search-provider.runtime.ts

@@ -0,0 +1,367 @@
+import {
+  createProviderHttpError,
+  formatProviderHttpErrorMessage,
+  readProviderJsonObjectResponse,
+} from "openclaw/plugin-sdk/provider-http";
+import {
+  buildSearchCacheKey,
+  buildUnsupportedSearchFilterResponse,
+  DEFAULT_SEARCH_COUNT,
+  normalizeFreshness,
+  parseIsoDateRange,
+  readCachedSearchPayload,
+  readConfiguredSecretString,
+  readNumberParam,
+  readProviderEnvValue,
+  readStringParam,
+  resolveCitationRedirectUrl,
+  resolveSearchCacheTtlMs,
+  resolveSearchCount,
+  resolveSearchTimeoutSeconds,
+  type SearchConfigRecord,
+  withTrustedWebSearchEndpoint,
+  wrapWebContent,
+  writeCachedSearchPayload,
+} from "openclaw/plugin-sdk/provider-web-search";
+import {
+  resolveGeminiConfig,
+  resolveGeminiBaseUrl,
+  resolveGeminiModel,
+  type GeminiConfig,
+} from "./gemini-web-search-provider.shared.js";
+
+type GeminiFreshness = "day" | "week" | "month" | "year";
+
+type GeminiTimeRangeFilter = {
+  startTime: string;
+  endTime: string;
+};
+
+type GeminiGroundingResponse = {
+  candidates?: Array<{
+    content?: {
+      parts?: Array<{
+        text?: string;
+      }>;
+    };
+    groundingMetadata?: {
+      groundingChunks?: Array<{
+        web?: {
+          uri?: string;
+          title?: string;
+        };
+      }>;
+    };
+  }>;
+  error?: {
+    code?: number;
+    message?: string;
+    status?: string;
+  };
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function throwMalformedGeminiResponse(): never {
+  throw new Error("Gemini API error: malformed JSON response");
+}
+
+const GEMINI_FRESHNESS_DAYS: Record<GeminiFreshness, number> = {
+  day: 1,
+  week: 7,
+  month: 30,
+  year: 365,
+};
+
+// Gemini's google_search.time_range_filter accepts second-precision RFC 3339
+// only. Despite the underlying google.protobuf.Timestamp type accepting "0, 3,
+// 6 or 9 fractional digits", the Search grounding endpoint rejects any
+// non-zero fractional component with
+//   "[FIELD_INVALID] Granularity of nano is not supported".
+// Strip the fractional-second component before serializing.
+function toGeminiTimeRangeTimestamp(date: Date): string {
+  return date.toISOString().replace(/\.\d+Z$/, "Z");
+}
+
+function isoDateStart(value: string): string {
+  return `${value}T00:00:00Z`;
+}
+
+function isoDateExclusiveEnd(value: string): string {
+  const end = new Date(`${value}T00:00:00Z`);
+  end.setUTCDate(end.getUTCDate() + 1);
+  return toGeminiTimeRangeTimestamp(end);
+}
+
+function freshnessStartTime(freshness: GeminiFreshness, now: Date): string {
+  const start = new Date(now);
+  start.setUTCDate(start.getUTCDate() - GEMINI_FRESHNESS_DAYS[freshness]);
+  return toGeminiTimeRangeTimestamp(start);
+}
+
+function resolveGeminiTimeRangeFilter(
+  args: Record<string, unknown>,
+  now = new Date(),
+):
+  | { timeRangeFilter?: GeminiTimeRangeFilter }
+  | {
+      error:
+        | "invalid_freshness"
+        | "invalid_date"
+        | "invalid_date_range"
+        | "conflicting_time_filters";
+      message: string;
+      docs: string;
+    } {
+  const rawFreshness = readStringParam(args, "freshness");
+  const freshness = rawFreshness
+    ? (normalizeFreshness(rawFreshness, "perplexity") as GeminiFreshness | undefined)
+    : undefined;
+  if (rawFreshness && !freshness) {
+    return {
+      error: "invalid_freshness",
+      message: "freshness must be day, week, month, year, or the shortcuts pd, pw, pm, py.",
+      docs: "https://docs.openclaw.ai/tools/web",
+    };
+  }
+
+  const rawDateAfter = readStringParam(args, "date_after");
+  const rawDateBefore = readStringParam(args, "date_before");
+  if (rawFreshness && (rawDateAfter || rawDateBefore)) {
+    return {
+      error: "conflicting_time_filters",
+      message:
+        "freshness and date_after/date_before cannot be used together. Use either freshness (day/week/month/year) or a date range (date_after/date_before), not both.",
+      docs: "https://docs.openclaw.ai/tools/web",
+    };
+  }
+
+  const parsedDateRange = parseIsoDateRange({
+    rawDateAfter,
+    rawDateBefore,
+    invalidDateAfterMessage: "date_after must be YYYY-MM-DD format.",
+    invalidDateBeforeMessage: "date_before must be YYYY-MM-DD format.",
+    invalidDateRangeMessage: "date_after must be before date_before.",
+  });
+  if ("error" in parsedDateRange) {
+    return parsedDateRange;
+  }
+
+  if (freshness) {
+    return {
+      timeRangeFilter: {
+        startTime: freshnessStartTime(freshness, now),
+        endTime: toGeminiTimeRangeTimestamp(now),
+      },
+    };
+  }
+
+  const { dateAfter, dateBefore } = parsedDateRange;
+  if (!dateAfter && !dateBefore) {
+    return {};
+  }
+
+  return {
+    timeRangeFilter: {
+      startTime: dateAfter ? isoDateStart(dateAfter) : "1970-01-01T00:00:00Z",
+      endTime: dateBefore ? isoDateExclusiveEnd(dateBefore) : toGeminiTimeRangeTimestamp(now),
+    },
+  };
+}
+
+export function resolveGeminiRuntimeApiKey(gemini?: GeminiConfig): string | undefined {
+  return (
+    readConfiguredSecretString(gemini?.apiKey, "tools.web.search.gemini.apiKey") ??
+    readProviderEnvValue(["GEMINI_API_KEY"]) ??
+    readConfiguredSecretString(gemini?.providerApiKey, "models.providers.google.apiKey")
+  );
+}
+
+async function runGeminiSearch(params: {
+  query: string;
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  timeoutSeconds: number;
+  signal?: AbortSignal;
+  timeRangeFilter?: GeminiTimeRangeFilter;
+}): Promise<{ content: string; citations: Array<{ url: string; title?: string }> }> {
+  const endpoint = `${params.baseUrl}/models/${params.model}:generateContent`;
+  const googleSearch =
+    params.timeRangeFilter === undefined ? {} : { timeRangeFilter: params.timeRangeFilter };
+
+  return withTrustedWebSearchEndpoint(
+    {
+      url: endpoint,
+      timeoutSeconds: params.timeoutSeconds,
+      signal: params.signal,
+      init: {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-goog-api-key": params.apiKey,
+        },
+        body: JSON.stringify({
+          contents: [{ parts: [{ text: params.query }] }],
+          tools: [{ google_search: googleSearch }],
+        }),
+      },
+    },
+    async (res) => {
+      if (!res.ok) {
+        const error = await createProviderHttpError(res, "Gemini API error");
+        throw new Error(error.message.replace(/key=[^&\s]+/giu, "key=***"));
+      }
+
+      const data = (await readProviderJsonObjectResponse(
+        res,
+        "Gemini API error",
+      )) as GeminiGroundingResponse;
+
+      if (data.error) {
+        const rawMessage = data.error.message || data.error.status || "unknown";
+        throw new Error(
+          formatProviderHttpErrorMessage({
+            label: "Gemini API error",
+            status: data.error.code ?? 0,
+            detail: rawMessage.replace(/key=[^&\s]+/giu, "key=***"),
+          }),
+        );
+      }
+
+      if (!Array.isArray(data.candidates)) {
+        throwMalformedGeminiResponse();
+      }
+      const candidate = data.candidates[0];
+      if (!isRecord(candidate) || !isRecord(candidate.content)) {
+        throwMalformedGeminiResponse();
+      }
+      const parts = candidate.content.parts;
+      if (!Array.isArray(parts)) {
+        throwMalformedGeminiResponse();
+      }
+      const content = parts
+        .map((part) => (isRecord(part) && typeof part.text === "string" ? part.text : undefined))
+        .filter((text): text is string => Boolean(text))
+        .join("\n");
+      if (!content) {
+        throwMalformedGeminiResponse();
+      }
+      const groundingMetadata = candidate.groundingMetadata;
+      const groundingChunks =
+        groundingMetadata === undefined
+          ? []
+          : isRecord(groundingMetadata) && Array.isArray(groundingMetadata.groundingChunks)
+            ? groundingMetadata.groundingChunks
+            : undefined;
+      if (!groundingChunks) {
+        throwMalformedGeminiResponse();
+      }
+      const rawCitations = groundingChunks.flatMap((chunk) => {
+        if (!isRecord(chunk) || !isRecord(chunk.web) || typeof chunk.web.uri !== "string") {
+          return [];
+        }
+        return [
+          {
+            url: chunk.web.uri,
+            title: typeof chunk.web.title === "string" ? chunk.web.title : undefined,
+          },
+        ];
+      });
+
+      const citations: Array<{ url: string; title?: string }> = [];
+      for (let index = 0; index < rawCitations.length; index += 10) {
+        const batch = rawCitations.slice(index, index + 10);
+        const resolved = await Promise.all(
+          batch.map(async (citation) =>
+            Object.assign({}, citation, { url: await resolveCitationRedirectUrl(citation.url) }),
+          ),
+        );
+        citations.push(...resolved);
+      }
+
+      return { content, citations };
+    },
+  );
+}
+
+export async function executeGeminiSearch(
+  args: Record<string, unknown>,
+  searchConfig?: SearchConfigRecord,
+  context?: { signal?: AbortSignal },
+): Promise<Record<string, unknown>> {
+  const unsupportedResponse = buildUnsupportedSearchFilterResponse(
+    {
+      country: args.country,
+      language: args.language,
+    },
+    "gemini",
+  );
+  if (unsupportedResponse) {
+    return unsupportedResponse;
+  }
+
+  const timeRange = resolveGeminiTimeRangeFilter(args);
+  if ("error" in timeRange) {
+    return timeRange;
+  }
+
+  const geminiConfig = resolveGeminiConfig(searchConfig);
+  const apiKey = resolveGeminiRuntimeApiKey(geminiConfig);
+  if (!apiKey) {
+    return {
+      error: "missing_gemini_api_key",
+      message:
+        "web_search (gemini) needs an API key. Set GEMINI_API_KEY in the Gateway environment, configure plugins.entries.google.config.webSearch.apiKey, or reuse models.providers.google.apiKey. If you do not want to configure a search API key, use web_fetch for a specific URL or the browser tool for interactive pages.",
+      docs: "https://docs.openclaw.ai/tools/web",
+    };
+  }
+
+  const query = readStringParam(args, "query", { required: true });
+  const count =
+    readNumberParam(args, "count", { integer: true }) ?? searchConfig?.maxResults ?? undefined;
+  const model = resolveGeminiModel(geminiConfig);
+  const baseUrl = resolveGeminiBaseUrl(geminiConfig);
+  const cacheKey = buildSearchCacheKey([
+    "gemini",
+    query,
+    resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
+    baseUrl,
+    model,
+    timeRange.timeRangeFilter?.startTime,
+    timeRange.timeRangeFilter?.endTime,
+  ]);
+  const cached = readCachedSearchPayload(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const start = Date.now();
+  const result = await runGeminiSearch({
+    query,
+    apiKey,
+    baseUrl,
+    model,
+    timeoutSeconds: resolveSearchTimeoutSeconds(searchConfig),
+    signal: context?.signal,
+    timeRangeFilter: timeRange.timeRangeFilter,
+  });
+  const payload = {
+    query,
+    provider: "gemini",
+    model,
+    tookMs: Date.now() - start,
+    externalContent: {
+      untrusted: true,
+      source: "web_search",
+      provider: "gemini",
+      wrapped: true,
+    },
+    content: wrapWebContent(result.content),
+    citations: result.citations,
+  };
+  writeCachedSearchPayload(cacheKey, payload, resolveSearchCacheTtlMs(searchConfig));
+  return payload;
+}

package/extensions/google/src/gemini-web-search-provider.shared.ts

@@ -0,0 +1,45 @@
+import { normalizeGoogleApiBaseUrl } from "../provider-policy.js";
+
+const DEFAULT_GEMINI_WEB_SEARCH_MODEL = "gemini-2.5-flash";
+
+export type GeminiConfig = {
+  apiKey?: unknown;
+  baseUrl?: unknown;
+  model?: unknown;
+  providerApiKey?: unknown;
+  providerBaseUrl?: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function trimToUndefined(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+export function resolveGeminiConfig(searchConfig?: Record<string, unknown>): GeminiConfig {
+  const gemini = searchConfig?.gemini;
+  return isRecord(gemini) ? gemini : {};
+}
+
+export function resolveGeminiApiKey(
+  gemini?: GeminiConfig,
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  return (
+    trimToUndefined(gemini?.apiKey) ??
+    trimToUndefined(env.GEMINI_API_KEY) ??
+    trimToUndefined(gemini?.providerApiKey)
+  );
+}
+
+export function resolveGeminiModel(gemini?: GeminiConfig): string {
+  return trimToUndefined(gemini?.model) ?? DEFAULT_GEMINI_WEB_SEARCH_MODEL;
+}
+
+export function resolveGeminiBaseUrl(gemini?: GeminiConfig): string {
+  return normalizeGoogleApiBaseUrl(
+    trimToUndefined(gemini?.baseUrl) ?? trimToUndefined(gemini?.providerBaseUrl),
+  );
+}

package/extensions/google/src/gemini-web-search-provider.ts

@@ -0,0 +1,151 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import {
+  createWebSearchProviderContractFields,
+  mergeScopedSearchConfig,
+  resolveProviderWebSearchPluginConfig,
+  type WebSearchProviderPlugin,
+  type WebSearchProviderToolDefinition,
+} from "openclaw/plugin-sdk/provider-web-search-config-contract";
+import {
+  resolveGeminiApiKey,
+  resolveGeminiBaseUrl,
+  resolveGeminiModel,
+} from "./gemini-web-search-provider.shared.js";
+
+const GEMINI_CREDENTIAL_PATH = "plugins.entries.google.config.webSearch.apiKey";
+const GOOGLE_PROVIDER_CREDENTIAL_PATH = "models.providers.google.apiKey";
+
+type GeminiWebSearchRuntime = typeof import("./gemini-web-search-provider.runtime.js");
+
+let geminiWebSearchRuntimePromise: Promise<GeminiWebSearchRuntime> | undefined;
+
+function loadGeminiWebSearchRuntime(): Promise<GeminiWebSearchRuntime> {
+  geminiWebSearchRuntimePromise ??= import("./gemini-web-search-provider.runtime.js");
+  return geminiWebSearchRuntimePromise;
+}
+
+const GEMINI_TOOL_PARAMETERS = {
+  type: "object",
+  properties: {
+    query: { type: "string", description: "Search query string." },
+    count: {
+      type: "number",
+      description: "Number of results to return (1-10).",
+      minimum: 1,
+      maximum: 10,
+    },
+    country: { type: "string", description: "Not supported by Gemini." },
+    language: { type: "string", description: "Not supported by Gemini." },
+    freshness: {
+      type: "string",
+      description: "Limit Google Search grounding to recent results: day, week, month, or year.",
+    },
+    date_after: {
+      type: "string",
+      description: "Only ground with results published after this date (YYYY-MM-DD).",
+    },
+    date_before: {
+      type: "string",
+      description: "Only ground with results published before this date (YYYY-MM-DD).",
+    },
+  },
+  required: ["query"],
+} satisfies Record<string, unknown>;
+
+function createGeminiToolDefinition(
+  searchConfig?: Record<string, unknown>,
+): WebSearchProviderToolDefinition {
+  return {
+    description:
+      "Search the web using Gemini with Google Search grounding. Returns AI-synthesized answers with citations from Google Search.",
+    parameters: GEMINI_TOOL_PARAMETERS,
+    execute: async (args, context) => {
+      const { executeGeminiSearch } = await loadGeminiWebSearchRuntime();
+      return await executeGeminiSearch(args, searchConfig, context);
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveGoogleModelProviderConfig(
+  config?: OpenClawConfig,
+): Record<string, unknown> | undefined {
+  const provider = config?.models?.providers?.google;
+  return isRecord(provider) ? provider : undefined;
+}
+
+function getGoogleModelProviderCredentialFallback(
+  config?: OpenClawConfig,
+): { path: string; value: unknown } | undefined {
+  const provider = resolveGoogleModelProviderConfig(config);
+  return provider && provider.apiKey !== undefined
+    ? { path: GOOGLE_PROVIDER_CREDENTIAL_PATH, value: provider.apiKey }
+    : undefined;
+}
+
+function withGoogleModelProviderFallbacks(
+  searchConfig: Record<string, unknown> | undefined,
+  config?: OpenClawConfig,
+): Record<string, unknown> | undefined {
+  const provider = resolveGoogleModelProviderConfig(config);
+  if (!provider || (provider.apiKey === undefined && provider.baseUrl === undefined)) {
+    return searchConfig;
+  }
+  const gemini = isRecord(searchConfig?.gemini) ? { ...searchConfig.gemini } : {};
+  const mergedSearchConfig = searchConfig ? { ...searchConfig } : {};
+  if (provider.apiKey !== undefined) {
+    gemini.providerApiKey = provider.apiKey;
+  }
+  if (provider.baseUrl !== undefined) {
+    gemini.providerBaseUrl = provider.baseUrl;
+  }
+  return {
+    ...mergedSearchConfig,
+    gemini,
+  };
+}
+
+export function createGeminiWebSearchProvider(): WebSearchProviderPlugin {
+  const contractFields = createWebSearchProviderContractFields({
+    credentialPath: GEMINI_CREDENTIAL_PATH,
+    searchCredential: { type: "scoped", scopeId: "gemini" },
+    configuredCredential: { pluginId: "google" },
+  });
+
+  return {
+    id: "gemini",
+    label: "Gemini (Google Search)",
+    hint: "Requires Google Gemini API key · Google Search grounding",
+    onboardingScopes: ["text-inference"],
+    credentialLabel: "Google Gemini API key",
+    envVars: ["GEMINI_API_KEY"],
+    placeholder: "AIza...",
+    signupUrl: "https://aistudio.google.com/apikey",
+    docsUrl: "https://docs.openclaw.ai/tools/web",
+    autoDetectOrder: 20,
+    credentialPath: GEMINI_CREDENTIAL_PATH,
+    ...contractFields,
+    getConfiguredCredentialFallback: getGoogleModelProviderCredentialFallback,
+    createTool: (ctx) =>
+      createGeminiToolDefinition(
+        withGoogleModelProviderFallbacks(
+          mergeScopedSearchConfig(
+            ctx.searchConfig,
+            "gemini",
+            resolveProviderWebSearchPluginConfig(ctx.config, "google"),
+          ),
+          ctx.config,
+        ),
+      ),
+  };
+}
+
+export const testing = {
+  resolveGeminiApiKey,
+  resolveGeminiBaseUrl,
+  resolveGeminiModel,
+} as const;
+export { testing as __testing };

package/extensions/google/test-api.ts

@@ -0,0 +1,6 @@
+export { buildGoogleGeminiCliBackend } from "./cli-backend.js";
+export { buildGoogleImageGenerationProvider } from "./image-generation-provider.js";
+export { buildGoogleMusicGenerationProvider } from "./music-generation-provider.js";
+export { buildGoogleSpeechProvider } from "./speech-provider.js";
+export { googleMediaUnderstandingProvider } from "./media-understanding-provider.js";
+export { buildGoogleVideoGenerationProvider } from "./video-generation-provider.js";

package/extensions/google/thinking-api.ts

@@ -0,0 +1,14 @@
+export {
+  createGoogleThinkingPayloadWrapper,
+  createGoogleThinkingStreamWrapper,
+  isGoogleGemini25ThinkingBudgetModel,
+  isGoogleGemini3FlashModel,
+  isGoogleGemini3ProModel,
+  isGoogleGemini3ThinkingLevelModel,
+  isGoogleThinkingRequiredModel,
+  resolveGoogleGemini3ThinkingLevel,
+  sanitizeGoogleThinkingPayload,
+  stripInvalidGoogleThinkingBudget,
+  type GoogleThinkingInputLevel,
+  type GoogleThinkingLevel,
+} from "./thinking.js";