@google/adk 1.6.0 → 2.1.0

package/dist/types/agents/user_input_request.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Inspection helpers for the "paused, waiting on a human" state.
+ *
+ * A pause is not visible in an event's text: it is carried in a `functionCall`
+ * part named `adk_request_*`, with the prompt buried in that call's `args`. A
+ * client that renders only text parts therefore shows the user nothing while
+ * the run sits blocked. These helpers flatten the three encodings into one
+ * shape so a caller need not know how each kind stores its id and prompt.
+ */
+import { AuthConfig } from '../auth/auth_tool.js';
+import { Event } from '../events/event.js';
+/**
+ * What a paused run is waiting for.
+ *
+ * - `input`: free-form or structured data (`RequestInput`).
+ * - `credential`: an auth credential, e.g. an API key or an OAuth flow.
+ * - `confirmation`: approval to run a tool guarded by `requireConfirmation`.
+ */
+export type UserInputKind = 'input' | 'credential' | 'confirmation';
+/** A single request for user input carried by an event. */
+export interface UserInputRequest {
+    kind: UserInputKind;
+    /**
+     * The id that answers this request: reply with a `functionResponse` carrying
+     * this same id (and {@link functionCallName}).
+     */
+    interruptId: string;
+    /** The name to answer with, alongside {@link interruptId}. */
+    functionCallName: string;
+    /** The node or agent that raised the request. */
+    author?: string;
+    /**
+     * Human-readable prompt for the user. Populated for every kind: the
+     * `RequestInput` message, the credential prompt, or the tool-confirmation
+     * hint. Absent when the raiser supplied none.
+     */
+    message?: string;
+    /** Structured data attached to the request (`RequestInput.payload`). */
+    payload?: unknown;
+    /** JSON schema the reply is expected to satisfy, when declared. */
+    responseSchema?: unknown;
+    /** `confirmation` only: the tool awaiting approval. */
+    toolName?: string;
+    /** `credential` only: the auth config to complete. */
+    authConfig?: AuthConfig;
+}
+/**
+ * Returns every user-input request carried by a single event, in part order.
+ *
+ * This reports what the event *asks for*; it does not know whether the request
+ * was later answered. Use {@link getPendingUserInputRequests} over a session's
+ * events to get only the ones still outstanding.
+ */
+export declare function getUserInputRequests(event: Event): UserInputRequest[];
+/** Whether this event asks the user for something. */
+export declare function requiresUserInput(event: Event): boolean;
+/**
+ * Returns the requests across a sequence of events that have not been answered
+ * yet, in the order they were raised.
+ *
+ * A request is answered by a later `functionResponse` part carrying the same
+ * id, which is how a resumed session records the user's reply. Pass a session's
+ * events to answer "is this session waiting on the user right now, and for
+ * what?".
+ */
+export declare function getPendingUserInputRequests(events: readonly Event[]): UserInputRequest[];

package/dist/types/apps/app.d.ts

@@ -3,8 +3,8 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { BaseAgent } from '../agents/base_agent.js';
 import { BasePlugin } from '../plugins/base_plugin.js';
+import { RunnableRoot } from '../workflow/run_node_as_invocation.js';
 import { ResumabilityConfig } from './resumability_config.js';
 /**
  * Ensures the provided application name is safe and intuitive.
@@ -26,7 +26,12 @@ export declare function isApp(obj: unknown): obj is App;
  */
 export interface AppOptions {
     name: string;
-    rootAgent: BaseAgent;
+    /**
+     * The root of the application. A bare node — a `Workflow`, most usefully —
+     * is accepted and adapted, so a graph does not have to be wrapped by hand to
+     * be an app root. Accepts the same set a `Runner` does.
+     */
+    rootAgent: RunnableRoot;
     plugins?: BasePlugin[];
     resumabilityConfig?: ResumabilityConfig;
 }
@@ -44,7 +49,7 @@ export interface AppOptions {
 export declare class App {
     readonly [APP_SIGNATURE_SYMBOL] = true;
     readonly name: string;
-    readonly rootAgent: BaseAgent | any;
+    readonly rootAgent: RunnableRoot;
     readonly plugins: BasePlugin[];
     readonly resumabilityConfig?: ResumabilityConfig;
     constructor(options: AppOptions);

package/dist/types/artifacts/gcs_artifact_service.d.ts

@@ -3,12 +3,19 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { StorageOptions } from '@google-cloud/storage';
+import type { StorageOptions } from '@google-cloud/storage';
 import { Part } from '@google/genai';
 import { ArtifactVersion, BaseArtifactService, DeleteArtifactRequest, ListArtifactKeysRequest, ListVersionsRequest, LoadArtifactRequest, SaveArtifactRequest } from './base_artifact_service.js';
 export declare class GcsArtifactService implements BaseArtifactService {
-    private readonly bucket;
+    private readonly bucketName;
+    private readonly storageOptions?;
+    private bucketPromise?;
     constructor(bucket: string, options?: StorageOptions);
+    /**
+     * Resolves the GCS bucket handle, loading the `@google-cloud/storage`
+     * optional peer on first use.
+     */
+    private getBucket;
     saveArtifact(request: SaveArtifactRequest): Promise<number>;
     loadArtifact(request: LoadArtifactRequest): Promise<Part | undefined>;
     listArtifactKeys(request: ListArtifactKeysRequest): Promise<string[]>;

package/dist/types/artifacts/scoped_artifact_service.d.ts

@@ -6,6 +6,14 @@
 import { Part } from '@google/genai';
 import { ArtifactVersion, BaseArtifactService } from './base_artifact_service.js';
 import { SessionArtifactService, SessionLoadArtifactRequest, SessionSaveArtifactRequest } from './session_artifact_service.js';
+/**
+ * A unique symbol to identify session-scoped artifact services.
+ *
+ * Resolves to the same symbol as the one used by `isSessionArtifactService` in
+ * `session_artifact_service.ts` because `Symbol.for` looks up the global
+ * symbol registry.
+ */
+declare const SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL: unique symbol;
 /**
  * A wrapper that scopes a BaseArtifactService to a specific session.
  */
@@ -14,6 +22,10 @@ export declare class ScopedArtifactService implements SessionArtifactService {
     private readonly appName;
     private readonly userId;
     private readonly sessionId;
+    /**
+     * Brands this class as a session-scoped artifact service.
+     */
+    readonly [SESSION_ARTIFACT_SERVICE_SIGNATURE_SYMBOL] = true;
     constructor(delegate: BaseArtifactService, appName: string, userId: string, sessionId: string);
     saveArtifact(request: SessionSaveArtifactRequest): Promise<number>;
     loadArtifact(request: SessionLoadArtifactRequest): Promise<Part | undefined>;
@@ -23,3 +35,4 @@ export declare class ScopedArtifactService implements SessionArtifactService {
     listArtifactVersions(filename: string): Promise<ArtifactVersion[]>;
     getArtifactVersion(request: SessionLoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }
+export {};

package/dist/types/artifacts/session_artifact_service.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Part } from '@google/genai';
-import { ArtifactVersion } from './base_artifact_service.js';
+import { ArtifactVersion, BaseArtifactService } from './base_artifact_service.js';
 export interface SessionSaveArtifactRequest {
     filename: string;
     artifact: Part;
@@ -23,3 +23,10 @@ export interface SessionArtifactService {
     listArtifactVersions(filename: string): Promise<ArtifactVersion[]>;
     getArtifactVersion(request: SessionLoadArtifactRequest): Promise<ArtifactVersion | undefined>;
 }
+/**
+ * Type guard to check if an object implements SessionArtifactService.
+ *
+ * @param service The artifact service to check.
+ * @returns True if the service is a session-scoped artifact service.
+ */
+export declare function isSessionArtifactService(service: BaseArtifactService | SessionArtifactService): service is SessionArtifactService;

package/dist/types/auth/auth_credential.d.ts

@@ -43,6 +43,11 @@ export interface OAuth2Auth {
     nonce?: string;
     state?: string;
     codeVerifier?: string;
+    /**
+     * The PKCE code challenge method. Only 'S256' is supported; any other value
+     * is rejected when the authorization URI is generated.
+     */
+    codeChallengeMethod?: string;
     /**
      * tool or adk can decide the redirect_uri if they don't want client to decide
      */
@@ -60,7 +65,7 @@ export interface OAuth2Auth {
 /**
  * Represents Google Service Account configuration.
  * @example
- * config = {
+ * const config: ServiceAccountCredential = {
  *   type: "service_account",
  *   projectId: "your_project_id",
  *   privateKeyId: "your_private_key_id",
@@ -72,7 +77,7 @@ export interface OAuth2Auth {
  *   authProviderX509CertUrl: "https://www.googleapis.com/oauth2/v1/certs",
  *   clientX509CertUrl: "https://www.googleapis.com/robot/v1/metadata/x509/...",
  *   universeDomain: "googleapis.com",
- * }
+ * };
  */
 export interface ServiceAccountCredential {
     /**
@@ -164,10 +169,11 @@ export declare enum AuthCredentialTypes {
     SERVICE_ACCOUNT = "serviceAccount"
 }
 /**
- * Data class representing an authentication credential.
+ * An authentication credential, in one of several shapes selected by
+ * `authType`.
  *
- * To exchange for the actual credential, please use
- * CredentialExchanger.exchangeCredential().
+ * To turn one of these into the credential a request actually carries, use the
+ * `exchange()` method of a {@link BaseCredentialExchanger}.
  *
  * @example
  * // API Key Auth
@@ -211,7 +217,7 @@ export declare enum AuthCredentialTypes {
  *   }
  * }
  *
- * @example:
+ * @example
  * // Open ID Connect Auth
  * const authCredential: AuthCredential = {
  *   authType: AuthCredentialTypes.OPEN_ID_CONNECT,
@@ -219,11 +225,10 @@ export declare enum AuthCredentialTypes {
  *     clientId: "1234",
  *     clientSecret: "secret",
  *     redirectUri: "https://example.com",
- *     scopes: ["scope1", "scope2"],
  *   }
  * }
  *
- * @example:
+ * @example
  * // Auth with resource reference
  * const authCredential: AuthCredential = {
  *   authType: AuthCredentialTypes.API_KEY,

package/dist/types/auth/auth_handler.d.ts

@@ -15,14 +15,25 @@ export declare class AuthHandler {
     private readonly authConfig;
     constructor(authConfig: AuthConfig);
     getAuthResponse(state: State): AuthCredential | undefined;
+    /**
+     * Stores the exchanged credential in the session state.
+     *
+     * @param state The session state to store the credential in.
+     * @throws Error: If the auth config has no credentialKey.
+     */
     parseAndStoreAuthResponse(state: State): Promise<void>;
     generateAuthRequest(): AuthConfig;
     /**
      * Generates an response containing the auth uri for user to sign in.
      *
+     * When the credential requests PKCE, the URI also carries the S256 code
+     * challenge derived from the credential's code verifier, and the returned
+     * credential carries the verifier the later token exchange must send.
+     *
      * @return An AuthCredential object containing the auth URI and state.
      * @throws Error: If the authorization endpoint is not configured in the
-     *     auth scheme.
+     *     auth scheme, or the credential requests a code challenge method other
+     *     than 'S256'.
      */
     generateAuthUri(): AuthCredential | undefined;
 }

package/dist/types/auth/credential_response_binding.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthConfig } from './auth_tool.js';
+/**
+ * Reconciles a credential response with the request that asked for it.
+ *
+ * The request is agent-authored and defines the question: which scheme, from
+ * which authorization server, under which key, on behalf of which client. The
+ * response is client-authored and carries one thing — the credential material
+ * the user obtained. Everything else it contains is discarded, because a
+ * response that gets to restate the question also decides whether the
+ * credential is exchanged at all, where the exchange sends the client secret,
+ * and which waiting tool picks the result up.
+ *
+ * The request is typed loosely on purpose: it is read back off the wire out of
+ * a function call's args, so it can arrive missing the fields its type
+ * promises. Returns `undefined` when it is too incomplete to be an authority,
+ * or when the response carries nothing that answers it — either way there is
+ * nothing that can safely be stored.
+ */
+export declare function bindCredentialResponse(request: Partial<AuthConfig>, response: unknown): AuthConfig | undefined;

package/dist/types/auth/oauth2/oauth2_credential_refresher.d.ts

@@ -15,7 +15,7 @@ export declare class OAuth2CredentialRefresher implements BaseCredentialRefreshe
      *
      * @param authCredential The OAuth2 credential to check.
      * @param authScheme The OAuth2 authentication scheme (optional).
-     * @returns True if the credential needs to be refreshed, False otherwise.
+     * @returns True if the credential needs to be refreshed, false otherwise.
      */
     isRefreshNeeded(authCredential: AuthCredential): Promise<boolean>;
     /**

package/dist/types/auth/oauth2/oauth2_utils.d.ts

@@ -5,6 +5,15 @@
  */
 import { OAuth2Auth } from '../auth_credential.js';
 import { AuthScheme } from '../auth_schemes.js';
+/**
+ * Generates a cryptographically secure PKCE code verifier (RFC 7636).
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Derives the S256 PKCE code challenge for a code verifier (RFC 7636): the
+ * unpadded base64url encoding of the verifier's SHA-256 digest.
+ */
+export declare function createS256CodeChallenge(codeVerifier: string): string;
 /**
  * Returns the token endpoint for the given auth scheme.
  */

package/dist/types/auth/refresher/base_credential_refresher.d.ts

@@ -23,7 +23,7 @@ export interface BaseCredentialRefresher {
      *
      * @param authCredential The credential to check.
      * @param authScheme The authentication scheme (optional).
-     * @returns True if the credential needs to be refreshed, False otherwise.
+     * @returns True if the credential needs to be refreshed, false otherwise.
      */
     isRefreshNeeded(authCredential: AuthCredential, authScheme?: AuthScheme): Promise<boolean>;
     /**

package/dist/types/code_executors/code_execution_utils.d.ts

@@ -97,7 +97,7 @@ export declare function getEncodedFileContent(data: string): string;
  * @param content The mutable content to extract the code from.
  * @param codeBlockDelimiters The list of the enclosing delimiters to identify
  *     the code blocks.
- * @return The first code block if found, otherwise None.
+ * @return The first code block if found, otherwise an empty string.
  */
 export declare function extractCodeAndTruncateContent(content: Content, codeBlockDelimiters: Array<[string, string]>): string;
 /**

package/dist/types/code_executors/container_code_executor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type Docker from 'dockerode';
+import { BaseCodeExecutor, ExecuteCodeParams } from './base_code_executor.js';
+import { CodeExecutionResult } from './code_execution_utils.js';
+/**
+ * Options for {@link ContainerCodeExecutor}.
+ */
+export interface ContainerCodeExecutorOptions {
+    /** Optional base url of a user-hosted Docker daemon (e.g. `tcp://host:2375`). */
+    baseUrl?: string;
+    /**
+     * Tag of the predefined or custom image to run on the container. Either
+     * `image` or `dockerPath` must be set. Defaults to `adk-code-executor:latest`
+     * when only `dockerPath` is given.
+     */
+    image?: string;
+    /**
+     * Path to a directory containing a Dockerfile. If set, the image is built
+     * from it instead of using a prebuilt tag. Either `image` or `dockerPath`
+     * must be set.
+     */
+    dockerPath?: string;
+    /**
+     * Start the container with networking enabled. Defaults to false so
+     * untrusted, model-generated code cannot reach the network (the cloud
+     * metadata endpoint, internal services, or exfiltration destinations).
+     */
+    networkEnabled?: boolean;
+    /**
+     * Wall-clock timeout in seconds for a single execution. Must be greater than
+     * 0; defaults to 300. Every execution shares one long-lived container, so an
+     * unbounded run (e.g. a loop emitted by the model) would burn that
+     * container's CPU for every later caller. Raise it rather than remove it for
+     * a computation that legitimately runs longer.
+     */
+    timeoutSeconds?: number;
+    /**
+     * Injected Docker client, primarily for testing so unit tests never touch a
+     * real Docker daemon. Defaults to a new client built from `baseUrl`.
+     */
+    docker?: Docker;
+}
+/**
+ * A code executor that runs model-generated code inside a hardened Docker
+ * container via the `dockerode` client.
+ *
+ * Security note: this executor runs model-generated code, which may be
+ * influenced by untrusted input (e.g. via prompt injection). By default the
+ * container is started with networking disabled and all Linux capabilities
+ * dropped so the executed code cannot reach the network (including the cloud
+ * metadata endpoint at `169.254.169.254`) or escalate privileges. Networking
+ * can be re-enabled via `networkEnabled: true` when the executed code is
+ * trusted.
+ *
+ * Limitations: this executor runs a code string only. `inputFiles` and `args`
+ * on the request are not copied into the container, and output files are not
+ * collected (`outputFiles` is always empty), so tools that stage resource
+ * files or read artifacts back (e.g. `RunSkillScriptTool`) are not yet
+ * supported. Sending files in and out via `putArchive`/`getArchive` is future
+ * work.
+ */
+export declare class ContainerCodeExecutor extends BaseCodeExecutor {
+    private readonly dockerPath?;
+    private readonly containerOptions;
+    private readonly timeoutSeconds;
+    private container?;
+    private initPromise?;
+    constructor(options?: ContainerCodeExecutorOptions);
+    executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult>;
+    /**
+     * Turns a non-zero exit into stderr the model can see. An empty stderr maps
+     * to `OUTCOME_OK` downstream, so a program that exits non-zero without
+     * writing stderr would otherwise look successful (matching
+     * `UnsafeLocalCodeExecutor`).
+     */
+    private describeExit;
+    /**
+     * Stops and removes the container. Safe to call when no container has been
+     * started; provided for deterministic teardown in tests and app shutdown.
+     */
+    close(): Promise<void>;
+    /** Lazily builds/starts the container exactly once. */
+    private ensureContainer;
+    private initContainer;
+}

package/dist/types/code_executors/docker_container.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type Docker from 'dockerode';
+/**
+ * Exit code reported when a run is killed for exceeding its deadline. Matches
+ * the convention of coreutils `timeout(1)`, which the executor uses to bound a
+ * run inside the container.
+ */
+export declare const TIMEOUT_EXIT_CODE = 124;
+/** Decoded output of a single command executed inside the container. */
+export interface ExecOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+/** Options for {@link DockerContainer}. */
+export interface DockerContainerOptions {
+    /** Tag of the predefined or custom image to run on the container. */
+    image: string;
+    /**
+     * Start the container with networking enabled. When false, the container
+     * cannot reach the network, which is the safe default for untrusted code.
+     */
+    networkEnabled: boolean;
+    /** Optional base url of a user-hosted Docker daemon. */
+    baseUrl?: string;
+    /**
+     * Injected Docker client. When omitted, dockerode is loaded lazily and a
+     * client is built from `baseUrl`.
+     */
+    docker?: Docker;
+}
+/**
+ * The Docker container backing a code executor, wrapping the whole lifecycle
+ * (`build` -> `start` -> `execute` -> `stop`) and the Docker client resolution
+ * behind one small API, so callers only decide *what* to run, not *how* to
+ * drive Docker.
+ */
+export declare class DockerContainer {
+    private readonly options;
+    private client?;
+    private container?;
+    constructor(options: DockerContainerOptions);
+    /**
+     * Builds the image from a directory containing a Dockerfile. `src` is the raw
+     * directory listing; unlike the Docker CLI this does not honor
+     * `.dockerignore`.
+     */
+    build(dockerPath: string): Promise<void>;
+    /**
+     * Creates and starts the container, registering it for cleanup on process
+     * exit. Throws if already started: overwriting the handle would orphan the
+     * running container. Call {@link stop} first.
+     */
+    start(): Promise<void>;
+    /**
+     * Runs a command inside the container and returns its decoded output. The
+     * exec is created without a TTY so the stream stays multiplexed and can be
+     * split into stdout and stderr via `modem.demuxStream`.
+     *
+     * `timeoutSeconds` bounds the wait, not the in-container run: a process that
+     * keeps the exec's stdio open (e.g. a surviving background child) means
+     * `'end'` never fires, so without this cap the promise never settles (the
+     * same hang #793 fixed in the local executor). Callers that need to bound the
+     * run itself must wrap the command (see {@link ContainerCodeExecutor}). On a
+     * cap breach the result carries {@link TIMEOUT_EXIT_CODE}.
+     */
+    execute(cmd: string[], timeoutSeconds: number): Promise<ExecOutput>;
+    /** Stops and removes the container. Safe to call when never started. */
+    stop(): Promise<void>;
+    /**
+     * Resolves the Docker client once, lazily loading dockerode when no client
+     * was injected.
+     */
+    private getClient;
+}