@google/adk 2.0.0 → 2.2.0

package/dist/types/tools/webmcp/webmcp_types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Minimal structural types for the WebMCP browser API.
+ *
+ * Declared here rather than taken from the `webmcp-types` package so the core
+ * package gains no dependency for a browser-only, still-experimental API. They
+ * describe only the surface this toolset uses.
+ *
+ * @see https://developer.chrome.com/docs/ai/webmcp
+ */
+/** Metadata a page may attach to a registered tool. */
+export interface WebMCPToolAnnotations {
+    /** The tool only reads state. */
+    readOnlyHint?: boolean;
+    /** The tool's output may contain untrusted content. */
+    untrustedContentHint?: boolean;
+    /** The tool performs a significant or non-reversible real-world action. */
+    consequentialHint?: boolean;
+}
+/** A tool as reported by `document.modelContext.getTools()`. */
+export interface WebMCPRegisteredTool {
+    name: string;
+    title?: string;
+    description?: string;
+    /**
+     * JSON Schema for the tool's arguments.
+     *
+     * Typed loosely on purpose: the specification says object, but browsers have
+     * been observed handing back a JSON string, and a schema that is silently
+     * misread leaves the model unable to pass any arguments at all.
+     */
+    inputSchema?: object | string;
+    annotations?: WebMCPToolAnnotations;
+    origin?: string;
+}
+/** Options accepted by `getTools()`. */
+export interface WebMCPGetToolsOptions {
+    /** Secure origins to include tools from, for cross-origin iframes. */
+    fromOrigins?: string[];
+}
+/** Options accepted by `executeTool()`. */
+export interface WebMCPExecuteToolOptions {
+    signal?: AbortSignal;
+}
+/** The `document.modelContext` object. */
+export interface WebMCPModelContext extends EventTarget {
+    getTools(options?: WebMCPGetToolsOptions): Promise<WebMCPRegisteredTool[]>;
+    executeTool(tool: WebMCPRegisteredTool, args?: unknown, options?: WebMCPExecuteToolOptions): Promise<unknown>;
+}
+/** A Document that may expose WebMCP. */
+export interface WebMCPDocument {
+    modelContext?: WebMCPModelContext;
+}
+/**
+ * Returns the WebMCP entry point for a document, or undefined when the browser
+ * does not expose one.
+ */
+export declare function getModelContext(doc?: WebMCPDocument): WebMCPModelContext | undefined;
+/**
+ * Whether WebMCP is available.
+ *
+ * False outside a browser and in browsers without the API, so importing this
+ * module from Node is harmless.
+ */
+export declare function isWebMCPSupported(doc?: WebMCPDocument): boolean;

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

@@ -10,3 +10,39 @@
  * @returns The converted value.
  */
 export declare function camelCaseKeys(val: unknown): unknown;
+/**
+ * Converts one string into snake_case.
+ *
+ * Handles lowerCamelCase, UpperCamelCase and space-separated text, as well as
+ * acronyms such as `REST API` and runs of consecutive uppercase letters.
+ *
+ * The `Name` suffix separates this from `toSnakeCase` in
+ * `object_notation_utils.ts`, which converts the keys of an object and takes a
+ * different argument.
+ *
+ * @example
+ * ```ts
+ * toSnakeCaseName('camelCase'); // 'camel_case'
+ * toSnakeCaseName('UpperCamelCase'); // 'upper_camel_case'
+ * toSnakeCaseName('REST API'); // 'rest_api'
+ * ```
+ *
+ * @param text The input string.
+ * @returns The snake_case form of `text`.
+ */
+export declare function toSnakeCaseName(text: string): string;
+/**
+ * Prefixes a Python keyword, the way adk-python's `rename_python_keywords`
+ * does. Mirrors the reference exactly: the set is Python's, not TypeScript's.
+ *
+ * @example
+ * ```ts
+ * renameReservedKeywords('in'); // 'param_in'
+ * renameReservedKeywords('total'); // 'total'
+ * ```
+ *
+ * @param s The candidate identifier.
+ * @param prefix The prefix to add when `s` is reserved.
+ * @returns `prefix + s` when `s` is reserved, otherwise `s` unchanged.
+ */
+export declare function renameReservedKeywords(s: string, prefix?: string): string;

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

@@ -3,6 +3,12 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * The header shapes that `fetch` accepts. This matches the DOM library's
+ * `HeadersInit`, which is not used by name because the lint configuration
+ * defines only Node globals and its `no-undef` rule rejects it.
+ */
+type HeadersInput = Headers | Array<[string, string]> | Record<string, string>;
 export declare function parseUserAgent(userAgent: string): string;
 /**
  * Runs the given callback within a context that has the specified client label.
@@ -17,3 +23,30 @@ export declare function runWithClientLabel<R>(clientLabel: string, callback: ()
  * Returns the current list of client labels that can be added to HTTP Headers.
  */
 export declare function getClientLabels(): string[];
+/**
+ * Returns the HTTP headers that identify a request as coming from ADK.
+ *
+ * Both headers carry the current client labels, including a label set with
+ * {@link runWithClientLabel} when called inside that context.
+ */
+export declare function getTrackingHeaders(): Record<string, string>;
+/**
+ * Returns a copy of `headers` with the ADK tracking headers merged in.
+ *
+ * HTTP header names are case-insensitive, so a caller's `User-Agent` or
+ * `X-Goog-Api-Client` in any casing is folded onto the lower-case name and the
+ * header is sent once. For each tracking header, the ADK tokens come first,
+ * followed by every caller token that is not already present. Caller values
+ * are split on whitespace and empty tokens are dropped; adk-python splits on a
+ * 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.
+ *
+ * The input is never mutated.
+ *
+ * @param headers The caller's headers, in any `HeadersInit` shape.
+ * @return A new plain object with the merged headers.
+ */
+export declare function mergeTrackingHeaders(headers?: HeadersInput): Record<string, string>;
+export {};

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

@@ -14,3 +14,19 @@
  * back to and the only correct move is to fail rather than degrade.
  */
 export declare function randomUUID(): string;
+/**
+ * Stand-in for `createHash`, reached from the PKCE helpers in
+ * `auth/oauth2/oauth2_utils.ts`.
+ *
+ * A PKCE code challenge needs a synchronous SHA-256, and the Web Crypto API
+ * offers none: `crypto.subtle.digest` is asynchronous, while `generateAuthUri`
+ * is called from synchronous public API. PKCE is therefore unavailable in the
+ * bundled web build, and this throws rather than emit an authorization request
+ * with a missing or forged challenge.
+ */
+export declare function createHash(_algorithm: string): never;
+/**
+ * Stand-in for `randomBytes`, reached when the PKCE helpers in
+ * `auth/oauth2/oauth2_utils.ts` generate a code verifier.
+ */
+export declare function randomBytes(_size: number): never;

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

@@ -4,12 +4,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Schema } from '@google/genai';
-import { z } from 'zod';
-declare const MCPToolSchemaObject: z.ZodObject<{
-    type: z.ZodLiteral<"object">;
-    properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    required: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-type MCPToolSchema = z.infer<typeof MCPToolSchemaObject>;
+type MCPToolSchema = {
+    type: 'object';
+    properties?: Record<string, unknown>;
+    required?: string[];
+};
 export declare function toGeminiSchema(mcpSchema?: MCPToolSchema): Schema | undefined;
+/**
+ * Converts an OpenAPI schema to a Gemini `Schema`.
+ *
+ * This is the counterpart of `toGeminiSchema` for an arbitrary OpenAPI schema
+ * rather than an MCP tool input schema. An OpenAPI document may carry any key
+ * it likes, so a key the Gemini `Schema` does not declare is dropped instead of
+ * being forwarded to a backend that rejects it.
+ *
+ * @param openApiSchema The OpenAPI schema, which may be any value.
+ * @returns The converted schema, or `undefined` when there is no input.
+ * @throws {TypeError} If the input is neither an object nor nullish.
+ */
+export declare function openApiSchemaToGeminiSchema(openApiSchema?: unknown): Schema | undefined;
 export {};

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

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Serializes `value` to JSON with the keys of every object sorted, so two
+ * structurally equal values stringify identically whatever order their
+ * properties were assigned in.
+ *
+ * Array order is meaningful and is preserved. A value JSON cannot represent at
+ * the top level, such as `undefined` or a function, stringifies to
+ * `'undefined'`, because `JSON.stringify` returns no string for it and callers
+ * need one.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Returns a short lowercase hex digest of `value`, computed with FNV-1a over
+ * {@link stableStringify}.
+ *
+ * This is not a cryptographic hash and must not be used as one. It exists to
+ * keep distinct values in distinct cache slots, which is the same job
+ * adk-python gives the builtin `hash()`.
+ */
+export declare function stableHash(value: unknown): string;

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

@@ -1,3 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
 /** Log levels for the logger. */
 export declare enum LogLevel {
     DEBUG = 0,
@@ -16,16 +21,37 @@ export interface Logger {
     error(...args: unknown[]): void;
     setLogLevel(level: LogLevel): void;
 }
+/** The `console` method each level is written with. */
+export declare const CONSOLE_METHOD: {
+    readonly 0: "debug";
+    readonly 1: "info";
+    readonly 2: "warn";
+    readonly 3: "error";
+};
 /**
  * Sets a custom logger for ADK, or null to disable logging.
  */
 export declare function setLogger(customLogger: Logger | null): void;
 /**
- * Gets the current logger instance.
+ * Gets the logger instance that is currently installed.
+ *
+ * The result is a snapshot. A later {@link setLogger} call swaps the instance,
+ * and this reference keeps writing to the old one. The {@link logger} facade
+ * resolves the installed instance on every call.
  */
 export declare function getLogger(): Logger;
 /**
- * Resets the logger to the default SimpleLogger.
+ * Resets the logger to the built-in console logger.
+ *
+ * This is the inverse of {@link setLogger}: it reinstates the built-in logger
+ * after a custom one has been installed. Prefer it over `setLogger(null)`,
+ * which installs a no-op logger that discards every message rather than
+ * restoring default output. On Node it also replaces the winston-backed logger
+ * that the Node entry point installs.
+ *
+ * The default logger is constructed fresh, so a log level previously applied
+ * with {@link setLogLevel} is discarded and the level returns to
+ * `LogLevel.INFO`.
  */
 export declare function resetLogger(): void;
 /**
@@ -33,6 +59,10 @@ export declare function resetLogger(): void;
  */
 export declare function setLogLevel(level: LogLevel): void;
 /**
- * The logger instance for ADK.
+ * The ADK logger.
+ *
+ * Every method forwards to the instance installed by {@link setLogger} at call
+ * time, so this object is safe to capture at module scope, including across a
+ * {@link setLogger} call with `null` to disable logging.
  */
 export declare const logger: Logger;

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The browser logger implementation.
+ *
+ * It mirrors the Node logger (`logger_node.ts`): a dedicated `Logger` class plus
+ * an `install*` function that the browser entry point (`core/src/index_web.ts`)
+ * wires in through `setLogger`. It writes through `console` and colours the
+ * level with a `%c` CSS directive, which browser dev consoles render (ANSI
+ * escape codes, as winston emits on Node, are not rendered there).
+ * See https://github.com/google/adk-js/issues/611.
+ */
+import { Logger, LogLevel } from './logger.js';
+/** The default logger in the browser. Writes coloured lines through `console`. */
+export declare class BrowserLogger implements Logger {
+    private logLevel;
+    setLogLevel(level: LogLevel): void;
+    log(level: LogLevel, ...messages: unknown[]): void;
+    debug(...messages: unknown[]): void;
+    info(...messages: unknown[]): void;
+    warn(...messages: unknown[]): void;
+    error(...messages: unknown[]): void;
+}
+/** Makes the colour-aware browser logger the current ADK logger. */
+export declare function installBrowserLogger(): void;

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

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Logger, LogLevel } from './logger.js';
+/** The default logger on Node. Writes through winston. */
+export declare class WinstonLogger implements Logger {
+    private readonly logger;
+    private logLevel;
+    constructor();
+    setLogLevel(level: LogLevel): void;
+    log(level: LogLevel, ...messages: unknown[]): void;
+    debug(...messages: unknown[]): void;
+    info(...messages: unknown[]): void;
+    warn(...messages: unknown[]): void;
+    error(...messages: unknown[]): void;
+}
+/** Makes the winston-backed logger the current ADK logger. */
+export declare function installNodeLogger(): void;

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

@@ -33,10 +33,38 @@ export declare function isGemini1Model(modelString: string): boolean;
  */
 export declare function isGemini2OrAbove(modelString: string): boolean;
 /**
- * Check if the model is a Gemini 3.x Flash Live model.
+ * Check if the model is a Gemini 3.x Live model.
+ *
+ * Matches the whole `gemini-3.N-*live*` family, not just the `-flash-live`
+ * spelling: ids such as `gemini-3.8-live` and `gemini-3.5-transcribe-live` are
+ * Live models too, and they need the same realtime handling. Non-live 3.x
+ * models such as `gemini-3.0-flash` are still excluded. Gemini 3.5 Live
+ * Translate ids are excluded as well, mirroring adk-python's
+ * `_is_gemini_3_x_live`, which handles them through a dedicated translate
+ * branch instead.
+ *
+ * @param modelString Either a simple model name or path-based model name
+ * @return true if it's a Gemini 3.x Live model, false otherwise.
+ */
+export declare function isGemini3xLive(modelString: string | undefined): boolean;
+/**
+ * Check if the model is a Gemini 3.5 Live Translate model.
+ *
+ * Live Translate ids contain "-live" but are translation endpoints rather
+ * than conversational Live models, so they must not take the Gemini 3.x Live
+ * conversational path. Mirrors adk-python's `is_gemini_3_5_live_translate`.
+ *
+ * @param modelString Either a simple model name or path-based model name
+ * @return true if it's a Gemini 3.5 Live Translate model, false otherwise.
+ */
+export declare function isGemini35LiveTranslate(modelString: string | undefined): boolean;
+/**
+ * Check if the model is a Gemini 3.x Live model.
  *
  * @param modelString Either a simple model name or path-based model name
- * @return true if it's a Gemini 3.x Flash Live model, false otherwise.
+ * @return true if it's a Gemini 3.x Live model, false otherwise.
+ * @deprecated Renamed to {@link isGemini3xLive}, which covers every Gemini 3.x
+ *   Live id rather than only those spelled `-flash-live`.
  */
 export declare function isGemini3xFlashLive(modelString: string | undefined): boolean;
 /**

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

@@ -8,9 +8,9 @@
  * time as tools, which is strictly more reliable than the prompt-based
  * `set_model_response` workaround.
  *
- * Early Access Program model names encode no numeric version, so
- * `isGemini2OrAbove` rejects them even on Vertex AI. The Python
- * implementation accepts them; that gap lives in the shared predicate.
+ * Early Access Program model names encode no numeric version, so this returns
+ * `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.
  * @return True if the model supports an output schema alongside tools.

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

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Serializes a value as JSON with every inline attachment payload elided.
+ *
+ * An `Event` carrying an image, an audio clip or a PDF holds the whole
+ * attachment as a base64 string at `content.parts[].inlineData.data`. Passing
+ * such an event to `JSON.stringify` writes those bytes into whatever collects
+ * the log, which is a different trust boundary from whoever uploaded the file.
+ * Each blob keeps its descriptive fields and reports how many characters were
+ * elided in place of the payload.
+ */
+export declare function stringifyWithRedactedInlineData(value: unknown): string;

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

@@ -4,19 +4,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
- * Redacts the credentials from a connection URI so the URI can be safely
- * included in error messages and logs.
+ * Redacts credentials from a URI so it can be safely included in error
+ * messages and logs.
  *
  * A database or session-service connection URI such as
  * `postgres://user:password@host:5432/db` embeds the password in its userinfo
- * component. Including such a URI verbatim in a thrown Error or log entry leaks
- * the credential to wherever those are collected (log files, error-tracking
+ * component. An OAuth2 callback/authorization-response URI instead carries
+ * its secret (an authorization code, or an echoed token) as a query
+ * parameter, for example `https://app/callback?code=SECRET&state=xyz`.
+ * Including either verbatim in a thrown Error or log entry leaks the
+ * credential to wherever those are collected (log files, error-tracking
  * services, stdout captured by an orchestrator), which is frequently a
- * different trust boundary from whoever provisioned the connection string.
+ * different trust boundary from whoever holds the credential.
  *
- * The same credential can instead arrive as a query parameter, for example
- * `postgres://user@host/db?password=secret`, which several drivers accept and
- * which reaches the same error paths. Both forms are masked.
+ * The same connection-string credential can also arrive as a query
+ * parameter rather than userinfo, for example
+ * `postgres://user@host/db?password=secret`, which several drivers accept
+ * and which reaches the same error paths. All forms above are masked.
  *
  * The rest of the URI is kept intact for debugging, mirroring the semantics of
  * Go's `net/url.URL.Redacted()`. A URI carrying no credential is returned

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

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Returns `true` when `url` uses a scheme that may be fetched. */
+export declare function isHttpUrl(url: URL): boolean;
+/**
+ * Returns `true` for `localhost` and any `*.localhost` name (case-insensitive,
+ * ignoring a trailing dot), matching Python's `_is_blocked_hostname` helper.
+ */
+export declare function isLocalhostHostname(hostname: string): boolean;
+/** Strips the surrounding brackets from an IPv6 URL hostname (`[::1]` → `::1`). */
+export declare function normalizeHost(hostname: string): string;
+/**
+ * Returns `true` when `address` is not globally routable (private, loopback,
+ * link-local, shared, reserved, multicast, ...). Unparseable input fails closed
+ * (blocked).
+ */
+export declare function isNonGlobalAddress(address: string): boolean;
+/**
+ * Returns `true` when `address` is link-local: IPv4 `169.254.0.0/16` (which
+ * holds the cloud metadata endpoint), IPv6 `fe80::/10`, or an IPv6 address that
+ * embeds a link-local IPv4. Unparseable input fails closed (blocked).
+ */
+export declare function isLinkLocalAddress(address: string): boolean;
+/**
+ * Resolves `hostname` to a de-duplicated list of IP addresses. IP literals are
+ * returned as-is; hostnames are resolved via DNS. Throws when resolution yields
+ * no address.
+ */
+export declare function resolveHostAddresses(hostname: string): Promise<string[]>;

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.0.0";
+export declare const version = "2.2.0";