@google/adk 2.2.1 → 2.4.0

package/dist/types/utils/client_labels.d.ts

@@ -41,7 +41,8 @@ export declare function getTrackingHeaders(): Record<string, string>;
  * single space, so the two differ only for values with repeated or non-space
  * whitespace. Commas are not treated as separators, so a `Headers` object that
  * joined two values of one header with `, ` keeps the comma on the first
- * token. All other headers keep the caller's name and value.
+ * token. Other repeated header names use the platform `Headers` semantics;
+ * for example, repeated `Cookie` values are joined with `; `.
  *
  * The input is never mutated.
  *

package/dist/types/utils/env_aware_utils.d.ts

@@ -34,15 +34,31 @@ export declare function randomUUID(): string;
 /**
  * Encodes the given string or Uint8Array to base64.
  *
+ * `window.btoa` is byte-oriented and throws on any code unit above `U+00FF`,
+ * so a string is first encoded to UTF-8 bytes. Node's `Buffer` encodes a
+ * string as UTF-8 too, which keeps both environments on one contract and lets
+ * `base64Decode` round-trip its output.
+ *
  * @param data The data to encode.
  * @return The base64-encoded string.
  */
 export declare function base64Encode(data: string | Uint8Array): string;
 /**
- * Decodes the given base64 string to a string.
+ * Decodes the given base64 string to UTF-8 text.
+ *
+ * `window.atob` is byte-oriented: it returns a latin1 "binary string" with one
+ * code unit per decoded byte, so a multi-byte UTF-8 sequence surfaces as
+ * mojibake. Node's `Buffer` decodes the same bytes as UTF-8, so the browser
+ * branch recovers the bytes from `atob` and decodes them explicitly. That keeps
+ * both environments on the single contract `File.content` and
+ * `materializeFiles` already assume.
+ *
+ * `ignoreBOM` keeps a leading byte order mark as `U+FEFF`, which is what
+ * `Buffer` does. `TextDecoder` strips it by default, so a spreadsheet CSV
+ * exported as UTF-8 with a BOM would otherwise lose a character.
  *
  * @param data The base64-encoded string.
- * @return The decoded string.
+ * @return The decoded UTF-8 string.
  */
 export declare function base64Decode(data: string): string;
 /**

package/dist/types/utils/error_utils.d.ts

@@ -3,6 +3,13 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Returns the plain, non-recursive message for a single thrown value.
+ *
+ * Reads `.message` from any object that carries a string `message` property,
+ * and falls back to `String(err)` for primitives and other values.
+ */
+export declare function getErrorMessage(err: unknown): string;
 /**
  * Formats an arbitrary thrown value into a readable, root-cause message.
  *

package/dist/types/utils/file_utils.d.ts

@@ -17,5 +17,10 @@ import { File } from '../code_executors/code_execution_utils.js';
  * @param dir The directory to materialize the files into.
  */
 export declare function materializeFiles(files: File[], dir: string): Promise<File[]>;
-export declare const EXTENSION_TO_MIME_TYPE: Record<string, string>;
+/**
+ * Guesses the MIME type of a file from its extension.
+ * @param filePath A file name or path.
+ * @returns The MIME type, or 'application/octet-stream' if the extension is
+ *     unknown or absent.
+ */
 export declare function guessMimeType(filePath: string): string;

package/dist/types/utils/gemini_schema_util.d.ts

@@ -4,12 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Schema } from '@google/genai';
-type MCPToolSchema = {
+export type MCPToolSchema = {
     type: 'object';
     properties?: Record<string, unknown>;
     required?: string[];
 };
 export declare function toGeminiSchema(mcpSchema?: MCPToolSchema): Schema | undefined;
+/**
+ * Normalizes a JSON Schema `type` value into a single non-null type name and a
+ * `nullable` flag.
+ *
+ * When `type` is an array containing multiple non-null types, the first
+ * non-null entry is selected as the primary Gemini schema type.
+ */
+export declare function normalizeJsonSchemaType(jsonSchemaType?: unknown): [string | undefined, boolean];
 /**
  * Converts an OpenAPI schema to a Gemini `Schema`.
  *
@@ -23,4 +31,3 @@ export declare function toGeminiSchema(mcpSchema?: MCPToolSchema): Schema | unde
  * @throws {TypeError} If the input is neither an object nor nullish.
  */
 export declare function openApiSchemaToGeminiSchema(openApiSchema?: unknown): Schema | undefined;
-export {};

package/dist/types/utils/json_utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** A JSON object keyed by string. */
+export type JsonObject = Record<string, unknown>;
+/** Narrows an arbitrary value to a plain JSON object (non-null, non-array). */
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/** Returns `value` when it is a JSON object, or `{}` otherwise. */
+export declare function toJsonObject(value: unknown): JsonObject;

package/dist/types/utils/object_notation_utils.d.ts

@@ -19,3 +19,10 @@ export declare function toCamelCase(obj: unknown, preserveKeys?: string[]): unkn
  * @returns The object with snake_case keys.
  */
 export declare function toSnakeCase(obj: unknown, preserveKeys?: string[]): unknown;
+/**
+ * Converts a camelCase, PascalCase, or hyphenated key to snake_case.
+ *
+ * @param key The key to convert.
+ * @returns The snake_case key.
+ */
+export declare const toSnakeCaseKey: (key: string) => string;

package/dist/types/utils/output_schema_utils.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { BaseLlm } from '../models/base_llm.js';
 /**
  * Returns whether the model can natively accept an output schema at the same
  * time as tools, which is strictly more reliable than the prompt-based
@@ -12,7 +13,7 @@
  * `false` for them even on Vertex AI, where they do support the capability.
  * That under-reporting is a known gap.
  *
- * @param modelString A simple or path-based model name.
+ * @param model A simple or path-based model name, or a `BaseLlm` instance.
  * @return True if the model supports an output schema alongside tools.
  */
-export declare function canUseOutputSchemaWithTools(modelString: string): boolean;
+export declare function canUseOutputSchemaWithTools(model: string | BaseLlm): boolean;

package/dist/types/utils/simple_zod_to_json.d.ts

@@ -6,7 +6,7 @@
 import { Schema } from '@google/genai';
 import { z as z3 } from 'zod/v3';
 import { z as z4 } from 'zod/v4';
-type ZodSchema<T = unknown> = z3.ZodType<T> | z4.ZodType<T>;
+export type ZodSchema<T = unknown> = z3.ZodType<T> | z4.ZodType<T>;
 /** Returns true if the value is a Zod schema (v3 or v4). */
 export declare function isZodSchema(obj: unknown): obj is ZodSchema;
 /** Returns true if the value is a Zod v3 schema. */
@@ -18,4 +18,3 @@ export declare function isZodV4Schema(obj: unknown): obj is z4.ZodType;
  */
 export declare function isZodObject(obj: unknown): obj is z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape>;
 export declare function zodObjectToSchema(schema: z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape>): Schema;
-export {};

package/dist/types/utils/streaming_utils.d.ts

@@ -5,14 +5,21 @@
  */
 import { GenerateContentResponse, Part } from '@google/genai';
 import { LlmResponse } from '../models/llm_response.js';
+/** Options for {@link GeminiStreamingResponseAggregator}. */
+export interface GeminiStreamingResponseAggregatorOptions {
+    /**
+     * Whether to flush parts as they arrive. Defaults to the
+     * PROGRESSIVE_SSE_STREAMING feature flag.
+     */
+    isProgressiveMode?: boolean;
+}
 /**
- * Aggregates partial streaming responses.
+ * Aggregates partial Gemini streaming responses.
  *
  * It aggregates content from partial responses, and generates LlmResponses for
  * individual (partial) model responses, as well as for aggregated content.
  */
-export declare class StreamingResponseAggregator {
-    private readonly isProgressiveMode;
+export declare class GeminiStreamingResponseAggregator {
     private usageMetadata?;
     private groundingMetadata?;
     private citationMetadata?;
@@ -20,7 +27,7 @@ export declare class StreamingResponseAggregator {
     private finishReason?;
     private lastThoughtSignature;
     private readonly strategy;
-    constructor(isProgressiveMode?: boolean);
+    constructor({ isProgressiveMode, }?: GeminiStreamingResponseAggregatorOptions);
     processResponse(response: GenerateContentResponse): AsyncGenerator<LlmResponse, void, void>;
     close(): LlmResponse | undefined;
 }

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "2.2.1";
+export declare const version = "2.4.0";