@smithers-orchestrator/agents 0.24.2 → 0.25.0

package/src/index.js

@@ -21,7 +21,7 @@
 /** @typedef {import("./PiAgentOptions.ts").PiAgentOptions} PiAgentOptions */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
-/** @typedef {import("./OpenCodeAgent.ts").OpenCodeAgentOptions} OpenCodeAgentOptions */
+/** @typedef {import("./OpenCodeAgentOptions.ts").OpenCodeAgentOptions} OpenCodeAgentOptions */
 /** @typedef {import("./VibeAgentOptions.ts").VibeAgentOptions} VibeAgentOptions */
 /** @typedef {import("./agent-contract/SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
 /** @typedef {import("./agent-contract/SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
@@ -37,6 +37,14 @@
 /** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentSurfaceOptionMapping} CliAgentSurfaceOptionMapping */
 /** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentSurfaceResumeContract} CliAgentSurfaceResumeContract */
 /** @typedef {import("./cli-surface/CliAgentSurfaceTypes.ts").CliAgentUnsupportedFlag} CliAgentUnsupportedFlag */
+/** @typedef {import("./image-generation/ImageGenerationProvider.ts").ImageGenerationProvider} ImageGenerationProvider */
+/** @typedef {import("./image-generation/ImageGenerationRequest.ts").ImageGenerationRequest} ImageGenerationRequest */
+/** @typedef {import("./image-generation/ImageGenerationResult.ts").ImageGenerationResult} ImageGenerationResult */
+/** @typedef {import("./image-generation/ImageGenerationToolOptions.ts").ImageGenerationToolOptions} ImageGenerationToolOptions */
+/** @typedef {import("./http/CreateHttpToolOptions.ts").CreateHttpToolOptions} CreateHttpToolOptions */
+/** @typedef {import("./http/HttpToolAuth.ts").HttpToolAuth} HttpToolAuth */
+/** @typedef {import("./http/HttpToolInput.ts").HttpToolInput} HttpToolInput */
+/** @typedef {import("./http/HttpToolOutput.ts").HttpToolOutput} HttpToolOutput */
 // @smithers-type-exports-end
 
 export { BaseCliAgent } from "./BaseCliAgent/index.js";
@@ -45,17 +53,15 @@ export { AnthropicAgent } from "./AnthropicAgent.js";
 export { OpenAIAgent } from "./OpenAIAgent.js";
 export { HermesAgent } from "./HermesAgent.js";
 export { AmpAgent } from "./AmpAgent.js";
-export { createAmpCapabilityRegistry } from "./AmpAgent.js";
-export { AntigravityAgent, createAntigravityCapabilityRegistry } from "./AntigravityAgent.js";
+export { AntigravityAgent } from "./AntigravityAgent.js";
 export { ClaudeCodeAgent } from "./ClaudeCodeAgent.js";
 export { CodexAgent } from "./CodexAgent.js";
 export { GeminiAgent } from "./GeminiAgent.js";
 export { PiAgent } from "./PiAgent.js";
 export { KimiAgent } from "./KimiAgent.js";
 export { ForgeAgent } from "./ForgeAgent.js";
-export { createForgeCapabilityRegistry } from "./ForgeAgent.js";
 export { OpenCodeAgent } from "./OpenCodeAgent.js";
-export { VibeAgent, createVibeCapabilityRegistry } from "./VibeAgent.js";
+export { VibeAgent } from "./VibeAgent.js";
 export {
   getCliAgentCapabilityReport,
   getCliAgentCapabilityDoctorReport,
@@ -66,5 +72,17 @@ export {
 } from "./cli-capabilities/index.js";
 export { createSmithersAgentContract } from "./agent-contract/createSmithersAgentContract.js";
 export { renderSmithersAgentPromptGuidance } from "./agent-contract/renderSmithersAgentPromptGuidance.js";
+export { createImageGenerationTool } from "./image-generation/createImageGenerationTool.js";
+export { createHttpTool } from "./http/createHttpTool.js";
 export { zodToOpenAISchema } from "./zodToOpenAISchema.js";
 export { sanitizeForOpenAI } from "./sanitizeForOpenAI.js";
+export { createTranscriptionTool } from "./transcription/createTranscriptionTool.js";
+export {
+  createGroundedWebSearchToolset,
+  createExaSearchProvider,
+  createTavilySearchProvider,
+  createBraveSearchProvider,
+  createSerperSearchProvider,
+} from "./web-search/index.js";
+
+export { createElevenLabsTextToSpeechTool } from "./createElevenLabsTextToSpeechTool.js";

package/src/streamResultToGenerateResult.js

@@ -8,40 +8,69 @@
  * @returns {Promise<GenerateTextResult<TOOLS, any>>}
  */
 export async function streamResultToGenerateResult(stream, onStdout) {
+    // When the provider rejects the request (e.g. a 404 "model not found"), the
+    // AI SDK delivers an `error` part on the stream and then rejects the derived
+    // promises (text/output/steps) with a generic NoOutputGeneratedError that
+    // masks the real cause — which smithers' engine misclassifies as "the agent
+    // did not return valid JSON for the declared output schema". Capture the
+    // first error here so we can re-throw the genuine provider error instead.
+    /** @type {unknown} */
+    let streamError;
     if (onStdout) {
         for await (const part of stream.fullStream) {
-            if (part.type === "text-delta" && part.text) {
+            if (part.type === "error") {
+                if (streamError === undefined)
+                    streamError = part.error;
+            }
+            else if (part.type === "text-delta" && part.text) {
                 onStdout(part.text);
             }
         }
     }
     else {
-        await stream.consumeStream();
+        await stream.consumeStream({
+            onError: (error) => {
+                if (streamError === undefined)
+                    streamError = error;
+            },
+        });
+    }
+    /** @type {any[]} */
+    let resolved;
+    try {
+        resolved = await Promise.all([
+            stream.content,
+            stream.text,
+            stream.reasoning,
+            stream.reasoningText,
+            stream.files,
+            stream.sources,
+            stream.toolCalls,
+            stream.staticToolCalls,
+            stream.dynamicToolCalls,
+            stream.toolResults,
+            stream.staticToolResults,
+            stream.dynamicToolResults,
+            stream.finishReason,
+            stream.rawFinishReason,
+            stream.usage,
+            stream.totalUsage,
+            stream.warnings,
+            stream.steps,
+            stream.request,
+            stream.response,
+            stream.providerMetadata,
+            stream.output,
+        ]);
+    }
+    catch (err) {
+        // Prefer the captured provider error (the true 404/APICallError) over the
+        // SDK's masking NoOutputGeneratedError.
+        if (streamError !== undefined)
+            throw streamError;
+        throw err;
     }
-    const [content, text, reasoning, reasoningText, files, sources, toolCalls, staticToolCalls, dynamicToolCalls, toolResults, staticToolResults, dynamicToolResults, finishReason, rawFinishReason, usage, totalUsage, warnings, steps, request, response, providerMetadata, output,] = await Promise.all([
-        stream.content,
-        stream.text,
-        stream.reasoning,
-        stream.reasoningText,
-        stream.files,
-        stream.sources,
-        stream.toolCalls,
-        stream.staticToolCalls,
-        stream.dynamicToolCalls,
-        stream.toolResults,
-        stream.staticToolResults,
-        stream.dynamicToolResults,
-        stream.finishReason,
-        stream.rawFinishReason,
-        stream.usage,
-        stream.totalUsage,
-        stream.warnings,
-        stream.steps,
-        stream.request,
-        stream.response,
-        stream.providerMetadata,
-        stream.output,
-    ]);
+    const [content, text, reasoning, reasoningText, files, sources, toolCalls, staticToolCalls, dynamicToolCalls, toolResults, staticToolResults, dynamicToolResults, finishReason, rawFinishReason, usage, totalUsage, warnings, steps, request, response, providerMetadata, output,] = resolved;
     return {
         content,
         text,

package/src/transcription/createTranscriptionTool.js

@@ -0,0 +1,182 @@
+import { dynamicTool, jsonSchema } from "ai";
+
+const transcriptionInputSchema = {
+  type: "object",
+  properties: {
+    audioUrl: {
+      type: "string",
+      description: "HTTP(S) URL for the audio file to transcribe.",
+    },
+    audioBase64: {
+      type: "string",
+      description: "Base64-encoded audio bytes. Use this when the audio is already available in memory.",
+    },
+    mimeType: {
+      type: "string",
+      description: "MIME type for audioBase64, for example audio/mpeg or audio/wav.",
+    },
+    language: {
+      type: "string",
+      description: "Optional BCP-47 or provider-supported language hint.",
+    },
+    prompt: {
+      type: "string",
+      description: "Optional provider prompt or keywords to improve recognition.",
+    },
+  },
+  additionalProperties: false,
+};
+
+/**
+ * Create an AI SDK-compatible audio transcription tool backed by Whisper or Deepgram.
+ *
+ * @param {import("./createTranscriptionTool.ts").CreateTranscriptionToolOptions} options
+ * @returns {import("ai").Tool}
+ */
+export function createTranscriptionTool(options) {
+  const provider = options.provider;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("createTranscriptionTool requires fetch to be available");
+  }
+
+  return dynamicTool({
+    description:
+      options.description ??
+      "Transcribe speech from an audio URL or base64-encoded audio using a configured transcription provider.",
+    inputSchema: jsonSchema(transcriptionInputSchema),
+    execute: async (input) => {
+      const request = normalizeInput(input);
+      if (provider === "whisper") {
+        return transcribeWithWhisper(options, request, fetchImpl);
+      }
+      if (provider === "deepgram") {
+        return transcribeWithDeepgram(options, request, fetchImpl);
+      }
+      throw new Error(`Unsupported transcription provider: ${provider}`);
+    },
+  });
+}
+
+/**
+ * @param {unknown} input
+ * @returns {import("./createTranscriptionTool.ts").TranscriptionToolInput}
+ */
+function normalizeInput(input) {
+  const value = input && typeof input === "object" ? /** @type {Record<string, unknown>} */ (input) : {};
+  const audioUrl = typeof value.audioUrl === "string" && value.audioUrl.trim() ? value.audioUrl.trim() : undefined;
+  const audioBase64 =
+    typeof value.audioBase64 === "string" && value.audioBase64.trim() ? value.audioBase64.trim() : undefined;
+  if (!audioUrl && !audioBase64) {
+    throw new Error("Transcription requires either audioUrl or audioBase64");
+  }
+  if (audioUrl && audioBase64) {
+    throw new Error("Transcription accepts only one of audioUrl or audioBase64");
+  }
+  return {
+    ...(audioUrl ? { audioUrl } : {}),
+    ...(audioBase64 ? { audioBase64 } : {}),
+    ...(typeof value.mimeType === "string" && value.mimeType.trim() ? { mimeType: value.mimeType.trim() } : {}),
+    ...(typeof value.language === "string" && value.language.trim() ? { language: value.language.trim() } : {}),
+    ...(typeof value.prompt === "string" && value.prompt.trim() ? { prompt: value.prompt.trim() } : {}),
+  };
+}
+
+/**
+ * @param {import("./createTranscriptionTool.ts").CreateTranscriptionToolOptions} options
+ * @param {import("./createTranscriptionTool.ts").TranscriptionToolInput} input
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<import("./createTranscriptionTool.ts").TranscriptionToolResult>}
+ */
+async function transcribeWithWhisper(options, input, fetchImpl) {
+  const form = new FormData();
+  form.set("model", options.model ?? "whisper-1");
+  form.set("response_format", "verbose_json");
+  if (input.language) form.set("language", input.language);
+  if (input.prompt) form.set("prompt", input.prompt);
+
+  if (input.audioBase64) {
+    form.set("file", base64ToFile(input.audioBase64, input.mimeType ?? "application/octet-stream"));
+  } else if (input.audioUrl) {
+    const audioResponse = await fetchImpl(input.audioUrl);
+    await assertOk(audioResponse, "download audio for Whisper transcription");
+    const blob = await audioResponse.blob();
+    form.set("file", new File([blob], filenameForMime(input.mimeType ?? blob.type), { type: input.mimeType ?? blob.type }));
+  }
+
+  const response = await fetchImpl(options.baseUrl ?? "https://api.openai.com/v1/audio/transcriptions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${options.apiKey}` },
+    body: form,
+  });
+  await assertOk(response, "transcribe audio with Whisper");
+  const payload = /** @type {any} */ (await response.json());
+  return {
+    text: String(payload.text ?? ""),
+    ...(typeof payload.language === "string" ? { language: payload.language } : {}),
+    ...(typeof payload.duration === "number" ? { durationSeconds: payload.duration } : {}),
+    provider: "whisper",
+  };
+}
+
+/**
+ * @param {import("./createTranscriptionTool.ts").CreateTranscriptionToolOptions} options
+ * @param {import("./createTranscriptionTool.ts").TranscriptionToolInput} input
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<import("./createTranscriptionTool.ts").TranscriptionToolResult>}
+ */
+async function transcribeWithDeepgram(options, input, fetchImpl) {
+  const body = input.audioUrl
+    ? JSON.stringify({ url: input.audioUrl })
+    : Buffer.from(input.audioBase64 ?? "", "base64");
+  const url = new URL(options.baseUrl ?? "https://api.deepgram.com/v1/listen");
+  url.searchParams.set("model", options.model ?? "nova-3");
+  url.searchParams.set("smart_format", "true");
+  if (input.language) url.searchParams.set("language", input.language);
+
+  const response = await fetchImpl(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: `Token ${options.apiKey}`,
+      "Content-Type": input.audioUrl ? "application/json" : (input.mimeType ?? "application/octet-stream"),
+    },
+    body,
+  });
+  await assertOk(response, "transcribe audio with Deepgram");
+  const payload = /** @type {any} */ (await response.json());
+  const alternative = payload.results?.channels?.[0]?.alternatives?.[0] ?? {};
+  return {
+    text: String(alternative.transcript ?? ""),
+    ...(typeof payload.metadata?.duration === "number" ? { durationSeconds: payload.metadata.duration } : {}),
+    provider: "deepgram",
+  };
+}
+
+/**
+ * @param {Response} response
+ * @param {string} action
+ */
+async function assertOk(response, action) {
+  if (response.ok) return;
+  const message = await response.text().catch(() => "");
+  throw new Error(`Failed to ${action}: ${response.status} ${response.statusText}${message ? ` - ${message}` : ""}`);
+}
+
+/**
+ * @param {string} audioBase64
+ * @param {string} mimeType
+ * @returns {File}
+ */
+function base64ToFile(audioBase64, mimeType) {
+  const bytes = Buffer.from(audioBase64, "base64");
+  return new File([bytes], filenameForMime(mimeType), { type: mimeType });
+}
+
+/**
+ * @param {string} mimeType
+ * @returns {string}
+ */
+function filenameForMime(mimeType) {
+  const extension = mimeType.split("/")[1]?.split(";")[0] || "bin";
+  return `audio.${extension}`;
+}

package/src/transcription/createTranscriptionTool.ts

@@ -0,0 +1,29 @@
+import type { Tool } from "ai";
+
+export type TranscriptionProvider = "whisper" | "deepgram";
+
+export type TranscriptionToolInput = {
+  audioUrl?: string;
+  audioBase64?: string;
+  mimeType?: string;
+  language?: string;
+  prompt?: string;
+};
+
+export type TranscriptionToolResult = {
+  text: string;
+  language?: string;
+  durationSeconds?: number;
+  provider: TranscriptionProvider;
+};
+
+export type CreateTranscriptionToolOptions = {
+  provider: TranscriptionProvider;
+  apiKey: string;
+  model?: string;
+  baseUrl?: string;
+  description?: string;
+  fetch?: typeof fetch;
+};
+
+export declare function createTranscriptionTool(options: CreateTranscriptionToolOptions): Tool;

package/src/transcription/index.js

@@ -0,0 +1 @@
+export { createTranscriptionTool } from "./createTranscriptionTool.js";

package/src/transcription/index.ts

@@ -0,0 +1,6 @@
+export type {
+  CreateTranscriptionToolOptions,
+  TranscriptionProvider,
+  TranscriptionToolInput,
+  TranscriptionToolResult,
+} from "./createTranscriptionTool";

package/src/web-search/GroundedWebSearchProvider.ts

@@ -0,0 +1,21 @@
+export type GroundedWebSearchProviderKind = "semantic" | "fresh";
+
+export type GroundedWebSearchProviderName = "exa" | "tavily" | "brave" | "serper";
+
+export type GroundedWebSearchResult = {
+  title: string;
+  url: string;
+  snippet?: string;
+  publishedDate?: string;
+  score?: number;
+};
+
+export type GroundedWebSearchProvider = {
+  name: GroundedWebSearchProviderName;
+  kind: GroundedWebSearchProviderKind;
+  search(input: {
+    query: string;
+    maxResults: number;
+    freshness?: "day" | "week" | "month" | "year";
+  }): Promise<GroundedWebSearchResult[]>;
+};

package/src/web-search/GroundedWebSearchToolset.ts

@@ -0,0 +1,6 @@
+import type { Tool } from "ai";
+
+export type GroundedWebSearchToolset = {
+  tools: Record<"grounded_web_search", Tool>;
+  toolNames: ["grounded_web_search"];
+};

package/src/web-search/createBraveSearchProvider.js

@@ -0,0 +1,53 @@
+/** @typedef {import("./GroundedWebSearchProvider.ts").GroundedWebSearchProvider} GroundedWebSearchProvider */
+
+/**
+ * @param {{ apiKey: string; baseUrl?: string; fetch?: typeof fetch }} options
+ * @returns {GroundedWebSearchProvider}
+ */
+export function createBraveSearchProvider(options) {
+  return {
+    name: "brave",
+    kind: "fresh",
+    async search(input) {
+      const fetchImpl = options.fetch ?? fetch;
+      const params = new URLSearchParams({ q: input.query, count: String(input.maxResults) });
+      const freshness = freshnessParam(input.freshness);
+      if (freshness) params.set("freshness", freshness);
+      const response = await fetchImpl(`${options.baseUrl ?? "https://api.search.brave.com/res/v1/web/search"}?${params}`, {
+        headers: {
+          accept: "application/json",
+          "x-subscription-token": options.apiKey,
+        },
+      });
+      const body = await readJson(response, "Brave");
+      const results = Array.isArray(body.web?.results) ? body.web.results : [];
+      return results.map((result) => ({
+        title: String(result.title ?? result.url ?? "Untitled"),
+        url: String(result.url ?? ""),
+        snippet: result.description,
+      })).filter((result) => result.url);
+    },
+  };
+}
+
+/** @param {string | undefined} freshness */
+function freshnessParam(freshness) {
+  if (freshness === "day") return "pd";
+  if (freshness === "week") return "pw";
+  if (freshness === "month") return "pm";
+  if (freshness === "year") return "py";
+  return undefined;
+}
+
+/**
+ * @param {Response} response
+ * @param {string} provider
+ * @returns {Promise<any>}
+ */
+async function readJson(response, provider) {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`${provider} search failed (${response.status}): ${text}`);
+  }
+  return text ? JSON.parse(text) : {};
+}

package/src/web-search/createExaSearchProvider.js

@@ -0,0 +1,72 @@
+/** @typedef {import("./GroundedWebSearchProvider.ts").GroundedWebSearchProvider} GroundedWebSearchProvider */
+
+/**
+ * @param {{ apiKey: string; baseUrl?: string; fetch?: typeof fetch }} options
+ * @returns {GroundedWebSearchProvider}
+ */
+export function createExaSearchProvider(options) {
+  return {
+    name: "exa",
+    kind: "semantic",
+    async search(input) {
+      const fetchImpl = options.fetch ?? fetch;
+      const response = await fetchImpl(`${options.baseUrl ?? "https://api.exa.ai"}/search`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": options.apiKey,
+        },
+        body: JSON.stringify({
+          query: input.query,
+          numResults: input.maxResults,
+          useAutoprompt: true,
+          ...freshnessParams(input.freshness),
+        }),
+      });
+      const body = await readJson(response, "Exa");
+      const results = Array.isArray(body.results) ? body.results : [];
+      return results.map((result) => ({
+        title: String(result.title ?? result.url ?? "Untitled"),
+        url: String(result.url ?? ""),
+        snippet: typeof result.text === "string" ? result.text : result.summary,
+        publishedDate: result.publishedDate,
+        score: typeof result.score === "number" ? result.score : undefined,
+      })).filter((result) => result.url);
+    },
+  };
+}
+
+/** @param {string | undefined} freshness */
+function freshnessParams(freshness) {
+  const days = freshnessDays(freshness);
+  return days ? { startPublishedDate: isoDateDaysAgo(days) } : {};
+}
+
+/** @param {string | undefined} freshness */
+function freshnessDays(freshness) {
+  if (freshness === "day") return 1;
+  if (freshness === "week") return 7;
+  if (freshness === "month") return 30;
+  if (freshness === "year") return 365;
+  return undefined;
+}
+
+/** @param {number} days */
+function isoDateDaysAgo(days) {
+  const date = new Date();
+  date.setUTCDate(date.getUTCDate() - days);
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * @param {Response} response
+ * @param {string} provider
+ * @returns {Promise<any>}
+ */
+async function readJson(response, provider) {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`${provider} search failed (${response.status}): ${text}`);
+  }
+  return text ? JSON.parse(text) : {};
+}

package/src/web-search/createGroundedWebSearchToolset.js

@@ -0,0 +1,110 @@
+import { dynamicTool, jsonSchema } from "ai";
+
+/** @typedef {import("./GroundedWebSearchProvider.ts").GroundedWebSearchProvider} GroundedWebSearchProvider */
+/** @typedef {import("./GroundedWebSearchProvider.ts").GroundedWebSearchResult} GroundedWebSearchResult */
+/** @typedef {import("./GroundedWebSearchToolset.ts").GroundedWebSearchToolset} GroundedWebSearchToolset */
+
+/**
+ * @param {{ providers: GroundedWebSearchProvider[]; maxResultsPerProvider?: number }} options
+ * @returns {GroundedWebSearchToolset}
+ */
+export function createGroundedWebSearchToolset(options) {
+  const providers = options.providers ?? [];
+  if (!providers.some((provider) => provider.name === "exa" && provider.kind === "semantic")) {
+    throw new Error("grounded_web_search requires Exa as the semantic provider");
+  }
+  if (!providers.some((provider) => provider.kind === "fresh")) {
+    throw new Error("grounded_web_search requires at least one fresh/SERP provider: Tavily, Brave, or Serper");
+  }
+
+  return {
+    tools: {
+      grounded_web_search: dynamicTool({
+        description: "Search the web with both Exa semantic retrieval and a fresh/SERP provider, returning grounded citations.",
+        inputSchema: jsonSchema({
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            query: { type: "string", minLength: 1 },
+            maxResults: { type: "number", minimum: 1, maximum: 20 },
+            freshness: { type: "string", enum: ["day", "week", "month", "year"] },
+          },
+          required: ["query"],
+        }),
+        execute: async (input) => searchAll(providers, input, options.maxResultsPerProvider ?? 5),
+      }),
+    },
+    toolNames: ["grounded_web_search"],
+  };
+}
+
+/**
+ * @param {GroundedWebSearchProvider[]} providers
+ * @param {unknown} input
+ * @param {number} maxResultsPerProvider
+ * @returns {Promise<{ query: string; providers: string[]; results: Array<GroundedWebSearchResult & { provider: string; citation: number }> }>}
+ */
+async function searchAll(providers, input, maxResultsPerProvider) {
+  const args = normalizeInput(input, maxResultsPerProvider);
+  const settled = await Promise.allSettled(providers.map(async (provider) => ({
+    provider,
+    results: await provider.search(args),
+  })));
+  const deduped = new Map();
+  const succeededProviders = [];
+  for (const outcome of settled) {
+    if (outcome.status !== "fulfilled") continue;
+    const entry = outcome.value;
+    succeededProviders.push(entry.provider.name);
+    for (const result of entry.results) {
+      const key = normalizeUrl(result.url);
+      if (!key || deduped.has(key)) continue;
+      deduped.set(key, {
+        ...result,
+        provider: entry.provider.name,
+        citation: deduped.size + 1,
+      });
+    }
+  }
+  return {
+    query: args.query,
+    providers: succeededProviders,
+    results: [...deduped.values()],
+  };
+}
+
+/**
+ * @param {unknown} input
+ * @param {number} defaultMaxResults
+ */
+function normalizeInput(input, defaultMaxResults) {
+  const value = input && typeof input === "object" ? /** @type {Record<string, unknown>} */ (input) : {};
+  const query = typeof value.query === "string" ? value.query.trim() : "";
+  if (!query) {
+    throw new Error("grounded_web_search requires a non-empty query");
+  }
+  const requestedMax = typeof value.maxResults === "number" ? value.maxResults : defaultMaxResults;
+  const cappedMax = Math.min(requestedMax, defaultMaxResults);
+  return {
+    query,
+    maxResults: Math.min(Math.max(Math.trunc(cappedMax), 1), 20),
+    freshness: isFreshness(value.freshness) ? value.freshness : undefined,
+  };
+}
+
+/** @param {unknown} value */
+function isFreshness(value) {
+  return value === "day" || value === "week" || value === "month" || value === "year";
+}
+
+/** @param {string | undefined} url */
+function normalizeUrl(url) {
+  if (!url) return "";
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}