@effect-uai/google 0.10.0 → 0.11.0

package/src/GoogleDeepResearch.ts

@@ -0,0 +1,446 @@
+import { Context, Effect, Layer, Match, Redacted, Ref, Schema, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import {
+  DeepResearch,
+  type DeepResearchService,
+  type DeepResearchServiceShape,
+  fromJob,
+  type ResearchJobOps,
+} from "@effect-uai/core/DeepResearch"
+import * as Items from "@effect-uai/core/Items"
+import * as Job from "@effect-uai/core/Job"
+import type { ResearchJobRef, ResearchRequest, ResearchState } from "@effect-uai/core/Research"
+import * as SSE from "@effect-uai/core/SSE"
+import { type Turn, TurnEvent } from "@effect-uai/core/Turn"
+import type { GoogleDeepResearchModel } from "./models.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Gemini-typed research request. Narrows `model` to the deep-research agent ids.
+ * Provider-portable code uses the generic `DeepResearch` tag instead.
+ */
+export type GoogleResearchRequest = Omit<ResearchRequest, "model"> & {
+  readonly model?: GoogleDeepResearchModel
+}
+
+export type GoogleDeepResearchService = DeepResearchServiceShape<GoogleResearchRequest>
+
+/**
+ * Provider-typed tag for Gemini deep research over the Interactions API
+ * (`POST /v1beta/interactions`, `agent: deep-research-*`). Yield this for the
+ * agent-id knob; yield the generic `DeepResearch` tag for portable code.
+ *
+ * `research` / `submit` / `collect` drive a background job by polling;
+ * `researchStream` consumes the real Interactions SSE (`step.delta` text /
+ * thought, terminating in `interaction.completed`). Preview surface: the SSE
+ * event shapes and the completed-interaction citation shape are decoded
+ * defensively and best confirmed against a live response.
+ */
+export class GoogleDeepResearch extends Context.Service<
+  GoogleDeepResearch,
+  GoogleDeepResearchService
+>()("@betalyra/effect-uai/providers/google/GoogleDeepResearch") {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  /** Poll cadence / overall timeout for the derived poll loops. */
+  readonly job?: Job.JobConfig
+}
+
+// ---------------------------------------------------------------------------
+// Wire codec
+// ---------------------------------------------------------------------------
+
+const WireSubmit = Schema.Struct({ id: Schema.String })
+const decodeSubmit = Schema.decodeUnknownEffect(WireSubmit)
+
+// A completed interaction's text lives at `outputs[].text` (SDK `outputs`) or,
+// in some doc examples, `steps[].content[].text`. Decode both defensively and
+// extract from whichever is populated. Citations are undocumented on this
+// preview surface, so none are mapped yet (the report text carries inline
+// `[n]` markers); enrich once a live response confirms the shape.
+const WireTextPart = Schema.Struct({
+  type: Schema.optional(Schema.NullOr(Schema.String)),
+  text: Schema.optional(Schema.NullOr(Schema.String)),
+})
+const WireStep = Schema.Struct({
+  type: Schema.optional(Schema.NullOr(Schema.String)),
+  text: Schema.optional(Schema.NullOr(Schema.String)),
+  content: Schema.optional(Schema.NullOr(Schema.Array(WireTextPart))),
+})
+export const WireInteraction = Schema.Struct({
+  id: Schema.optional(Schema.NullOr(Schema.String)),
+  status: Schema.optional(Schema.NullOr(Schema.String)),
+  outputs: Schema.optional(Schema.NullOr(Schema.Array(WireTextPart))),
+  steps: Schema.optional(Schema.NullOr(Schema.Array(WireStep))),
+  error: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        message: Schema.optional(Schema.NullOr(Schema.String)),
+        code: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ),
+  ),
+})
+export type WireInteraction = typeof WireInteraction.Type
+const decodeInteraction = Schema.decodeUnknownEffect(WireInteraction)
+
+const textOfParts = (parts: ReadonlyArray<typeof WireTextPart.Type> | null | undefined): string =>
+  (parts ?? [])
+    .filter((p) => (p.type ?? "text") === "text" && p.text != null)
+    .map((p) => p.text)
+    .join("")
+
+const reportText = (wire: WireInteraction): string => {
+  const fromOutputs = textOfParts(wire.outputs)
+  if (fromOutputs.length > 0) return fromOutputs
+  const lastStep = (wire.steps ?? []).at(-1)
+  const fromStep = textOfParts(lastStep?.content)
+  return fromStep.length > 0 ? fromStep : (lastStep?.text ?? "")
+}
+
+const turnFromInteraction = (wire: WireInteraction): Turn => ({
+  items: [
+    {
+      type: "message",
+      role: "assistant",
+      content: [{ type: "output_text", text: reportText(wire) }],
+      providerData: wire,
+    },
+  ],
+  usage: {},
+  stop_reason: "stop",
+})
+
+// Map the interaction status onto the generic `JobState`.
+export const jobStateOf = (wire: WireInteraction): ResearchState =>
+  Match.value(wire.status ?? "").pipe(
+    Match.whenOr("queued", "pending", (): ResearchState => ({ _tag: "Pending" })),
+    Match.whenOr(
+      "in_progress",
+      "running",
+      "processing",
+      (): ResearchState => ({ _tag: "Running" }),
+    ),
+    Match.whenOr(
+      "completed",
+      "succeeded",
+      (): ResearchState => ({ _tag: "Succeeded", result: turnFromInteraction(wire) }),
+    ),
+    Match.whenOr(
+      "failed",
+      "error",
+      "cancelled",
+      (): ResearchState => ({
+        _tag: "Failed",
+        ...(wire.error?.message != null && { reason: wire.error.message }),
+        raw: wire,
+      }),
+    ),
+    Match.orElse((): ResearchState => ({ _tag: "Running" })),
+  )
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+const baseUrl = (cfg: Config): string =>
+  cfg.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta"
+
+const authHeader = (cfg: Config) =>
+  HttpClientRequest.setHeader("x-goog-api-key", Redacted.value(cfg.apiKey))
+
+const transportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "google", raw: cause })
+
+const httpStatusError = (status: number, body: string): AiError.AiError => {
+  const provider = "google"
+  const raw = body
+  if (status === 429) return new AiError.RateLimited({ provider, raw })
+  if (status === 408 || status === 504) return new AiError.Timeout({ provider, raw })
+  if (status === 401) return new AiError.AuthFailed({ provider, subtype: "auth", raw })
+  if (status === 403) return new AiError.AuthFailed({ provider, subtype: "permission", raw })
+  if (status === 402) return new AiError.AuthFailed({ provider, subtype: "billing", raw })
+  if (status === 413) return new AiError.ContextLengthExceeded({ provider, raw })
+  if (status >= 500) return new AiError.Unavailable({ provider, status, raw })
+  return new AiError.InvalidRequest({ provider, raw })
+}
+
+// Deep research takes one question. Concatenate the user turns' text into the
+// Interactions `input` string.
+const inputText = (history: ReadonlyArray<Items.HistoryItem>): string =>
+  history
+    .filter(Items.isMessage)
+    .filter((m) => m.role === "user")
+    .flatMap((m) => m.content)
+    .filter(Items.isInputText)
+    .map((b) => b.text)
+    .join("\n")
+
+const submitBody = (request: GoogleResearchRequest): Record<string, unknown> => ({
+  agent: request.model ?? "deep-research-preview-04-2026",
+  input: inputText(request.history),
+  background: true,
+  store: true,
+  agent_config: { type: "deep-research", thinking_summaries: "auto" },
+  tools: [{ type: "google_search" }],
+})
+
+const submitJob = (
+  cfg: Config,
+  request: GoogleResearchRequest,
+): Effect.Effect<ResearchJobRef, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/interactions`).pipe(
+      authHeader(cfg),
+      HttpClientRequest.bodyJsonUnsafe(submitBody(request)),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const wire = yield* decodeSubmit(json).pipe(Effect.mapError(transportFailure))
+    return Job.jobRef<Turn>("google", wire.id)
+  })
+
+const pollJob = (
+  cfg: Config,
+  ref: ResearchJobRef,
+): Effect.Effect<ResearchState, AiError.AiError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const httpRequest = HttpClientRequest.get(`${baseUrl(cfg)}/interactions/${ref.id}`).pipe(
+      authHeader(cfg),
+    )
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* httpStatusError(response.status, text)
+    }
+    const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    const wire = yield* decodeInteraction(json).pipe(Effect.mapError(transportFailure))
+    return jobStateOf(wire)
+  })
+
+// No verified cancel endpoint on the preview Interactions surface.
+const unsupported = (capability: string): AiError.Unsupported =>
+  new AiError.Unsupported({
+    provider: "google",
+    capability,
+    reason: "Gemini deep research (preview) exposes no verified cancel endpoint.",
+  })
+
+// ---------------------------------------------------------------------------
+// Streaming (Interactions SSE)
+// ---------------------------------------------------------------------------
+
+// The Interactions stream emits `step.delta` events in two shapes: the report
+// body arrives as `delta: { type: "text", text }`, while a thinking summary
+// arrives as `delta: { type: "thought_summary", content: { text } }` (and a
+// content-free `thought_signature` we skip). Terminates in `interaction.completed`
+// / `interaction.error`, then an OpenAI-style `[DONE]` sentinel we drop upstream.
+const WireDelta = Schema.Struct({
+  type: Schema.optional(Schema.NullOr(Schema.String)),
+  text: Schema.optional(Schema.NullOr(Schema.String)),
+  content: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        type: Schema.optional(Schema.NullOr(Schema.String)),
+        text: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ),
+  ),
+})
+const WireStreamEvent = Schema.Struct({
+  event_type: Schema.optional(Schema.NullOr(Schema.String)),
+  delta: Schema.optional(Schema.NullOr(WireDelta)),
+  interaction: Schema.optional(Schema.NullOr(WireInteraction)),
+  error: Schema.optional(
+    Schema.NullOr(Schema.Struct({ message: Schema.optional(Schema.NullOr(Schema.String)) })),
+  ),
+})
+type WireStreamEvent = typeof WireStreamEvent.Type
+
+const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+const decodeStreamEvent = Schema.decodeUnknownEffect(WireStreamEvent)
+
+// Prefer the completed interaction's decoded text; when the terminal event is
+// bare (or its text decodes empty) fall back to the accumulated stream deltas,
+// so `TurnComplete.turn` always carries the report that streamed.
+const completedTurn = (wire: WireInteraction | null | undefined, streamed: string): Turn =>
+  wire != null && reportText(wire).length > 0
+    ? turnFromInteraction(wire)
+    : {
+        items: [
+          {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: streamed }],
+            ...(wire != null && { providerData: wire }),
+          },
+        ],
+        usage: {},
+        stop_reason: "stop",
+      }
+
+// Map one wire event onto `TurnEvent`s, appending text deltas to `acc` (the
+// `completedTurn` fallback) and lifting `interaction.error` to a typed failure.
+const streamEventToTurnEvents = (
+  acc: Ref.Ref<string>,
+  ev: WireStreamEvent,
+): Effect.Effect<ReadonlyArray<TurnEvent>, AiError.AiError> => {
+  if (ev.event_type === "interaction.error") {
+    return Effect.fail(
+      new AiError.GenerationFailed({
+        provider: "google",
+        ...(ev.error?.message != null && { message: ev.error.message }),
+        raw: ev,
+      }),
+    )
+  }
+  if (ev.event_type === "step.delta") {
+    const delta = ev.delta
+    // Report body: `delta.text`. Accumulate it so the terminal `TurnComplete`
+    // carries the report even when `interaction.completed` arrives text-free.
+    if (delta?.text != null) {
+      const text = delta.text
+      return Effect.as(
+        Ref.update(acc, (streamed) => streamed + text),
+        [TurnEvent.TextDelta({ text })],
+      )
+    }
+    // Thinking summary: nested under `delta.content.text`. Surfaced as reasoning,
+    // not accumulated into the report.
+    if (delta?.content?.text != null) {
+      return Effect.succeed([
+        TurnEvent.ReasoningDelta({ text: delta.content.text, kind: "summary" }),
+      ])
+    }
+    return Effect.succeed([])
+  }
+  if (ev.event_type === "interaction.completed") {
+    return Effect.map(Ref.get(acc), (streamed) => [
+      TurnEvent.TurnComplete({ turn: completedTurn(ev.interaction, streamed) }),
+    ])
+  }
+  return Effect.succeed([])
+}
+
+// A streaming interaction create (`?stream=true`): consume the SSE directly,
+// mapping each event onto `TurnEvent`s via {@link streamEventToTurnEvents}.
+const streamCreate = (
+  cfg: Config,
+  request: GoogleResearchRequest,
+): Stream.Stream<TurnEvent, AiError.AiError, HttpClient.HttpClient> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const acc = yield* Ref.make("")
+      const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/interactions?stream=true`).pipe(
+        authHeader(cfg),
+        HttpClientRequest.bodyJsonUnsafe({ ...submitBody(request), stream: true }),
+        HttpClientRequest.accept("text/event-stream"),
+      )
+      const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+      // Preview surface: log the response status + content-type so an
+      // unexpected `application/json` (i.e. `?stream=true` not triggering SSE)
+      // is visible at LOG_LEVEL=Debug rather than presenting as a silent hang.
+      yield* Effect.logDebug("google interactions stream response", {
+        status: response.status,
+        contentType: response.headers["content-type"],
+      })
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return Stream.fail(httpStatusError(response.status, text))
+      }
+      return response.stream.pipe(
+        Stream.mapError(transportFailure),
+        SSE.fromBytes,
+        // Log each raw frame before decode: the ground truth for the (unverified)
+        // event_type / delta shapes this codec keys on.
+        Stream.tap((ev) =>
+          Effect.logDebug("google interactions sse frame", { event: ev.event, data: ev.data }),
+        ),
+        // The stream ends with an OpenAI-style `[DONE]` sentinel that is not JSON;
+        // drop it (and any blank frame) before the JSON decode.
+        Stream.filter((ev) => ev.event !== "done" && ev.data.trim() !== "[DONE]"),
+        Stream.mapEffect((ev) =>
+          parseJsonUnknown(ev.data).pipe(
+            Effect.flatMap(decodeStreamEvent),
+            Effect.mapError(transportFailure),
+            Effect.flatMap((wire) => streamEventToTurnEvents(acc, wire)),
+          ),
+        ),
+        Stream.flatMap(Stream.fromIterable),
+      )
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+const jobOps = (
+  cfg: Config,
+  client: HttpClient.HttpClient,
+): ResearchJobOps<GoogleResearchRequest> => {
+  const withClient = <A>(e: Effect.Effect<A, AiError.AiError, HttpClient.HttpClient>) =>
+    Effect.provideService(e, HttpClient.HttpClient, client)
+  return {
+    submit: (request) => withClient(submitJob(cfg, request)),
+    poll: (ref) => withClient(pollJob(cfg, ref)),
+    cancel: () => Effect.fail(unsupported("cancel")),
+  }
+}
+
+// fromJob's default surface, with `researchStream` overridden to the real
+// Interactions SSE (its submit-then-attach default only synthesizes progress).
+const buildService = <Req extends ResearchRequest>(
+  cfg: Config,
+  client: HttpClient.HttpClient,
+  ops: ResearchJobOps<Req>,
+  toGoogle: (request: Req) => GoogleResearchRequest,
+): DeepResearchServiceShape<Req> => ({
+  ...fromJob(ops, cfg.job),
+  researchStream: (request) =>
+    Stream.provideService(streamCreate(cfg, toGoogle(request)), HttpClient.HttpClient, client),
+})
+
+/** Build a `GoogleDeepResearchService`. For Layer setup, prefer {@link layer}. */
+export const make = (
+  cfg: Config,
+): Effect.Effect<GoogleDeepResearchService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient, (client) =>
+    buildService(cfg, client, jobOps(cfg, client), (request) => request),
+  )
+
+/**
+ * Layer registering the provider-typed `GoogleDeepResearch` tag and the generic
+ * `DeepResearch` tag. No capability markers: the surface (poll, collect,
+ * synthesized stream) is universal.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<GoogleDeepResearch | DeepResearch, never, HttpClient.HttpClient> => {
+  const typed = Layer.effect(GoogleDeepResearch, make(cfg))
+  const generic = Layer.effect(
+    DeepResearch,
+    Effect.map(HttpClient.HttpClient, (client): DeepResearchService => {
+      const ops = jobOps(cfg, client)
+      const genericOps: ResearchJobOps<ResearchRequest> = {
+        ...ops,
+        submit: (request) => ops.submit(request as GoogleResearchRequest),
+      }
+      return buildService(cfg, client, genericOps, (request) => request as GoogleResearchRequest)
+    }),
+  )
+  return Layer.merge(typed, generic)
+}

package/src/LyriaGenerator.ts

@@ -371,7 +371,7 @@ const streamGenerationFromUnsupported = <E, R>(
 export const make = (
   cfg: Config,
 ): Effect.Effect<LyriaGeneratorService, never, HttpClient.HttpClient> =>
-  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+  Effect.map(HttpClient.HttpClient, (client) => ({
     generate: (request) =>
       generateImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
     streamGeneration: (request) =>

package/src/codec.ts

@@ -101,14 +101,24 @@ type RequestSystemInstruction = {
   readonly parts: ReadonlyArray<{ readonly text: string }>
 }
 
-/** Gemini's tool declaration. We translate one `ToolDescriptor` per entry. */
-type RequestTool = {
-  readonly functionDeclarations: ReadonlyArray<{
-    readonly name: string
-    readonly description: string
-    readonly parameters: Record<string, unknown>
-  }>
-}
+/**
+ * Gemini's tool declaration. A `tools[]` entry is either a function-declaration
+ * block (translated from `ToolDescriptor`s) or one of the native hosted-tool
+ * entries. The native entries are empty objects keyed camelCase per the REST
+ * v1beta `Tool` object, and sit as siblings of the declarations in the same
+ * `tools` array.
+ */
+export type RequestTool =
+  | {
+      readonly functionDeclarations: ReadonlyArray<{
+        readonly name: string
+        readonly description: string
+        readonly parameters: Record<string, unknown>
+      }>
+    }
+  | { readonly googleSearch: {} }
+  | { readonly urlContext: {} }
+  | { readonly codeExecution: {} }
 
 type RequestToolConfig = {
   readonly functionCallingConfig: {
@@ -402,11 +412,13 @@ export const buildRequestBody = (
   history: ReadonlyArray<HistoryItem>,
   generationConfig: Option.Option<GenerationConfig>,
   tools: ReadonlyArray<ToolDescriptor> = [],
+  providerToolEntries: ReadonlyArray<RequestTool> = [],
   toolChoice: CommonRequest["toolChoice"] = undefined,
 ): RequestBody => {
   const systemTexts = pipe(allMessages(history), Arr.filterMap(systemMessageText))
   const contents = pipe(history, Arr.filterMap(itemToContent(history)))
-  const requestTools = toolDescriptorsToTools(tools)
+  const functionTools = toolDescriptorsToTools(tools)
+  const requestTools = [...functionTools, ...providerToolEntries]
   return {
     contents,
     ...(systemTexts.length > 0 && {
@@ -416,8 +428,10 @@ export const buildRequestBody = (
       onNone: () => ({}),
       onSome: (cfg) => ({ generationConfig: cfg }),
     }),
-    ...(requestTools.length > 0 && {
-      tools: requestTools,
+    ...(requestTools.length > 0 && { tools: requestTools }),
+    // Only force a function-calling mode when there are function declarations;
+    // a grounding-only request must keep the API default.
+    ...(functionTools.length > 0 && {
       toolConfig: { functionCallingConfig: toolChoiceToFunctionCallingConfig(toolChoice) },
     }),
   }

package/src/geminiTools.test.ts

@@ -0,0 +1,88 @@
+import { Effect, Option, Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+import { descriptorsOf, providerToolsOf } from "@effect-uai/core/Tool"
+import { describe, expect, it } from "vitest"
+import { WireChunk, buildRequestBody } from "./codec.js"
+import { codeExecutionTool, googleSearchTool, renderProviderTools } from "./GeminiTools.js"
+
+const localTool = Tool.make({
+  name: "get_weather",
+  description: "Look up the weather.",
+  inputSchema: Tool.fromEffectSchema(Schema.Struct({ city: Schema.String })),
+  run: ({ city }) => Effect.succeed(`sunny in ${city}`),
+})
+
+const build = (toolkit: Record<string, Tool.AnyTool>) => {
+  const entries = Result.getOrThrow(renderProviderTools(providerToolsOf(toolkit)))
+  return buildRequestBody([], Option.none(), descriptorsOf(toolkit), entries)
+}
+
+describe("Gemini provider tools", () => {
+  it("renders google_search to the native googleSearch entry", () => {
+    const body = build({ google_search: googleSearchTool })
+    expect(body.tools).toEqual([{ googleSearch: {} }])
+  })
+
+  it("renders a mixed toolkit to both a functionDeclarations entry and the native entry", () => {
+    const body = build({ get_weather: localTool, code_execution: codeExecutionTool })
+    expect(body.tools).toEqual([
+      {
+        functionDeclarations: [
+          expect.objectContaining({ name: "get_weather", description: "Look up the weather." }),
+        ],
+      },
+      { codeExecution: {} },
+    ])
+  })
+
+  it("omits toolConfig for a grounding-only request (no forced function-calling mode)", () => {
+    const body = build({ google_search: googleSearchTool })
+    expect(body.toolConfig).toBeUndefined()
+  })
+
+  it("sets toolConfig when a function declaration is present", () => {
+    const body = build({ get_weather: localTool, google_search: googleSearchTool })
+    expect(body.toolConfig).toEqual({ functionCallingConfig: { mode: "AUTO" } })
+  })
+
+  it("fails on a foreign provider tool", () => {
+    const foreign = Tool.provider({
+      name: "web_search",
+      description: "Anthropic web search.",
+      inputSchema: Tool.noInput,
+      provider: "anthropic",
+      config: { type: "web_search_20250305" },
+    })
+    const result = renderProviderTools(providerToolsOf({ web_search: foreign }))
+    expect(Result.isFailure(result)).toBe(true)
+  })
+
+  it("fails on an unrecognized config kind", () => {
+    const bogus = Tool.provider({
+      name: "mystery",
+      description: "Unknown Gemini tool.",
+      inputSchema: Tool.noInput,
+      provider: "gemini",
+      config: { kind: "telepathy" },
+    })
+    const result = renderProviderTools(providerToolsOf({ mystery: bogus }))
+    expect(Result.isFailure(result)).toBe(true)
+  })
+
+  it("decodes a grounded chunk without throwing (groundingMetadata is dropped)", () => {
+    const grounded = {
+      candidates: [
+        {
+          content: { role: "model", parts: [{ text: "Grounded answer." }] },
+          groundingMetadata: {
+            webSearchQueries: ["effect ts"],
+            groundingChunks: [{ web: { uri: "https://example.com", title: "Example" } }],
+          },
+          finishReason: "STOP",
+        },
+      ],
+    }
+    const chunk = Schema.decodeUnknownSync(WireChunk)(grounded)
+    expect(chunk.candidates?.[0]?.content?.parts?.[0]).toEqual({ text: "Grounded answer." })
+  })
+})

package/src/index.ts

@@ -1,6 +1,8 @@
 export * as Gemini from "./Gemini.js"
+export * as GeminiTools from "./GeminiTools.js"
 export * as GeminiEmbedding from "./GeminiEmbedding.js"
 export * as GeminiSynthesizer from "./GeminiSynthesizer.js"
+export * as GoogleDeepResearch from "./GoogleDeepResearch.js"
 export * as LyriaGenerator from "./LyriaGenerator.js"
 export * as codec from "./codec.js"
 export * from "./models.js"

package/src/models.ts

@@ -17,6 +17,21 @@ export type GoogleModel =
   // eslint-disable-next-line @typescript-eslint/ban-types
   | (string & {})
 
+/**
+ * Deep-research agent identifiers for the Interactions API (`POST
+ * /v1beta/interactions`). `-preview` is the fast tier, `-max-` the
+ * comprehensive one. Preview surface: verify against live docs before relying on
+ * exact ids. The `(string & {})` tail accepts any string so a renamed agent
+ * works without an SDK update.
+ *
+ * Reference: https://ai.google.dev/gemini-api/docs/interactions/deep-research
+ */
+export type GoogleDeepResearchModel =
+  | "deep-research-preview-04-2026"
+  | "deep-research-max-preview-04-2026"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
 /**
  * Known Gemini embedding model identifiers.
  *