@google/adk 1.5.0 → 2.0.0

package/dist/types/tools/function_tool.d.ts

@@ -20,7 +20,13 @@ export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TPara
 /**
  * The signature of the user-provided function executed by a {@link FunctionTool}.
  */
-export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, tool_context?: Context) => Promise<unknown> | unknown;
+export type ToolExecuteFunction<TParameters extends ToolInputParameters> = (input: ToolExecuteArgument<TParameters>, toolContext?: Context) => Promise<unknown> | unknown;
+/**
+ * Whether a {@link FunctionTool} requires user confirmation before it runs: a
+ * boolean, or a predicate over the (validated) call arguments and tool context.
+ * See {@link ToolOptions.requireConfirmation}.
+ */
+export type RequireConfirmation<TParameters extends ToolInputParameters> = boolean | ((input: ToolExecuteArgument<TParameters>, toolContext?: Context) => boolean | Promise<boolean>);
 /**
  * The configuration options for creating a function-based tool.
  * The `name`, `description` and `parameters` fields are used to generate the
@@ -35,6 +41,24 @@ export type ToolOptions<TParameters extends ToolInputParameters> = {
     parameters?: TParameters;
     execute: ToolExecuteFunction<TParameters>;
     isLongRunning?: boolean;
+    /**
+     * Whether this tool requires user confirmation before it runs. A boolean, or
+     * a predicate over the (validated) call arguments and tool context returning
+     * a boolean.
+     *
+     * The HITL gate is enforced when the tool is invoked through an `LlmAgent`
+     * turn: `agents/functions.ts` surfaces an `adk_request_confirmation`
+     * interrupt from the tool's `requestedToolConfirmations`, and the tool only
+     * executes once the user approves (via the
+     * `RequestConfirmationLlmRequestProcessor`).
+     *
+     * NOTE: a workflow `ToolNode` does not yet route through that path, so a
+     * `requireConfirmation` tool used directly as a node does not pause — it
+     * returns the "requires confirmation" error as its node output. Approval for
+     * workflow nodes is not wired up. Mirrors Python's
+     * `FunctionTool(require_confirmation=...)`.
+     */
+    requireConfirmation?: RequireConfirmation<TParameters>;
 };
 /**
  * A unique symbol to identify ADK agent classes.
@@ -60,6 +84,7 @@ export declare class FunctionTool<TParameters extends ToolInputParameters = unde
     readonly [FUNCTION_TOOL_SIGNATURE_SYMBOL] = true;
     private readonly execute;
     private readonly parameters?;
+    private readonly requireConfirmation;
     /**
      * The constructor acts as the user-friendly factory.
      * @param options The configuration for the tool.
@@ -78,5 +103,25 @@ export declare class FunctionTool<TParameters extends ToolInputParameters = unde
      * @returns A promise resolving to the function's return value.
      */
     runAsync(req: RunAsyncToolRequest): Promise<unknown>;
+    /**
+     * Whether this call is gated on human approval — the static flag, or the
+     * predicate evaluated against the validated arguments.
+     *
+     * @param args The arguments the tool would run with.
+     * @param toolContext The context of the call, when there is one.
+     * @return Whether the call requires confirmation.
+     */
+    checkRequireConfirmation(args: Record<string, unknown>, toolContext?: Context): Promise<boolean>;
+    /** Parses `args` against the parameter schema, when one is declared. */
+    private validateArgs;
+    /** Resolves `requireConfirmation`, which may be a flag or a predicate. */
+    private evaluateRequireConfirmation;
+    /**
+     * Evaluates the confirmation gate. Returns `undefined` if the tool may
+     * proceed; otherwise returns the function response payload to surface instead
+     * of running (a request-for-confirmation on the first pass, or a rejection
+     * once the user declined).
+     */
+    private checkConfirmation;
 }
 export {};

package/dist/types/tools/get_user_choice_tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import { LongRunningFunctionTool } from './long_running_tool.js';
+/**
+ * A long-running tool that presents a list of options to the user and awaits
+ * their selection.
+ */
+export declare const getUserChoiceTool: LongRunningFunctionTool<z.ZodObject<{
+    options: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;

package/dist/types/tools/mcp/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * `@google/adk/tools/mcp` subpath: the MCP tools only, without the full ADK
+ * barrel. Also re-exported from `@google/adk`.
+ */
+export * from './load_mcp_resource_tool.js';
+export * from './mcp_session_manager.js';
+export * from './mcp_tool.js';
+export * from './mcp_toolset.js';

package/dist/types/tools/mcp/mcp_session_manager.d.ts

@@ -3,9 +3,9 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 /**
  * Defines the parameters for establishing a connection to an MCP server using
  * standard input/output (stdio). This is typically used for running MCP servers

package/dist/types/tools/mcp/mcp_tool.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { FunctionDeclaration } from '@google/genai';
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
 import { MCPSessionManager } from './mcp_session_manager.js';
 /**

package/dist/types/tools/mcp/mcp_toolset.d.ts

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BlobResourceContents, Resource, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
+import type { BlobResourceContents, Resource, TextResourceContents } from '@modelcontextprotocol/sdk/types.js';
 import { ReadonlyContext } from '../../agents/readonly_context.js';
 import { BaseTool } from '../base_tool.js';
 import { BaseToolset, ToolPredicate } from '../base_toolset.js';

package/dist/types/tools/request_input_tool.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import { LongRunningFunctionTool } from './long_running_tool.js';
+/**
+ * A long-running tool that presents a custom message to the user and awaits
+ * unstructured or structured input.
+ *
+ * `response_schema` is spelled the way a workflow's `RequestInput` spells it on
+ * the wire (`RESPONSE_SCHEMA_ARG` in `workflow/utils/hitl_utils`), so a client
+ * reads one key whichever way the pause was raised — the dev UI builds its
+ * reply form from it either way.
+ */
+export declare const requestInputTool: LongRunningFunctionTool<z.ZodObject<{
+    message: z.ZodString;
+    response_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;

package/dist/types/tools/skill/skill_toolset.d.ts

@@ -17,8 +17,10 @@ export declare class SkillToolset extends BaseToolset {
     additionalTools: Array<BaseTool | BaseToolset>;
     codeExecutor?: BaseCodeExecutor;
     registry?: SkillRegistry;
+    private readonly scriptOutputDir?;
     private toolCache;
     private fetchedSkillCache;
+    private tempOutputDir?;
     constructor(skills: Record<string, Skill> | Skill[], options?: {
         codeExecutor?: BaseCodeExecutor;
         additionalTools?: Array<BaseTool | BaseToolset>;
@@ -32,10 +34,34 @@ export declare class SkillToolset extends BaseToolset {
          * confirmation.
          */
         allowInlineScripts?: boolean;
+        /**
+         * Directory that files produced by `run_skill_script` /
+         * `run_skill_inline_script` are written into. Output file names come from
+         * the executed script, so this must be a directory dedicated to
+         * throwaway script output — never the application's working directory or
+         * a source tree.
+         *
+         * Defaults to a private, randomly named directory created under the OS
+         * temp dir on first use. Nothing removes that directory: `close()` runs
+         * once per invocation on a toolset instance that concurrent invocations
+         * share (see `Runner`), so it cannot tell whose output is still in use.
+         * Set this to own the location and the lifetime of the output.
+         */
+        scriptOutputDir?: string;
     });
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
     close(): Promise<void>;
     getSkill(name: string): Skill | undefined;
+    /**
+     * Resolves the directory that script output files are materialized into.
+     *
+     * Script output file names are attacker-influenced (a prompt-injected skill
+     * controls what its script writes), so they must never be resolved against
+     * the host application's working directory. When no `scriptOutputDir` was
+     * configured this hands back a private temp directory instead, created once
+     * and reused for the lifetime of the toolset.
+     */
+    getScriptOutputDir(): Promise<string>;
     getOrFetchSkill(name: string, invocationId?: string): Promise<Skill | undefined>;
     processLlmRequest(toolContext: Context, llmRequest: LlmRequest): Promise<void>;
     private resolveAdditionalTools;

package/dist/types/tools/tool_confirmation.d.ts

@@ -23,3 +23,50 @@ export declare class ToolConfirmation {
         payload?: unknown;
     });
 }
+/**
+ * Why a confirmation was refused. Each value is one of the checks the resume
+ * path makes before it runs a tool call a human approved.
+ */
+export type IntentMismatchReason = 
+/** The `adk_request_confirmation` call was not raised by the agent. */
+'untrusted_request'
+/** The `adk_request_confirmation` call carries no usable pinned call. */
+ | 'malformed_request'
+/** The pinned call is absent from session history. */
+ | 'unknown_original_call'
+/** The pinned call names a tool the agent does not have. */
+ | 'unregistered_tool'
+/** The pinned tool does not gate on confirmation, so nothing was approved. */
+ | 'confirmation_not_required'
+/** The pinned tool name disagrees with the call in history. */
+ | 'tool_name_mismatch'
+/** The pinned arguments disagree with the call in history. */
+ | 'arguments_mismatch';
+/**
+ * Raised when a tool confirmation does not bind to the action it claims to
+ * approve — the approval and the action about to run are not the same thing.
+ *
+ * The framework fails closed on this: a mismatch aborts the invocation rather
+ * than running an action no human agreed to. It is worth alerting on, so the
+ * message names the reason and the call, and deliberately carries no argument
+ * values — a rejected payload is attacker-controlled and does not belong in
+ * logs.
+ */
+export declare class IntentMismatchError extends Error {
+    /** Which binding check refused the confirmation. */
+    readonly reason: IntentMismatchReason;
+    /** The id of the pinned call, when one was named. */
+    readonly functionCallId?: string;
+    constructor(options: {
+        reason: IntentMismatchReason;
+        functionCallId?: string;
+    });
+}
+/**
+ * Type guard for {@link IntentMismatchError}.
+ *
+ * Matches on `name` rather than `instanceof` so it stays correct when the error
+ * crosses a package boundary (two copies of adk-js in one runtime would fail an
+ * `instanceof` check between them).
+ */
+export declare function isIntentMismatchError(e: unknown): e is IntentMismatchError;

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

@@ -4,15 +4,47 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
- * A generic, async-safe queue that implements AsyncIterable.
+ * A generic, single-consumer async queue that implements AsyncIterable,
+ * bridging a *push* producer to a *pull* consumer (`for await (const x of q)`).
+ *
+ * Producers call {@link push} as values are produced and {@link close} (or
+ * {@link fail}) when finished. A single consumer drains the queue.
+ *
+ * Semantics:
+ *  - Buffered items are always delivered before an end/error signal.
+ *  - {@link close} ends iteration cleanly (`done: true`); idempotent.
+ *  - {@link fail} surfaces the error to the consumer *after* any buffered items
+ *    have been drained; it is sticky (first failure wins) and also closes the
+ *    queue, so a later `close()` can't discard the error.
+ *  - {@link push} after close/fail is ignored (the producer has already
+ *    signalled completion).
  */
 export declare class AsyncQueue<T> implements AsyncIterable<T> {
     private queue;
     private resolvers;
     private closed;
-    private errorVal?;
+    private failure?;
+    /** Whether the queue has been closed or failed. */
+    get isClosed(): boolean;
+    /** Number of items buffered and not yet consumed. */
+    get size(): number;
+    /**
+     * Enqueues a value. If a consumer is currently awaiting, it is resolved
+     * immediately; otherwise the value is buffered. No-op once closed/failed.
+     */
     push(value: T): void;
+    /**
+     * Signals that production failed. Buffered items are still delivered first;
+     * once the buffer drains, the consumer's next `next()` rejects with `error`.
+     * Sticky (first failure wins) and closes the queue.
+     */
+    fail(error: unknown): void;
+    /** @deprecated Alias for {@link fail}; kept for existing callers. */
     error(err: unknown): void;
+    /**
+     * Signals that no more items will be produced. Any awaiting consumer receives
+     * `{done: true}`. Idempotent.
+     */
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }

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

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Browser stand-in for the `node:crypto` builtin, wired up by the alias in
+ * `build.js` so that the Node fallback in `env_aware_utils.ts` does not pull a
+ * Node builtin into the web bundle.
+ *
+ * `randomUUID` is reached here only after both `globalThis.crypto` branches in
+ * `env_aware_utils.ts` have been ruled out. In a browser that means the Web
+ * Crypto API is genuinely absent, so there is no secure source left to fall
+ * back to and the only correct move is to fail rather than degrade.
+ */
+export declare function randomUUID(): string;

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Resets the warned-once registry. Test-only. */
+export declare function resetDeprecationWarnings(): void;
+type Constructor = new (...args: any[]) => any;
+/**
+ * Marks a class as deprecated, logging `reason` once the first time it is
+ * instantiated.
+ *
+ * The JSDoc `@deprecated` tag is what a reader and an editor see; this is what
+ * someone running the code sees, so a deprecation is not silent to a caller who
+ * never opens the source. Mirrors `typing_extensions.deprecated`, which
+ * adk-python applies to the same classes, and follows the shape of
+ * {@link experimental}: one warning per class, not per instance, so a hot loop
+ * does not turn into a wall of logs.
+ */
+export declare function deprecated(reason: string): <T extends Constructor>(target: T) => T;
+export {};

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

@@ -7,6 +7,29 @@
  * Returns true if the environment is a browser.
  */
 export declare function isBrowser(): boolean;
+/**
+ * Generates a random UUID from a cryptographically secure source.
+ *
+ * `crypto.randomUUID()` is only exposed in secure contexts, so it is absent on
+ * plain-HTTP origins even though `crypto` itself is present.
+ * `crypto.getRandomValues()` carries no such restriction, so it is used as the
+ * fallback rather than `Math.random()`.
+ *
+ * In Node the `globalThis.crypto` global was added in v17.4.0 and stayed behind
+ * `--experimental-global-webcrypto` until v19.0.0, so neither of those branches
+ * matches on a default Node 18 or earlier. `node:crypto` carries no such gate —
+ * its `randomUUID` has existed since v14.17.0 — so it is the last resort. In
+ * the bundled web build the import is aliased to `crypto_shim.ts`, which
+ * throws, because a browser without the Web Crypto API has no secure source
+ * left. The non-bundle `dist/web` output that `package.json#browser` points
+ * at keeps the import verbatim, as it already does for `node:async_hooks`
+ * and `node:path`.
+ *
+ * Some callers use this value to make security decisions — the OAuth2 `state`
+ * parameter in `AuthHandler` and the session identifiers minted by the session
+ * services — so this function must not silently degrade to a non-cryptographic
+ * generator.
+ */
 export declare function randomUUID(): string;
 /**
  * Encodes the given string or Uint8Array to base64.
@@ -36,3 +59,19 @@ export declare function isBase64Encoded(data: string): boolean;
  * @return The boolean value of the environment variable.
  */
 export declare function getBooleanEnvVar(envVar: string): boolean;
+/**
+ * Returns whether Google GenAI enterprise mode is enabled.
+ *
+ * `GOOGLE_GENAI_USE_ENTERPRISE` takes precedence whenever it is set, even when
+ * it is set to a falsy value. `GOOGLE_GENAI_USE_VERTEXAI` is only consulted
+ * when `GOOGLE_GENAI_USE_ENTERPRISE` is absent.
+ *
+ * Setting the deprecated `GOOGLE_GENAI_USE_VERTEXAI` logs a deprecation
+ * warning, whether it is used or overridden. When both variables are set the
+ * warning also states that `GOOGLE_GENAI_USE_VERTEXAI` is ignored, so a stale
+ * value silently overridden by the new variable is still surfaced. This is
+ * read per request, so the warning is logged only once.
+ *
+ * @return True if enterprise mode is enabled, false otherwise.
+ */
+export declare function isEnterpriseModeEnabled(): boolean;

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Formats an arbitrary thrown value into a readable, root-cause message.
+ *
+ * Recursively flattens `AggregateError.errors` (joining leaves with ` | `) and
+ * unwraps the `Error.cause` chain, and — when HTTP details are synchronously
+ * available — appends the status code and a response-body snippet truncated to
+ * 1000 characters with a `... [truncated]` marker. It never throws and is safe
+ * on `null`/`undefined` and cyclic error graphs.
+ *
+ * @param err The thrown or rejected value to format.
+ * @return A single human-readable message describing the root cause(s).
+ */
+export declare function formatError(err: unknown): string;

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

@@ -5,9 +5,17 @@
  */
 import { File } from '../code_executors/code_execution_utils.js';
 /**
- * Creates files with the given paths in the current working directory.
+ * Writes `files` into `dir`, refusing any entry that resolves outside of it.
+ *
+ * `dir` is deliberately required and has no default: file names typically
+ * originate from a code executor's output (i.e. from model- or skill-controlled
+ * content), so the destination must be a dedicated directory chosen by the
+ * caller. Defaulting to `process.cwd()` would let such content drop files into
+ * the host application's working directory.
+ *
  * @param files The files to materialize.
+ * @param dir The directory to materialize the files into.
  */
-export declare function materializeFiles(files: File[], dir?: string): Promise<File[]>;
+export declare function materializeFiles(files: File[], dir: string): Promise<File[]>;
 export declare const EXTENSION_TO_MIME_TYPE: Record<string, string>;
 export declare function guessMimeType(filePath: string): string;

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

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Schema } from '@google/genai';
+/**
+ * Converts a genai `Schema` into a standard JSON Schema object.
+ *
+ * This is the inverse of `zodObjectToSchema`, which renders Zod into the
+ * genai/OpenAPI dialect. The two dialects differ in four ways, all handled
+ * here:
+ *
+ * - `type` is an uppercase enum (`STRING`) rather than a JSON Schema type name
+ *   (`string`). `TYPE_UNSPECIFIED` means "no constraint" and is dropped.
+ * - `nullable: true` widens the type, which JSON Schema expresses as a type
+ *   union (`['string', 'null']`).
+ * - Count and length bounds are stringified (`maxItems: '5'`).
+ * - `propertyOrdering` and `example` have no JSON Schema equivalent.
+ *
+ * Everything else (`description`, `title`, `default`, `pattern`, `required`,
+ * `minimum`, `maximum`, `format`) is already JSON-Schema-shaped and passes
+ * through, with `items`, `properties` and `anyOf` converted recursively.
+ */
+export declare function genaiSchemaToJsonSchema(schema: Schema): Record<string, unknown>;

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

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Describes the optional peer dependency a feature is asking for. */
+export interface OptionalPeer {
+    /** The npm package name, e.g. `@google-cloud/storage`. */
+    packageName: string;
+    /** The ADK feature that needs it, used in the error message. */
+    feature: string;
+}
+/**
+ * Loads an optional peer dependency, translating "not installed" into an
+ * actionable error.
+ *
+ * The dynamic `import()` is passed in as a thunk rather than being built from
+ * `packageName`, so that the specifier stays a literal in the calling module
+ * and remains visible to bundlers and to test doubles installed with
+ * `vi.mock()`.
+ *
+ * ```ts
+ * const {Storage} = await loadOptionalPeer(
+ *   {packageName: '@google-cloud/storage', feature: 'GcsArtifactService'},
+ *   () => import('@google-cloud/storage'),
+ * );
+ * ```
+ *
+ * @param peer The package being loaded and the feature that needs it.
+ * @param load Thunk performing the dynamic `import()`.
+ * @return The imported module namespace.
+ * @throws If the package is not installed, an error naming the feature and
+ *   the `npm install` command that fixes it. Any other load failure is
+ *   rethrown unchanged.
+ */
+export declare function loadOptionalPeer<T>(peer: OptionalPeer, load: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * 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
+ * `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.
+ *
+ * @param modelString A simple or path-based model name.
+ * @return True if the model supports an output schema alongside tools.
+ */
+export declare function canUseOutputSchemaWithTools(modelString: string): boolean;

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * 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.
+ *
+ * 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
+ * services, stdout captured by an orchestrator), which is frequently a
+ * different trust boundary from whoever provisioned the connection string.
+ *
+ * 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 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
+ * unchanged, byte for byte.
+ *
+ * If the input cannot be parsed as a URL, only its scheme prefix is returned so
+ * that a credential embedded in an otherwise-unparseable string is not leaked.
+ */
+export declare function redactUriPassword(uri: string): string;

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A single, reusable abstraction over the schema formats ADK APIs accept: a Zod
+ * v3 type, a Zod v4 type, or a genai `Schema`. Mirrors the union
+ * `FunctionTool` uses for its parameters, but at the `ZodType` level (any
+ * schema, not just an object) so it also fits value validation.
+ */
+import { Schema } from '@google/genai';
+import { z as z3 } from 'zod/v3';
+import { z as z4 } from 'zod/v4';
+/**
+ * A schema accepted by ADK APIs, expressed as a Zod v3 type, a Zod v4 type, or
+ * a genai `Schema`.
+ *
+ * Use `parseWithSchema` to validate a value against one, and `toJsonSchema` to
+ * render one as a plain JSON Schema.
+ */
+export type SchemaLike = z3.ZodType | z4.ZodType | Schema;
+/**
+ * Validates `value` against `schema`, returning the parsed value.
+ *
+ * Every schema form ADK accepts is enforced:
+ *
+ * - Zod v3/v4: runs `schema.parse(value)`.
+ * - genai `Schema`: converted to JSON Schema and compiled to a Zod type once
+ *   (then cached), so a declaration written in the genai dialect is checked
+ *   just as a Zod one is.
+ * - `undefined`: returns `value` unchanged.
+ *
+ * A genai `Schema` that has no Zod equivalent is left unenforced rather than
+ * rejected — see {@link genaiSchemaValidator}.
+ */
+export declare function parseWithSchema<T>(schema: SchemaLike | undefined, value: T): T;
+/**
+ * Renders a {@link SchemaLike} as a plain JSON Schema object.
+ *
+ * Zod v3 and v4 schemas are converted with their respective serializers. A
+ * genai `Schema` is translated out of the genai/OpenAPI dialect (uppercase
+ * type names, stringified bounds, `nullable`) so that every schema form
+ * produces the same JSON Schema shape for a consumer to read.
+ */
+export declare function toJsonSchema(schema: SchemaLike): Record<string, unknown>;
+/**
+ * Compiles a plain JSON Schema into a validator, for schemas that survive only
+ * in serialized form — a `RequestInput.responseSchema` reaches the resume that
+ * answers it as the JSON Schema recorded on the interrupt event, not as the
+ * original {@link SchemaLike}.
+ *
+ * Returns `undefined` when the schema cannot be compiled (JSON Schema is wider
+ * than Zod can express). Callers treat that as "no contract to check" rather
+ * than failing: refusing data because we could not build the validator would be
+ * worse than the unchecked pass-through this replaces.
+ */
+export declare function compileJsonSchema(jsonSchema: unknown): z4.ZodType | undefined;
+/**
+ * Decomposes an object {@link SchemaLike} into its declared fields, each mapped
+ * to a validator for that field alone.
+ *
+ * This is what lets a *partial* object be checked key by key. A state schema
+ * declares the keys a workflow may write, but the state holds only the ones
+ * written so far, so validating the whole object against the schema would
+ * reject it for missing fields that simply have not been set yet.
+ *
+ * Returns `undefined` when the schema is not an object schema or cannot be
+ * decomposed, and maps a field to `undefined` when that field's own schema has
+ * no Zod equivalent. Both mean "unvalidatable" rather than invalid, consistent
+ * with {@link parseWithSchema}.
+ */
+export declare function objectSchemaFields(schema: SchemaLike): Map<string, z4.ZodType | undefined> | undefined;

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

@@ -6,8 +6,16 @@
 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>;
+/** 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. */
+export declare function isZodV3Schema(obj: unknown): obj is z3.ZodTypeAny;
+/** Returns true if the value is a Zod v4 schema. */
+export declare function isZodV4Schema(obj: unknown): obj is z4.ZodType;
 /**
  * Returns true if the given object is a ZodObject (supports both Zod v3 and v4).
  */
 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/vertex_ai_utils.d.ts

@@ -3,9 +3,14 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+export declare const EXPRESS_MODE_UNSUPPORTED_MESSAGE: string;
 /**
  * Validates and returns the API key for Express Mode.
  *
+ * The key is only returned when enterprise mode is enabled via
+ * `GOOGLE_GENAI_USE_ENTERPRISE` (or the deprecated
+ * `GOOGLE_GENAI_USE_VERTEXAI`).
+ *
  * @param project The project id.
  * @param location The location.
  * @param expressModeApiKey The API key for Express Mode.