@google/adk 1.4.0 → 1.6.0

package/dist/types/sessions/in_memory_session_service.d.ts

@@ -7,6 +7,15 @@ import { Session } from './session.js';
 export declare function isInMemoryConnectionString(uri?: string): boolean;
 /**
  * An in-memory implementation of the session service.
+ *
+ * Every map below is keyed by untrusted input — `appName`, `userId`,
+ * `sessionId` and state keys all arrive straight off the request path or body
+ * on a dev server — so each is created with `Object.create(null)`. On an
+ * ordinary `{}` literal a key of `__proto__` resolves to the inherited
+ * `__proto__` accessor instead of creating an own property, so
+ * `map[appName][userId] = ...` writes onto `Object.prototype` and pollutes
+ * every object in the process. A null-prototype map has no such accessor, so
+ * those keys become ordinary own properties.
  */
 export declare class InMemorySessionService extends BaseSessionService {
     /**

package/dist/types/sessions/vertex_ai_session_service.d.ts

@@ -26,6 +26,19 @@ export interface VertexAiSessionServiceOptions {
     expressModeApiKey?: string;
     sessions?: Sessions;
 }
+/**
+ * The parameters for `VertexAiSessionService.createSession`.
+ *
+ * Extends the common {@link CreateSessionRequest} with the mutually exclusive
+ * session-expiration options supported by Vertex AI Agent Engine Sessions. See
+ * https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1beta1/projects.locations.reasoningEngines.sessions
+ */
+export interface VertexAiCreateSessionRequest extends CreateSessionRequest {
+    /** Lifetime relative to creation, in seconds, e.g. `'7200s'`. */
+    ttl?: string;
+    /** Absolute RFC 3339 UTC expiration, e.g. `'2025-10-01T00:00:00Z'`. */
+    expireTime?: string;
+}
 /**
  * A session service implementation that integrates with Vertex AI Agent Engine Sessions.
  */
@@ -37,7 +50,12 @@ export declare class VertexAiSessionService extends BaseSessionService {
     private location?;
     constructor(options: VertexAiSessionServiceOptions);
     private getReasoningEngineId;
-    createSession({ appName, userId, state, sessionId, }: CreateSessionRequest): Promise<Session>;
+    /**
+     * Creates a session on Vertex AI Agent Engine.
+     *
+     * @throws if both `ttl` and `expireTime` are specified.
+     */
+    createSession({ appName, userId, state, sessionId, ttl, expireTime, }: VertexAiCreateSessionRequest): Promise<Session>;
     getSession({ appName, userId, sessionId, config, }: GetSessionRequest): Promise<Session | undefined>;
     listSessions({ appName, userId, limit, offset, page, order, }: ListSessionsRequest): Promise<ListSessionsResponse>;
     deleteSession({ appName, userId, sessionId, }: DeleteSessionRequest): Promise<void>;

package/dist/types/skills/loader.d.ts

@@ -39,7 +39,12 @@ export declare function loadAllSkillsInDir(skillsBasePath: string): Promise<Reco
 /**
  * Loads a complete skill directly from in-memory zip file buffer.
  *
+ * The whole archive is rejected if any member name escapes the extraction
+ * root, and the skill name must be a bare path segment.
+ *
  * @param zipBuffer - The raw Buffer of the zip file containing the skill.
  * @returns A Skill object with all components loaded.
+ * @throws {Error} If a member name is a traversal path, if SKILL.md is missing,
+ * or if the skill name is missing or is not a bare path segment.
  */
 export declare function loadSkillFromZipBuffer(zipBuffer: Buffer): Skill;

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

@@ -0,0 +1,26 @@
+import { LlmRequest } from '../models/llm_request.js';
+import { BaseTool, ToolProcessLlmRequest } from './base_tool.js';
+/**
+ * Appends the Enterprise Web Search built-in tool to the LLM request when the
+ * target model supports it.
+ *
+ * NOTE: This is NOT Vertex AI Search (formerly "Enterprise Search"). See
+ * https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/web-grounding-enterprise
+ */
+export declare function applyEnterpriseWebSearch(llmRequest: LlmRequest): void;
+/**
+ * A Gemini 2+ built-in tool that grounds responses on public web data via
+ * Vertex AI Search with Enterprise (Sec4) compliance.
+ *
+ * This tool operates internally within the model and does not require or
+ * perform local code execution.
+ */
+export declare class EnterpriseWebSearchTool extends BaseTool {
+    constructor();
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+}
+/**
+ * A global instance of {@link EnterpriseWebSearchTool}.
+ */
+export declare const ENTERPRISE_WEB_SEARCH: EnterpriseWebSearchTool;

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseExampleProvider } from '../examples/base_example_provider.js';
+import { Example } from '../examples/example.js';
+import { BaseTool, RunAsyncToolRequest, ToolProcessLlmRequest } from './base_tool.js';
+/**
+ * A tool that adds (few-shot) examples to the LLM request.
+ *
+ * This tool is executed for each LLM request and is never called by the model;
+ * it only mutates the outgoing request by appending few-shot instructions built
+ * from the latest user query.
+ */
+export declare class ExampleTool extends BaseTool {
+    readonly examples: Example[] | BaseExampleProvider;
+    constructor(examples: Example[] | BaseExampleProvider);
+    runAsync(_request: RunAsyncToolRequest): Promise<unknown>;
+    processLlmRequest({ toolContext, llmRequest, }: ToolProcessLlmRequest): Promise<void>;
+}

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/load_web_page.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { z } from 'zod';
+import { FunctionTool } from './function_tool.js';
+/** Options for {@link loadWebPage}. */
+export interface LoadWebPageOptions {
+    /** Request timeout in milliseconds. Defaults to 30_000 (30s). */
+    timeoutMs?: number;
+}
+/**
+ * Fetches the content at `url` and returns its extracted, readable text.
+ *
+ * Hardened against SSRF: only `http`/`https` URLs are fetched, the host is
+ * resolved and rejected up front if it is `localhost`-style or resolves to a
+ * private / loopback / link-local / shared / reserved / multicast address, and
+ * redirects are never followed. Never throws for expected failures (bad scheme,
+ * blocked host, non-200, timeout, network error); returns
+ * `Failed to fetch url: <url>` instead.
+ *
+ * Known limitation: global `fetch` performs its own DNS resolution at connect
+ * time, so a residual time-of-check/time-of-use (DNS-rebinding) window exists
+ * between this pre-flight lookup and fetch's own lookup. Full connection
+ * IP-pinning (e.g. an `undici` Agent with a custom `lookup`) is a possible
+ * future hardening.
+ */
+export declare function loadWebPage(url: string, options?: LoadWebPageOptions): Promise<string>;
+/** A global {@link FunctionTool} exposing {@link loadWebPage} to the model. */
+export declare const LOAD_WEB_PAGE: FunctionTool<z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>>;

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

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest, ToolProcessLlmRequest } from '../base_tool.js';
+import { MCPToolset } from './mcp_toolset.js';
+/**
+ * A tool that loads MCP server resources and adds them to the session.
+ *
+ * This mirrors the in-repo `LoadArtifactsTool` idiom: the model calls
+ * `load_mcp_resource` with the names of the resources it wants, and on the next
+ * turn {@link processLlmRequest} reads those resources over the MCP session and
+ * appends their contents (text and base64-encoded binary) to the request
+ * context.
+ */
+export declare class LoadMcpResourceTool extends BaseTool {
+    private readonly mcpToolset;
+    constructor(mcpToolset: MCPToolset);
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ args }: RunAsyncToolRequest): Promise<unknown>;
+    processLlmRequest(request: ToolProcessLlmRequest): Promise<void>;
+    private appendResourcesToLlmRequest;
+    private mcpContentToPart;
+}

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

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { 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';
@@ -40,5 +41,31 @@ export declare class MCPToolset extends BaseToolset {
     private readonly mcpSessionManager;
     constructor(connectionParams: MCPConnectionParams, toolFilter?: ToolPredicate | string[], prefix?: string);
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+    /**
+     * Lists the names of the resources advertised by the MCP server.
+     *
+     * @return The resource names available on the server.
+     */
+    listResources(): Promise<string[]>;
+    /**
+     * Returns metadata for the resource whose name matches `name`.
+     *
+     * @param name The advertised name of the resource.
+     * @return The matching MCP `Resource`.
+     * @throws If no resource with the given name is advertised by the server.
+     */
+    getResourceInfo(name: string): Promise<Resource>;
+    /**
+     * Reads the contents of the named resource from the MCP server.
+     *
+     * The resource name is resolved to a URI via {@link getResourceInfo} before
+     * reading. Binary contents are returned base64-encoded, exactly as provided
+     * by the server (never decoded and re-encoded).
+     *
+     * @param name The advertised name of the resource to read.
+     * @return The resource contents (text and/or base64-encoded binary).
+     * @throws If the resource is unknown or has no URI.
+     */
+    readResource(name: string): Promise<Array<TextResourceContents | BlobResourceContents>>;
     close(): Promise<void>;
 }

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

@@ -0,0 +1,15 @@
+/**
+ * @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.
+ */
+export declare const requestInputTool: LongRunningFunctionTool<z.ZodObject<{
+    message: z.ZodString;
+    responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>>;

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

@@ -6,9 +6,34 @@
 import { FunctionDeclaration } from '@google/genai';
 import { BaseTool, RunAsyncToolRequest } from '../base_tool.js';
 import { SkillToolset } from './skill_toolset.js';
+/**
+ * Error codes returned by {@link RunSkillInlineScriptTool} when a call cannot
+ * be completed. The string values are part of the tool's response contract and
+ * must remain stable.
+ */
+export declare enum RunSkillInlineScriptErrorCode {
+    MISSING_SCRIPT_CONTENT = "MISSING_SCRIPT_CONTENT",
+    MISSING_LANGUAGE = "MISSING_LANGUAGE",
+    NO_CODE_EXECUTOR = "NO_CODE_EXECUTOR",
+    EXECUTION_ERROR = "EXECUTION_ERROR",
+    CONFIRMATION_REJECTED = "CONFIRMATION_REJECTED"
+}
 export declare class RunSkillInlineScriptTool extends BaseTool {
     private toolset;
     constructor(toolset: SkillToolset);
     _getDeclaration(): FunctionDeclaration;
     runAsync({ args, toolContext, }: RunAsyncToolRequest): Promise<unknown>;
+    /**
+     * Enforces a human-in-the-loop confirmation gate before executing an inline
+     * script, using the repo's standard tool-confirmation mechanism.
+     *
+     * - When no confirmation has been provided yet, a confirmation is requested
+     *   (surfacing the language and script that would run) and an intermediate
+     *   result is returned so the tool call pauses until the client responds.
+     * - When a confirmation exists but was not confirmed, a rejection error is
+     *   returned and execution is refused.
+     * - When the confirmation is confirmed, `undefined` is returned to allow the
+     *   caller to proceed with execution.
+     */
+    private enforceConfirmation;
 }

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

@@ -23,6 +23,15 @@ export declare class SkillToolset extends BaseToolset {
         codeExecutor?: BaseCodeExecutor;
         additionalTools?: Array<BaseTool | BaseToolset>;
         registry?: SkillRegistry;
+        /**
+         * Whether to expose the `run_skill_inline_script` tool, which executes
+         * model-provided script content in the configured code executor. This is
+         * disabled by default because arbitrary inline-script execution is a
+         * sensitive capability; opt in explicitly by setting this to `true`.
+         * Execution additionally remains gated behind a human-in-the-loop
+         * confirmation.
+         */
+        allowInlineScripts?: boolean;
     });
     getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
     close(): Promise<void>;

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

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Checks whether targetBranch is equal to or an ancestor of currentBranch
+ * by verifying segment-by-segment matching without substring false positives.
+ *
+ * @param currentBranch The branch being evaluated.
+ * @param targetBranch The candidate prefix or ancestor branch.
+ * @returns true if targetBranch equals currentBranch or is an ancestor of currentBranch.
+ */
+export declare function isSegmentPrefix(currentBranch: string, targetBranch: string): boolean;

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/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.

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/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/vertex_ai_utils.d.ts

@@ -3,6 +3,7 @@
  * 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.
  *

package/dist/types/version.d.ts

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

package/dist/web/a2a/a2a_remote_agent.js

@@ -127,7 +127,12 @@ class RemoteA2AAgent extends BaseAgent {
                   yield new __await(callback(context, chunk));
                 }
               }
-              const adkEvent = toAdkEvent(chunk, context.invocationId, this.name);
+              const adkEvent = toAdkEvent(
+                chunk,
+                context.invocationId,
+                this.name,
+                context.branch
+              );
               if (!adkEvent) {
                 continue;
               }
@@ -158,7 +163,12 @@ class RemoteA2AAgent extends BaseAgent {
               yield new __await(callback(context, result));
             }
           }
-          const adkEvent = toAdkEvent(result, context.invocationId, this.name);
+          const adkEvent = toAdkEvent(
+            result,
+            context.invocationId,
+            this.name,
+            context.branch
+          );
           if (adkEvent) {
             processor.updateCustomMetadata(adkEvent, result);
             yield adkEvent;

package/dist/web/a2a/agent_to_a2a.js

@@ -16,10 +16,26 @@ import {
 import express from "express";
 import { StreamingMode } from "../agents/run_config.js";
 import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
+import { logger } from "../utils/logger.js";
 import { getA2AAgentCard, resolveAgentCard } from "./agent_card.js";
 import { A2AAgentExecutor } from "./agent_executor.js";
+function resolveA2aUserBuilder(options) {
+  if (options.authentication) {
+    return options.authentication;
+  }
+  if (options.allowUnauthenticated === true) {
+    logger.warn(
+      "SECURITY WARNING: Mounting the A2A server WITHOUT authentication because `allowUnauthenticated: true` was set. The agent and all of its tools are exposed to any network-reachable caller, which can invoke them with arbitrary input and read the output. Do NOT use this outside of local, trusted development."
+    );
+    return UserBuilder.noAuthentication;
+  }
+  throw new Error(
+    "toA2a: refusing to mount the A2A server without authentication. The A2A surface lets any network-reachable caller invoke this agent and its tools with arbitrary input and read the output, so it must be authenticated. Provide `authentication` (a UserBuilder that validates the request, e.g. a bearer token or OIDC credential) or, only for local/trusted development, explicitly set `allowUnauthenticated: true`."
+  );
+}
 async function toA2a(agent, options = {}) {
   var _a, _b, _c, _d;
+  const userBuilder = resolveA2aUserBuilder(options);
   const host = (_a = options.host) != null ? _a : "localhost";
   const port = (_b = options.port) != null ? _b : 8e3;
   const protocol = (_c = options.protocol) != null ? _c : "http";
@@ -54,7 +70,6 @@ async function toA2a(agent, options = {}) {
   );
   const app = (_d = options.app) != null ? _d : express();
   if (!options.app) {
-    app.use(express.urlencoded({ limit: "50mb", extended: true }));
     app.use(express.json({ limit: "50mb" }));
   }
   app.use(
@@ -65,14 +80,14 @@ async function toA2a(agent, options = {}) {
     "".concat(basePath, "/rest"),
     restHandler({
       requestHandler,
-      userBuilder: UserBuilder.noAuthentication
+      userBuilder
     })
   );
   app.use(
     "".concat(basePath, "/jsonrpc"),
     jsonRpcHandler({
       requestHandler,
-      userBuilder: UserBuilder.noAuthentication
+      userBuilder
     })
   );
   return app;

package/dist/web/a2a/auth.js

@@ -0,0 +1,37 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { timingSafeEqual } from "node:crypto";
+const AUTHENTICATED_USER_NAME = "a2a-bearer-token";
+const BEARER_SCHEME_PREFIX = "bearer ";
+function timingSafeEqualStrings(a, b) {
+  const left = Buffer.from(a, "utf8");
+  const right = Buffer.from(b, "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function bearerTokenUserBuilder(token) {
+  const expected = token.trim();
+  if (!expected) {
+    throw new Error(
+      "bearerTokenUserBuilder: an empty A2A bearer token is not a valid authenticator. Supply a real shared secret, or configure no token at all to run the A2A surface unauthenticated."
+    );
+  }
+  return async (req) => {
+    var _a;
+    const header = (_a = req.headers.authorization) != null ? _a : "";
+    const credential = header.toLowerCase().startsWith(BEARER_SCHEME_PREFIX) ? header.slice(BEARER_SCHEME_PREFIX.length) : "";
+    if (!timingSafeEqualStrings(credential, expected)) {
+      throw new Error(
+        "A2A request rejected: missing or invalid `Authorization: Bearer` credential."
+      );
+    }
+    return { isAuthenticated: true, userName: AUTHENTICATED_USER_NAME };
+  };
+}
+export {
+  bearerTokenUserBuilder
+};