@effect-uai/google 0.9.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

@@ -37,6 +37,9 @@ const FunctionCallPart = Schema.Struct({
     name: Schema.String,
     args: Schema.optional(Schema.Unknown),
   }),
+  // Gemini 3 thinking models attach an opaque signature to each function-call
+  // part that must be replayed on the next request, or the call is rejected.
+  thoughtSignature: Schema.optional(Schema.String),
 })
 
 const Part = Schema.Union([TextPart, FunctionCallPart])
@@ -74,7 +77,14 @@ export type WireChunk = typeof WireChunk.Type
 type RequestPart =
   | { readonly text: string }
   | { readonly inlineData: { readonly mimeType: string; readonly data: string } }
-  | { readonly functionCall: { readonly name: string; readonly args: unknown } }
+  | {
+      readonly functionCall: {
+        readonly id?: string
+        readonly name: string
+        readonly args: unknown
+      }
+      readonly thoughtSignature?: string
+    }
   | {
       readonly functionResponse: {
         readonly name: string
@@ -91,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: {
@@ -244,23 +264,37 @@ const nameForCallId = (
   )
 
 /**
- * Extract the Gemini-3 wire id we stashed in `providerData` on the way out.
- * Schema-driven so the shape lives in one place; failure → `Option.none()`.
+ * Extract the Gemini-3 wire id and thought signature we stashed in
+ * `providerData` on the way out. Schema-driven so the shape lives in one
+ * place; failure or absence → `Option.none()`.
  */
-const ProviderDataWithGeminiId = Schema.Struct({
-  gemini: Schema.Struct({ id: Schema.String }),
+const ProviderDataGemini = Schema.Struct({
+  gemini: Schema.Struct({
+    id: Schema.optional(Schema.String),
+    thoughtSignature: Schema.optional(Schema.String),
+  }),
 })
-const decodeProviderId = Schema.decodeUnknownResult(ProviderDataWithGeminiId)
-
-const providerIdFor = (item: ToolCall): Option.Option<string> =>
+const decodeGemini = Schema.decodeUnknownResult(ProviderDataGemini)
+
+const geminiField = (
+  item: ToolCall,
+  pick: (g: {
+    readonly id?: string | undefined
+    readonly thoughtSignature?: string | undefined
+  }) => string | undefined,
+): Option.Option<string> =>
   pipe(
-    decodeProviderId(item.providerData),
+    decodeGemini(item.providerData),
     Result.match({
-      onSuccess: (d) => Option.some(d.gemini.id),
+      onSuccess: (d) => Option.fromNullishOr(pick(d.gemini)),
       onFailure: () => Option.none<string>(),
     }),
   )
 
+const providerIdFor = (item: ToolCall): Option.Option<string> => geminiField(item, (g) => g.id)
+const signatureFor = (item: ToolCall): Option.Option<string> =>
+  geminiField(item, (g) => g.thoughtSignature)
+
 const itemToContent =
   (history: ReadonlyArray<HistoryItem>) =>
   (item: HistoryItem): Result.Result<RequestContent, void> =>
@@ -272,6 +306,10 @@ const itemToContent =
             role: "model" as const,
             parts: [
               {
+                ...Option.match(signatureFor(f), {
+                  onSome: (thoughtSignature) => ({ thoughtSignature }),
+                  onNone: () => ({}),
+                }),
                 functionCall: {
                   ...Option.match(providerIdFor(f), {
                     onSome: (id) => ({ id }),
@@ -374,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 && {
@@ -388,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) },
     }),
   }
@@ -414,6 +456,8 @@ export type AccumulatedFunctionCall = {
   readonly name: string
   /** Wire id from Gemini 3, when present - echoed back on `functionResponse`. */
   readonly providerId: Option.Option<string>
+  /** Thought signature from Gemini 3, replayed on the next request's part. */
+  readonly signature: Option.Option<string>
   /** Args as JSON-encoded string, mirroring `Items.ToolCall.arguments`. */
   readonly arguments: string
 }
@@ -451,6 +495,7 @@ export type ChunkPart =
   | {
       readonly kind: "function_call"
       readonly id: Option.Option<string>
+      readonly signature: Option.Option<string>
       readonly name: string
       readonly args: unknown
     }
@@ -470,6 +515,7 @@ const functionCallToChunkParts = (p: WireFunctionCallPart): ReadonlyArray<ChunkP
   {
     kind: "function_call",
     id: Option.fromNullishOr(p.functionCall.id),
+    signature: Option.fromNullishOr(p.thoughtSignature),
     name: p.functionCall.name,
     args: p.functionCall.args ?? {},
   },
@@ -537,6 +583,7 @@ const chunkCallToAccumulated = (
   callId: synthesizeCallId(call, prior),
   name: call.name,
   providerId: call.id,
+  signature: call.signature,
   // `functionCallToChunkParts` already replaced null/undefined with `{}`,
   // so `call.args` is always a JSON-encodable value here.
   arguments: JSON.stringify(call.args),
@@ -584,13 +631,19 @@ const assistantMessageItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
 const functionCallItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
   pipe(
     acc.functionCalls,
-    Arr.map((c) => ({
-      type: "function_call" as const,
-      call_id: c.callId,
-      name: c.name,
-      arguments: c.arguments,
-      ...(Option.isSome(c.providerId) && { providerData: { gemini: { id: c.providerId.value } } }),
-    })),
+    Arr.map((c) => {
+      const gemini = {
+        ...(Option.isSome(c.providerId) && { id: c.providerId.value }),
+        ...(Option.isSome(c.signature) && { thoughtSignature: c.signature.value }),
+      }
+      return {
+        type: "function_call" as const,
+        call_id: c.callId,
+        name: c.name,
+        arguments: c.arguments,
+        ...(Object.keys(gemini).length > 0 && { providerData: { gemini } }),
+      }
+    }),
   )
 
 export const accumulatorToTurn = (acc: Accumulator): Turn => ({